Metodo IShellFolder::CompareIDs (shobjidl_core.h)

Articolo
03/15/2023

Determina l'ordine relativo di due oggetti file o cartelle, in base agli elenchi degli identificatori di elemento.

Sintassi

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

Parametri

[in] lParam

Tipo: LPARAM

Valore che specifica la modalità di esecuzione del confronto.

I sedici bit inferiori di lParam definiscono la regola di ordinamento. La maggior parte delle applicazioni imposta la regola di ordinamento sul valore predefinito di zero, che indica che i due elementi devono essere confrontati in base al nome. Il sistema non definisce altre regole di ordinamento. Alcuni oggetti cartelle potrebbero consentire alle applicazioni di chiamata di usare i sedici bit inferiori di lParam per specificare regole di ordinamento specifiche della cartella. Le regole e i valori lParam associati sono definiti dalla cartella.

Quando l'oggetto vista cartella di sistema chiama IShellFolder::CompareIDs, vengono usati i sedici bit inferiori di lParam per specificare la colonna da usare per il confronto.

I sedici bit superiori di lParam vengono usati per i flag che modificano la regola di ordinamento. Il sistema definisce attualmente questi flag di modificatore.

SHCIDS_ALLFIELDS

Versione 5.0. Confrontare tutte le informazioni contenute nella struttura ITEMIDLIST , non solo i nomi visualizzati. Questo flag è valido solo per gli oggetti cartella che supportano l'interfaccia IShellFolder2 . Ad esempio, se i due elementi sono file, la cartella deve confrontare i relativi nomi, dimensioni, tempi di file, attributi e altre informazioni nelle strutture. Se questo flag è impostato, i sedici bit inferiori di lParam devono essere zero.

SHCIDS_CANONICALONLY

Versione 5.0. Quando si confronta in base al nome, confrontare i nomi di sistema ma non i nomi visualizzati. Quando questo flag viene passato, i due elementi vengono confrontati con qualsiasi criterio determinato dalla cartella Shell, purché implementi una funzione di ordinamento coerente. Questo flag è utile quando si confronta per l'uguaglianza o quando i risultati dell'ordinamento non vengono visualizzati all'utente. Questo flag non può essere combinato con altri flag.

[in] pidl1

Tipo: PCUIDLIST_RELATIVE

Puntatore alla struttura ITEMIDLIST del primo elemento. Sarà relativo alla cartella. Questa struttura ITEMIDLIST può contenere più di un elemento; pertanto, l'intera struttura deve essere confrontata, non solo il primo elemento.

[in] pidl2

Tipo: PCUIDLIST_RELATIVE

Puntatore alla struttura ITEMIDLIST del secondo elemento. Sarà relativo alla cartella. Questa struttura ITEMIDLIST può contenere più di un elemento; pertanto, l'intera struttura deve essere confrontata, non solo il primo elemento.

Valore restituito

Tipo: HRESULT

Se questo metodo ha esito positivo, il campo CODE di HRESULT contiene uno dei valori seguenti. Per informazioni sull'estrazione del campo CODE da HRESULT restituito, vedere Osservazioni. Se questo metodo non riesce, restituisce un codice di errore COM.

Codice restituito	Descrizione
Negativo	Un valore restituito negativo indica che il primo elemento deve precedere il secondo (pidl1 < pidl2).
Positivo	Un valore restituito positivo indica che il primo elemento deve seguire il secondo (pidl1 > pidl2).
Zero	Un valore restituito pari a zero indica che i due elementi sono uguali (pidl1 = pidl2).

Commenti

Nota per la chiamata di applicazioni

Non impostare il flag SHCIDS_ALLFIELDS in lParam se l'oggetto cartella non supporta IShellFolder2. In questo modo potrebbero avere risultati imprevedibili. Se si usa il flag SHCIDS_ALLFIELDS , è necessario impostare su zero i sedici bit inferiori di lParam .

Utilizzare la macro HRESULT_CODE per estrarre il campo CODE da HRESULT, quindi eseguire il cast del risultato come breve.

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

Nota per implementatori

Per estrarre la regola di ordinamento, usare un operatore AND bit per bit (&) per combinare lParam con SHCIDS_COLUMNMASK (0X0000FFFF). Questa operazione maschera i sedici bit superiori di lParam, incluso il valore di SHCIDS_ALLFIELDS .

La macro MAKE_HRESULT è utile per costruire il valore restituito per un'implementazione del metodo CompareIDs. Ad esempio:

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shobjidl_core.h (include Shobjidl.h)
DLL	Shell32.dll (versione 4.0 o successiva)

Vedi anche

IShellFolder

IShellFolder2

Condividi tramite