IShellFolder::CompareIDs メソッド (shobjidl_core.h)

[アーティクル]
08/26/2023

アイテム識別子リストを指定して、2 つのファイルオブジェクトまたはフォルダーの相対順序を決定します。

構文

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

パラメーター

[in] lParam

型: LPARAM

比較の実行方法を示す値。

lParam の下位 16 ビットは、並べ替え規則を定義します。ほとんどのアプリケーションでは、並べ替えルールを既定値の 0 に設定し、2 つの項目を名前で比較する必要があることを示します。システムは、他の並べ替えルールを定義しません。一部のフォルダーオブジェクトでは、呼び出し元のアプリケーションで lParam の下位 16 ビットを使用して、フォルダー固有の並べ替え規則を指定できる場合があります。ルールとそれに関連付けられている lParam 値は、フォルダーによって定義されます。

システムフォルダービューオブジェクトが IShellFolder::CompareIDs を呼び出すと、比較に使用する列を指定するために lParam の下位 16 ビットが使用されます。

並べ替え規則を変更するフラグには、 lParam の上位 16 ビットが使用されます。システムは現在、これらの修飾子フラグを定義しています。

SHCIDS_ALLFIELDS

バージョン 5.0。表示名だけでなく、 ITEMIDLIST 構造体に含まれるすべての情報を比較します。このフラグは、 IShellFolder2 インターフェイスをサポートするフォルダーオブジェクトに対してのみ有効です。たとえば、2 つの項目がファイルの場合は、フォルダーの名前、サイズ、ファイルの時刻、属性、および構造体内のその他の情報を比較する必要があります。このフラグが設定されている場合、 lParam の下位 16 ビットは 0 である必要があります。

SHCIDS_CANONICALONLY

バージョン 5.0。名前で比較する場合は、システム名を比較しますが、表示名は比較しないでください。このフラグが渡されると、2 つの項目は、一貫性のある並べ替え関数を実装している限り、Shell フォルダーが最も効率的であると判断した条件によって比較されます。このフラグは、等価性を比較する場合、または並べ替えの結果がユーザーに表示されない場合に便利です。このフラグを他のフラグと組み合わせることはできません。

[in] pidl1

種類: PCUIDLIST_RELATIVE

最初の項目の ITEMIDLIST 構造体へのポインター。フォルダーに対する相対パスになります。この ITEMIDLIST 構造体には、複数の要素を含めることができます。したがって、最初の要素だけでなく、構造体全体を比較する必要があります。

[in] pidl2

種類: PCUIDLIST_RELATIVE

2 番目の項目の ITEMIDLIST 構造体へのポインター。フォルダーに対する相対パスになります。この ITEMIDLIST 構造体には、複数の要素を含めることができます。したがって、最初の要素だけでなく、構造体全体を比較する必要があります。

戻り値

型: HRESULT

このメソッドが成功した場合、 HRESULT の CODE フィールドには次のいずれかの値が含まれます。返された HRESULT からの CODE フィールドの抽出については、「解説」を参照してください。このメソッドが失敗した場合は、COM エラーコードが返されます。

リターンコード	説明
負	負の戻り値は、最初の項目が 2 番目の項目 (pidl1 < pidl2) の前にあることを示します。
正	正の戻り値は、最初の項目が 2 番目の項目 (pidl1 > pidl2) の後に続く必要があることを示します。
Zero	戻り値 0 は、2 つの項目が同じであることを示します (pidl1 = pidl2)。

注釈

アプリケーションの呼び出しに関する注意

フォルダーオブジェクトが IShellFolder2 をサポートしていない場合は、lParam で SHCIDS_ALLFIELDS フラグを設定しないでください。これにより、予期しない結果が生じる可能性があります。 SHCIDS_ALLFIELDS フラグを使用する場合は、lParam の下位 16 ビットを 0 に設定する必要があります。

HRESULT_CODE マクロを使用して HRESULT から CODE フィールドを抽出し、結果を短い形式でキャストします。

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

実装者への注意

並べ替えルールを抽出するには、ビットごとの AND 演算子 (&) を使用して 、lParam と SHCIDS_COLUMNMASK (0X0000FFFF) を組み合わせます。この操作は、SHCIDS_ALLFIELDS値を含め、lParam の上位 16 ビットをマスクします。

MAKE_HRESULT マクロは、CompareIDs メソッドの実装の戻り値を構築する場合に便利です。次に例を示します。

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

要件

要件	値
サポートされている最小のクライアント	Windows XP (デスクトップアプリのみ)
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	shobjidl_core.h (Shobjidl.h を含む)
[DLL]	Shell32.dll (バージョン 4.0 以降)

こちらもご覧ください

IShellFolder

IShellFolder2