IShellFolder::CompareIDs-Methode (shobjidl_core.h)

Artikel
08/26/2023

Bestimmt die relative Reihenfolge von zwei Dateiobjekten oder Ordnern unter Berücksichtigung ihrer Elementbezeichnerlisten.

Syntax

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

Parameter

[in] lParam

Typ: LPARAM

Ein -Wert, der angibt, wie der Vergleich durchgeführt werden soll.

Die unteren sechzehn Bits von lParam definieren die Sortierregel. Die meisten Anwendungen legen die Sortierregel auf den Standardwert 0 (null) fest, was angibt, dass die beiden Elemente anhand des Namens verglichen werden sollen. Das System definiert keine anderen Sortierregeln. Einige Ordnerobjekte ermöglichen es möglicherweise, dass aufrufende Anwendungen die unteren sechzehn Bits von lParam verwenden, um ordnerspezifische Sortierregeln anzugeben. Die Regeln und die zugehörigen lParam-Werte werden durch den Ordner definiert.

Wenn das Systemordneransichtsobjekt IShellFolder::CompareIDs aufruft, werden die unteren sechzehn Bits von lParam verwendet, um die Spalte anzugeben, die für den Vergleich verwendet werden soll.

Die oberen sechzehn Bits von lParam werden für Flags verwendet, die die Sortierregel ändern. Das System definiert derzeit diese Modifiziererflags.

SHCIDS_ALLFIELDS

Version 5.0. Vergleichen Sie alle in der ITEMIDLIST-Struktur enthaltenen Informationen, nicht nur die Anzeigenamen. Dieses Flag ist nur für Ordnerobjekte gültig, die die IShellFolder2-Schnittstelle unterstützen. Wenn es sich bei den beiden Elementen um Dateien handelt, sollte der Ordner bei instance ihre Namen, Größen, Dateizeiten, Attribute und alle anderen Informationen in den Strukturen vergleichen. Wenn dieses Flag festgelegt ist, müssen die unteren sechzehn Bits von lParam null sein.

SHCIDS_CANONICALONLY

Version 5.0. Vergleichen Sie beim Vergleich anhand des Namens die Systemnamen, aber nicht die Anzeigenamen. Wenn dieses Flag übergeben wird, werden die beiden Elemente nach den Kriterien verglichen, die der Shellordner als am effizientesten festlegt, solange eine konsistente Sortierfunktion implementiert wird. Dieses Flag ist nützlich, wenn vergleicht wird, um Gleichheit zu erzielen oder wenn die Ergebnisse der Sortierung für den Benutzer nicht angezeigt werden. Dieses Flag kann nicht mit anderen Flags kombiniert werden.

[in] pidl1

Typ: PCUIDLIST_RELATIVE

Ein Zeiger auf die ITEMIDLIST-Struktur des ersten Elements. Sie ist relativ zum Ordner. Diese ITEMIDLIST-Struktur kann mehrere Elemente enthalten. Daher muss die gesamte Struktur verglichen werden, nicht nur das erste Element.

[in] pidl2

Typ: PCUIDLIST_RELATIVE

Ein Zeiger auf die ITEMIDLIST-Struktur des zweiten Elements. Sie ist relativ zum Ordner. Diese ITEMIDLIST-Struktur kann mehrere Elemente enthalten. Daher muss die gesamte Struktur verglichen werden, nicht nur das erste Element.

Rückgabewert

Typ: HRESULT

Wenn diese Methode erfolgreich ist, enthält das FELD CODE des HRESULT einen der folgenden Werte. Informationen zur Extraktion des CODE-Felds aus dem zurückgegebenen HRESULT finden Sie unter Hinweise. Wenn diese Methode nicht erfolgreich ist, wird ein COM-Fehlercode zurückgegeben.

Rückgabecode	Beschreibung
Negative	Ein negativer Rückgabewert gibt an, dass das erste Element vor dem zweiten (pidl1 < pidl2) stehen soll.
Positive	Ein positiver Rückgabewert gibt an, dass das erste Element nach dem zweiten (pidl1 > pidl2) folgen soll.
Zero	Der Rückgabewert 0 (null) gibt an, dass die beiden Elemente identisch sind (pidl1 = pidl2).

Hinweise

Hinweis zum Aufrufen von Anwendungen

Legen Sie das SHCIDS_ALLFIELDS-Flag in lParam nicht fest, wenn das Ordnerobjekt IShellFolder2 nicht unterstützt. Dies kann zu unvorhersehbaren Ergebnissen kommen. Wenn Sie das flag SHCIDS_ALLFIELDS verwenden, müssen die unteren sechzehn Bits von lParam auf null festgelegt werden.

Verwenden Sie das HRESULT_CODE-Makro , um das CODE-Feld aus dem HRESULT zu extrahieren, und wandeln Sie das Ergebnis dann in eine Kurze um.

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 */ }

Hinweis zu Implementern

Verwenden Sie zum Extrahieren der Sortierregel einen bitweisen AND-Operator (&), um lParam mit SHCIDS_COLUMNMASK (0X0000FFFF) zu kombinieren. Dieser Vorgang maskiert die oberen sechzehn Bits von lParam, einschließlich des SHCIDS_ALLFIELDS-Werts .

Das MAKE_HRESULT Makro ist nützlich, um den Rückgabewert für eine Implementierung der CompareIDs-Methode zu erstellen. Beispiel:

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);
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shobjidl_core.h (shobjidl.h einschließen)
DLL	Shell32.dll (Version 4.0 oder höher)

Weitere Informationen

IShellFolder

IShellFolder2

Share via