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

Determina a ordem relativa de dois objetos ou pastas de arquivo, considerando suas listas de identificadores de item.

Sintaxe

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

Parâmetros

[in] lParam

Tipo: LPARAM

Um valor que especifica como a comparação deve ser executada.

Os dezesseis bits inferiores de lParam definem a regra de classificação. A maioria dos aplicativos define a regra de classificação como o valor padrão de zero, indicando que os dois itens devem ser comparados por nome. O sistema não define nenhuma outra regra de classificação. Alguns objetos de pasta podem permitir que aplicativos de chamada usem os dezesseis bits inferiores de lParam para especificar regras de classificação específicas de pasta. As regras e seus valores lParam associados são definidos pela pasta .

Quando o objeto de exibição de pasta do sistema chama IShellFolder::CompareIDs, os dezesseis bits inferiores de lParam são usados para especificar a coluna a ser usada para a comparação.

Os dezesseis bits superiores de lParam são usados para sinalizadores que modificam a regra de classificação. Atualmente, o sistema define esses sinalizadores modificador.

SHCIDS_ALLFIELDS

Versão 5.0. Compare todas as informações contidas na estrutura ITEMIDLIST , não apenas os nomes de exibição. Esse sinalizador é válido apenas para objetos de pasta que dão suporte à interface IShellFolder2 . Por exemplo, se os dois itens forem arquivos, a pasta deverá comparar seus nomes, tamanhos, tempos de arquivo, atributos e qualquer outra informação nas estruturas. Se esse sinalizador for definido, os dezesseis bits inferiores de lParam deverão ser zero.

SHCIDS_CANONICALONLY

Versão 5.0. Ao comparar por nome, compare os nomes do sistema, mas não os nomes de exibição. Quando esse sinalizador é passado, os dois itens são comparados por qualquer critério que a pasta Shell determina ser mais eficiente, desde que implemente uma função de classificação consistente. Esse sinalizador é útil ao comparar a igualdade ou quando os resultados da classificação não são exibidos para o usuário. Esse sinalizador não pode ser combinado com outros sinalizadores.

[in] pidl1

Tipo: PCUIDLIST_RELATIVE

Um ponteiro para a estrutura ITEMIDLIST do primeiro item. Ele será relativo à pasta . Essa estrutura ITEMIDLIST pode conter mais de um elemento; portanto, toda a estrutura deve ser comparada, não apenas o primeiro elemento.

[in] pidl2

Tipo: PCUIDLIST_RELATIVE

Um ponteiro para a estrutura ITEMIDLIST do segundo item. Ele será relativo à pasta . Essa estrutura ITEMIDLIST pode conter mais de um elemento; portanto, toda a estrutura deve ser comparada, não apenas o primeiro elemento.

Retornar valor

Tipo: HRESULT

Se esse método for bem-sucedido, o campo CODE do HRESULT conterá um dos valores a seguir. Para obter informações sobre a extração do campo CODE do HRESULT retornado, consulte Comentários. Se esse método não for bem-sucedido, ele retornará um código de erro COM.

Código de retorno	Descrição
Negativo	Um valor retornado negativo indica que o primeiro item deve preceder o segundo (pidl1 < pidl2).
Positivo	Um valor retornado positivo indica que o primeiro item deve seguir o segundo (pidl1 > pidl2).
Zero	Um valor retornado de zero indica que os dois itens são os mesmos (pidl1 = pidl2).

Comentários

Observação aos aplicativos de chamada

Não defina o sinalizador SHCIDS_ALLFIELDS em lParam se o objeto de pasta não der suporte a IShellFolder2. Fazer isso pode ter resultados imprevisíveis. Se você usar o sinalizador SHCIDS_ALLFIELDS , os dezesseis bits inferiores de lParam deverão ser definidos como zero.

Use a macro HRESULT_CODE para extrair o campo CODE do HRESULT e, em seguida, converta o resultado como um curto.

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

Observação aos implementadores

Para extrair a regra de classificação, use um operador AND bit a bit (&) para combinar lParam com SHCIDS_COLUMNMASK (0X0000FFFF). Essa operação mascara os dezesseis bits superiores de lParam, incluindo o valor SHCIDS_ALLFIELDS .

A macro MAKE_HRESULT é útil para construir o valor retornado para uma implementação do método CompareIDs. Por exemplo:

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

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shobjidl_core.h (inclua Shobjidl.h)
DLL	Shell32.dll (versão 4.0 ou posterior)

Confira também

Ishellfolder

IShellFolder2