Méthode ICustomDestinationList ::AppendKnownCategory (shobjidl_core.h)

Article
03/06/2024

Spécifie que la catégorie Fréquent ou Récent doit être incluse dans une liste de raccourcis personnalisée.

Syntaxe

HRESULT AppendKnownCategory(
  [in] KNOWNDESTCATEGORY category
);

Paramètres

[in] category

Type : KNOWNDESTCATEGORY

L’une des valeurs suivantes qui indique la catégorie connue à ajouter à la liste :

KDC_FREQUENT (1)

0x1. Ajoutez la catégorie Fréquent .

KDC_RECENT (2)

0x2. Ajoutez la catégorie Récent .

Valeur retournée

Type : HRESULT

Retourne S_OK en cas de réussite, ou une valeur d’erreur dans le cas contraire.

S’il existe un stratégie de groupe de confidentialité ou un paramètre de confidentialité utilisateur, cela peut affecter le résultat de cette méthode. Les catégories qui contiennent des éléments spécifiques à l’utilisateur en fonction de l’utilisation individuelle ne sont pas autorisées dans ces paramètres de confidentialité. Pour cette raison, les catégories Récentes ou Fréquentes ajoutées via cette méthode n’auront aucune donnée, et les catégories sans données ne sont pas affichées. Toutefois, dans ce cas, cet appel de méthode n’entraîne pas de code d’échec.

Remarques

Vous devez appeler ICustomDestinationList ::BeginList avant d’appeler cette méthode.

La catégorie Récent est affichée dans une liste de raccourcis par défaut, mais pour l’afficher dans une liste de raccourcis personnalisée avec des catégories personnalisées, vous devez la demander explicitement via cette méthode.

Avec AppendCategory et AppendKnownCategory, une liste de raccourcis personnalisée doit être conçue pour éviter que tout élément apparaisse dans plusieurs catégories. Si deux catégories sont simplement des vues différentes sur les mêmes données, l’une de ces catégories doit être supprimée, car elle utilise l’espace de liste de raccourcis sans contribuer à la commodité de l’utilisateur. Les doublons ne sont pas masqués par le système, sauf dans le cas d’une destination épinglée, auquel cas cette destination est affichée dans la catégorie Épinglée et masquée dans toutes les autres.

Les catégories Fréquents et Récents sont susceptibles de contenir un certain degré de chevauchement. Par conséquent, vous ne devez pas ajouter les deux catégories à une seule liste de raccourcis. Lequel des deux est le mieux adapté à votre application dépend de sa nature. Une application qui génère des fichiers, comme Microsoft Word ou Microsoft Paint, doit utiliser la catégorie Récent, car les utilisateurs sont plus susceptibles de vouloir revenir aux fichiers sur lesquels ils ont récemment travaillé. Une application qui est plus utilisée pour la navigation ou la lecture de données créées ailleurs doit utiliser la catégorie Fréquent , car l’utilisateur est plus susceptible d’accéder à un plus grand nombre d’éléments, beaucoup d’entre eux une seule fois. En d’autres termes, si votre application est la plus susceptible d’accéder à un grand nombre d’éléments seulement quelques fois chacun, ce qui contribue au bruit pour le plus petit ensemble d’éléments que les utilisateurs souhaitent accéder plusieurs fois, alors Fréquent est le meilleur choix. Si votre application est plus susceptible d’accéder à un plus petit nombre d’éléments plus récents la plupart du temps, vous devez choisir Récent.

Les catégories d’une liste de raccourcis personnalisée, y compris la catégorie Récente ou Fréquente connue, sont affichées dans l’ordre dans lequel elles sont ajoutées, avec les catégories les plus récemment ajoutées en bas de la liste.

Le nombre de destinations ajoutées au-dessus de la valeur pointée par le paramètre pcMinItems dans ICustomDestinationList ::BeginList n’est pas affiché.

Les catégories vides ne sont pas affichées.

Le contenu des catégories Frequent et Recent est calculé pour chaque application qui utilise SHAddToRecentDocs directement. Dans certains cas d’action de l’utilisateur, comme l’ouverture d’un fichier via Windows Explorer ou l’utilisation de la boîte de dialogue de fichier commune pour ouvrir, enregistrer ou créer un fichier, l’interpréteur de commandes appelle SHAddToRecentDocs pour le compte d’une application et ces appels sont également pris en compte dans les statistiques d’utilisation. L’interpréteur de commandes appelle également SHAddToRecentDocs pour le compte de l’application lorsqu’une destination est lancée à partir de sa liste de raccourcis. Toutefois, il est recommandé pour l’application d’appeler explicitement SHAddToRecentDocs elle-même, même si l’interpréteur de commandes doit effectuer l’appel. Cela garantit que l’utilisation est enregistrée et que les algorithmes de suivi de l’utilisation récente ou fréquente sont corrects pour les appels en double.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shobjidl_core.h (incluez Shobjidl.h)
Bibliothèque	Shell32.lib
DLL	Shell32.dll (version 6.1 ou ultérieure)