Méthode IShellFolder ::CompareIDs (shobjidl_core.h)

Article
03/06/2024

Détermine l’ordre relatif de deux objets ou dossiers de fichiers, en fonction de leurs listes d’identificateurs d’élément.

Syntaxe

HRESULT CompareIDs(
  [in] LPARAM             lParam,
  [in] PCUIDLIST_RELATIVE pidl1,
  [in] PCUIDLIST_RELATIVE pidl2
);

Paramètres

[in] lParam

Type : LPARAM

Valeur qui spécifie la façon dont la comparaison doit être effectuée.

Les seize bits inférieurs de lParam définissent la règle de tri. La plupart des applications définissent la règle de tri sur la valeur par défaut zéro, ce qui indique que les deux éléments doivent être comparés par nom. Le système ne définit aucune autre règle de tri. Certains objets de dossier peuvent permettre aux applications appelantes d’utiliser les seize bits inférieurs de lParam pour spécifier des règles de tri spécifiques aux dossiers. Les règles et leurs valeurs lParam associées sont définies par le dossier .

Lorsque l’objet d’affichage du dossier système appelle IShellFolder ::CompareIDs, les seize bits inférieurs de lParam sont utilisés pour spécifier la colonne à utiliser pour la comparaison.

Les seize bits supérieurs de lParam sont utilisés pour les indicateurs qui modifient la règle de tri. Le système définit actuellement ces indicateurs de modificateurs.

SHCIDS_ALLFIELDS

Version 5.0. Comparez toutes les informations contenues dans la structure ITEMIDLIST , pas seulement les noms d’affichage. Cet indicateur est valide uniquement pour les objets de dossier qui prennent en charge l’interface IShellFolder2 . Par instance, si les deux éléments sont des fichiers, le dossier doit comparer leurs noms, tailles, heures de fichier, attributs et toute autre information dans les structures. Si cet indicateur est défini, les seize bits inférieurs de lParam doivent être zéro.

SHCIDS_CANONICALONLY

Version 5.0. Lorsque vous comparez par nom, comparez les noms système, mais pas les noms d’affichage. Lorsque cet indicateur est passé, les deux éléments sont comparés selon les critères les plus efficaces que le dossier Shell détermine, tant qu’il implémente une fonction de tri cohérente. Cet indicateur est utile lors de la comparaison pour l’égalité ou lorsque les résultats de ce type ne sont pas affichés à l’utilisateur. Cet indicateur ne peut pas être combiné avec d’autres indicateurs.

[in] pidl1

Type : PCUIDLIST_RELATIVE

Pointeur vers la structure ITEMIDLIST du premier élément. Il sera relatif au dossier. Cette structure ITEMIDLIST peut contenir plusieurs éléments ; par conséquent, l’ensemble de la structure doit être comparé, pas seulement le premier élément.

[in] pidl2

Type : PCUIDLIST_RELATIVE

Pointeur vers la structure ITEMIDLIST du deuxième élément. Il sera relatif au dossier. Cette structure ITEMIDLIST peut contenir plusieurs éléments ; par conséquent, l’ensemble de la structure doit être comparé, pas seulement le premier élément.

Valeur retournée

Type : HRESULT

Si cette méthode réussit, le champ CODE du HRESULT contient l’une des valeurs suivantes. Pour plus d’informations sur l’extraction du champ CODE à partir du HRESULT retourné, consultez Remarques. Si cette méthode échoue, elle retourne un code d’erreur COM.

Code de retour	Description
Négatif	Une valeur de retour négative indique que le premier élément doit précéder le second (pidl1 < pidl2).
Positif	Une valeur de retour positive indique que le premier élément doit suivre le deuxième (pidl1 > pidl2).
Zéro	Une valeur de retour égale à zéro indique que les deux éléments sont identiques (pidl1 = pidl2).

Remarques

Remarque concernant l’appel d’applications

Ne définissez pas l’indicateur SHCIDS_ALLFIELDS dans lParam si l’objet folder ne prend pas en charge IShellFolder2. Cela peut avoir des résultats imprévisibles. Si vous utilisez l’indicateur SHCIDS_ALLFIELDS , les seize bits inférieurs de lParam doivent être définis sur zéro.

Utilisez la macro HRESULT_CODE pour extraire le champ CODE du HRESULT, puis caster le résultat sous la forme d’un court terme.

HRESULT hres = psf->CompareIDs(lParam, pidl1, pidl2);
if ((short)HRESULT_CODE(hres) < 0)
   { /* pidl1 comes first */ }
else if ((short)HRESULT_CODE(hres) > 0) 
   { /* pidl2 comes first */ }
else 
   { /* the two pidls are equal */ }

Remarque à l’attention des implémenteurs

Pour extraire la règle de tri, utilisez un opérateur AND au niveau du bit (&) pour combiner lParam avec SHCIDS_COLUMNMASK (0X0000FFFF). Cette opération masque les seize bits supérieurs de lParam, y compris la valeur SHCIDS_ALLFIELDS .

La macro MAKE_HRESULT est utile pour construire la valeur de retour pour une implémentation de la méthode CompareIDs. Par exemple :

HRESULT CompareIDs(LPARAM lParam, PCUIDLIST_RELATIVE pidl1, PCUIDLIST_RELATIVE pidl2)
{
    short sResult;
    unsigned uSeverity = 0x000000000;
    
    // Code that determines the relative order of pidl1 and pidl2 according to
    // any sorting rules specified by lParam goes here.
    //
    // Set sResult = -1 if pidl1 precedes pidl2 (pidl1 < pidl2).
    // Set sResult =  1 if pidl1 follows pidl2. (pidl1 > pidl2).
    // Set sResult =  0 if pidl1 and pidl2 are equivalent in terms of ordering. (pidl1 = pidl2).
    //
    // Leave uSeverity = 0 if the order is successfully determined.
    // Set uSeverity = 0x00000001 if there is an error.

    return MAKE_HRESULT(uSeverity, 0, (unsigned short)sResult);
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shobjidl_core.h (inclure Shobjidl.h)
DLL	Shell32.dll (version 4.0 ou ultérieure)

Voir aussi

IShellFolder

IShellFolder2

Partager via