IShellFolder

Shell の名前空間におけるすべてのフォルダーオブジェクトによって公開され、そのメソッドはフォルダーを管理するために使用されます。

Shell の名前空間を拡張するオブジェクトには、このインターフェイスを実装します。たとえば、ルート化された Windows Explorer を必要とする独立した名前空間を作成する場合や、システム名前空間の階層内に新しい名前空間を直接インストールする場合に、このインターフェイスを実装します。自分の名前空間の内容を最もよく理解しているのは開発者自身であるため、データにアクセスするために必要なすべての処理を実装する責任は開発者にあります。

Shell の名前空間の内容を表示したり、その内容に対して操作を実行したりする必要がある場合に、このインターフェイスを使用します。IShellFolder をサポートするオブジェクトは、通常、他の Shell フォルダーオブジェクトによって作成されます。フォルダーの IShellFolder インターフェイスを取得するには、通常、まず SHGetDesktopFolder を呼び出します。この関数はデスクトップの IShellFolder インターフェイスへのポインターを返します。その後、そのメソッドを使用して、特定の名前空間フォルダーの IShellFolder インターフェイスを取得できます。

Examples

IShellFolder の実装例は、Explorer Data Provider Sample サンプルで確認できます。さまざまな IShellFolder メソッドの使用例は、File Operations Sample など、いくつかのサンプルで確認できます。

ファイルオブジェクトまたはフォルダーの表示名を、アイテム識別子リストに変換します。

::{CLSID for Control Panel}\::{CLSID for printers folder}

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

一部の Shell フォルダーは IShellFolder::ParseDisplayName を実装していない場合があります。実装する各フォルダーは、独自の解析構文を定義します。

ParseDisplayName は、相対パスや親フォルダーの指示子("." や "..")を処理することは想定されていません。これらを適切に取り除くのは呼び出し側の責任です。

解析対象の名前を持つアイテムの存在を確認するために、pdwAttributes で SFGAO_VALIDATE フラグを使用しないでください。IShellFolder::ParseDisplayName は、特別なバインドコンテキストパラメーターによって動作が上書きされない限り、アイテムの存在を暗黙的に検証します。

一部の属性の照会は、比較的低速で、大量のメモリを使用する場合があります。たとえば、ファイルが共有されているかどうかを判定するために、Shell はネットワークコンポーネントを読み込みます。この処理には複数の DLL の読み込みが必要になる場合があります。pdwAttributes の目的は、照会を必要な情報のみに制限できるようにすることです。次のコード断片は、ファイルが圧縮されているかどうかを調べる方法を示しています。

LPITEMIDLIST pidl;
ULONG cbEaten;
DWORD dwAttribs = SFGAO_COMPRESSED;

hres = psf->ParseDisplayName(NULL,
                             NULL,
                             lpwszDisplayName,
                             &cbEaten,  // This can be NULL
                             &pidl,
                             &dwAttribs);

if(dwAttribs & SFGAO_COMPRESSED)
{
    // Do something with the compressed file
}

pdwAttributes は入出力パラメーターであるため、常に初期化する必要があります。初期化されていない値を渡すと、一部のビットが意図せず設定される可能性があります。その場合、IShellFolder::ParseDisplayName は対応する属性を照会するため、望ましくない遅延やメモリ需要を引き起こす可能性があります。属性を照会したくない場合は、予測できない動作を避けるために pdwAttributes を NULL に設定してください。

このメソッドは IParseDisplayName::ParseDisplayName メソッドに似ています。

アイテム識別子の列挙オブジェクトを作成し、その IEnumIDList インターフェイスを返すことで、クライアントがフォルダーの内容を確認できるようにします。そのインターフェイスがサポートするメソッドを使用して、フォルダーの内容を列挙できます。

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合はエラー値を返します。実装によっては、渡された grfFlags に一致する子が存在しないことを示す S_FALSE を返す場合もあります。S_FALSE が返された場合、ppenumIDList は NULL に設定されます。

メソッドが S_OK を返した場合、ppenumIDList は列挙子へのポインターを受け取ります。この場合、呼び出し側アプリケーションは、返された IEnumIDList オブジェクトの Release メソッドを呼び出して解放する必要があります。

メソッドが S_FALSE を返した場合、フォルダーには適切なサブオブジェクトが含まれておらず、ppenumIDList で指定されたポインターは NULL に設定されます。

メソッドが失敗した場合はエラー値が返され、ppenumIDList で指定されたポインターは NULL に設定されます。

フォルダーに適切なサブオブジェクトが含まれていない場合、IShellFolder::EnumObjects メソッドは、*ppenumIDList を NULL に設定して S_FALSE を返すか、オブジェクトを生成しない列挙子を *ppenumIDList に設定して S_OK を返すか、のいずれかが許容されます。呼び出し側アプリケーションは、両方の成功ケースに対応できるようにしておく必要があります。

ハンドラー、通常は特定のアイテムに対して IShellFolder を実装する Shell フォルダーオブジェクトを取得します。ハンドラーの構築を制御する省略可能なパラメーターは、バインドコンテキストで渡します。

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

アプリケーションは、サブアイテムの Shell フォルダーオブジェクトを取得するために IShellFolder::BindToObject(..., IID_IShellFolder, ...) を使用します。クライアントは、特定のハンドラーを識別するために使用される正規のインターフェイス IID を渡す必要があります。たとえば、IID_IShellFolder はフォルダーハンドラーを、IID_IStream はストリームハンドラーを識別します。実装は、IID_IShellFolder2 のような派生インターフェイスを使用したハンドラーへのバインドをサポートすることもできます。Shell の名前空間拡張は、指定されたサブアイテムの Shell フォルダーオブジェクトを作成し、QueryInterface を呼び出してそのインターフェイスポインターを通じてオブジェクトと通信することで、この関数を実装できます。

BindToObject の実装は、サポートしていない IID 値に対して速やかに失敗することで、呼び出しを最適化できます。たとえば、サブアイテムの Shell フォルダーオブジェクトが IRemoteComputer をサポートしていない場合、実装は、サブアイテムの Shell フォルダーオブジェクトを不必要に作成した後で IRemoteComputer がサポートされていなかったと判明するのではなく、直ちに E_NOINTERFACE を返す必要があります。

オブジェクトのストレージインターフェイスへのポインターを要求します。

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

名前空間拡張は、アイテムのストレージを表すオブジェクトへのバインドをアプリケーションに許可するオプションを提供できます。このオプションがサポートされている場合、IShellFolder::BindToStorage は、オブジェクトの内容にアクセスするために使用できる指定されたインターフェイスポインターを返します。詳細については、IMoniker::BindToStorage のリファレンスを参照してください。

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

型: HRESULT

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

戻り値	説明
負の値	負の戻り値は、1 番目のアイテムが 2 番目のアイテムより前に並ぶべきであることを示します(pidl1 < pidl2)。
正の値	正の戻り値は、1 番目のアイテムが 2 番目のアイテムより後に並ぶべきであることを示します(pidl1 > pidl2)。
ゼロ	ゼロの戻り値は、2 つのアイテムが同一であることを示します(pidl1 = pidl2)。

呼び出し側アプリケーションへの注意

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

HRESULT_CODE マクロを使用して HRESULT から CODE フィールドを抽出し、その結果を short にキャストします。

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

フォルダーオブジェクトから情報を取得したり、フォルダーオブジェクトと対話したりするために使用できるオブジェクトを要求します。

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

この要求をサポートするには、riid で示されるインターフェイスを公開するオブジェクトを作成し、そのインターフェイスへのポインターを返します。

このメソッドの主な目的は、フォルダーオブジェクトのフォルダービューオブジェクトを Windows Explorer に提供することです。Windows Explorer は、riid を IID_IShellView に設定してフォルダービューオブジェクトを要求します。フォルダービューオブジェクトは、Windows Explorer のフォルダービューにフォルダーの内容を表示します。Windows Explorer は複数のフォルダービューオブジェクトを作成するためにこのメソッドを複数回呼び出す可能性があるため、フォルダービューオブジェクトは Shell フォルダーオブジェクトから独立している必要があります。このメソッドが呼び出されるたびに、新しいビューオブジェクトを作成する必要があります。フォルダーオブジェクトは、この要求に対して次の 2 つの方法のいずれかで応答できます。

• カスタムのフォルダービューオブジェクトを作成し、その IShellView インターフェイスへのポインターを返す。
• システムのフォルダービューオブジェクトを作成し、その IShellView インターフェイスへのポインターを返す。

このメソッドは、IContextMenu や IExtractIcon を含む、いくつかの省略可能なインターフェイスのいずれかを公開するオブジェクトを要求するためにも使用されます。この文脈では、CreateViewObject は IShellFolder::GetUIObjectOf と使用方法が似ています。ただし、IShellFolder::GetUIObjectOf はフォルダーに含まれるアイテムの 1 つに対するオブジェクトを要求するために呼び出します。IShellFolder::CreateViewObject はフォルダー自体に対するオブジェクトを要求するために呼び出します。最もよく要求されるインターフェイスは次のとおりです。

• IQueryInfo
• IShellDetails
• IDropTarget

riid と ppv のパラメーターをまとめるには、Objbase.h で定義されている IID_PPV_ARGS マクロを使用することをお勧めします。このマクロは、ppv の値が指すインターフェイスに基づいて正しい IID を提供するため、予期しない結果につながる riid のコーディングミスの可能性を排除できます。

IShellFolder が表すオブジェクトに含まれる 1 つ以上のファイルオブジェクトまたはフォルダーオブジェクトの属性を取得します。

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

この操作を最適化するために、指定されていないフラグは返さないでください。

フォルダーオブジェクトの場合、SFGAO_BROWSABLE 属性は、クライアントがここに一般的な形式で示すようにこのオブジェクトにバインドできることを意味します。

IShellFolder::BindToObject(..., pidl, IID_IShellFolder, &psfItem);

その後、クライアントは次のステートメントを通じて、そのアイテム上に IShellView を作成できます。

psfItem->CreateViewObject(..., IID_IShellView,...);

SFGAO_DROPTARGET 属性は、クライアントがここに示すように IShellFolder::GetUIObjectOf を呼び出すことで、このフォルダーに対する IDropTarget のインスタンスにバインドできることを意味します。

IShellFolder::GetUIObjectOf(hwnd, 1, &pidl, IID_IDropTarget, NULL, &pv)

SFGAO_NONENUMERATED 属性は、IShellFolder::EnumObjects メソッドによって作成された列挙子が返さないアイテムを示します。

指定されたファイルオブジェクトまたはフォルダーに対してアクションを実行するために使用できるオブジェクトを取得します。

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

cidl が 1 より大きい場合、IShellFolder::GetUIObjectOf の実装は、apidl で指定されたすべてのアイテムに対して 1 つのオブジェクトを作成できる場合にのみ成功する必要があります。すべてのアイテムに対して 1 つのオブジェクトを作成できない場合、このメソッドは失敗します。

次に、Shell がこのメソッドからインターフェイスを要求する際に使用する最も一般的なインターフェイス識別子を示します。この一覧は、要求されたインターフェイスに対して cidl が 1 より大きくできるかどうかも示しています。

インターフェイス識別子	許容される cidl 値
IContextMenu	cidl パラメーターは 1 以上にできます。
IContextMenu2	cidl パラメーターは 1 以上にできます。
IDataObject	cidl パラメーターは 1 以上にできます。
IDropTarget	cidl パラメーターは 1 のみです。
IExtractIcon	cidl パラメーターは 1 のみです。
IExtractImage	cidl パラメーターは 1 のみです。
IQueryInfo	cidl パラメーターは 1 のみです。

riid と ppv のパラメーターをまとめるには、Objbase.h で定義されている IID_PPV_ARGS マクロを使用することをお勧めします。このマクロは、ppv の値が指すインターフェイスに基づいて正しい IID を提供するため、予期しない結果につながる riid のコーディングミスの可能性を排除できます。

指定されたファイルオブジェクトまたはサブフォルダーの表示名を取得します。

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

この関数によって割り当てられたリソースを解放するのは呼び出し側の責任です。

通常、pidl は親フォルダーに含まれるアイテムのみを参照できます。PIDL は単一レベルで、ちょうど 1 つの SHITEMID 構造体を含み、その後に終端のゼロが続く必要があります。親フォルダーから 1 レベルより深いアイテムの表示名を取得したい場合は、SHBindToParent を使用してアイテムの直接の親フォルダーにバインドし、そのアイテムの単一レベル PIDL を IShellFolder::GetDisplayNameOf に渡します。

また、uFlags に SHGDN_FORPARSING フラグが設定され、SHGDN_INFOLDER フラグが設定されていない場合、pidl は名前空間階層内で親フォルダーより下の任意のレベルのオブジェクトを参照できます。かつては、pidl は親フォルダーからの相対的な複数レベルの PIDL で、複数の SHITEMID 構造体を含むことができました。しかし、これはもうサポートされておらず、pidl は現在では単一の子アイテムのみを参照する必要があります。

pName が指す構造体から表示名を取得する最も簡単な方法は、それを StrRetToBuf または StrRetToStr のいずれかに渡すことです。これらの関数は STRRET 構造体を受け取り、名前を返します。構造体の uType メンバーを調べて、適切なメンバーから名前を取得することもできます。

uFlags で指定されたフラグは、名前の意図された用途に関するヒントです。これらは、IShellFolder が要求された形式の名前を返すことを保証するものではありません。その形式が利用できない場合は、別の形式が返される可能性があります。特に、SHGDN_FORPARSING フラグによって返される名前が IShellFolder::ParseDisplayName によって正常に解析される保証はありません。また、フラグの組み合わせによっては、GetDisplayNameOf/ParseDisplayName の往復で元の識別子リストが返されない場合があります。これは例外的な事象ですが、念のため確認する必要があります。

ファイルオブジェクトまたはサブフォルダーの表示名を設定し、その過程でアイテム識別子を変更します。

型: HRESULT

このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。

ファイルシステムオブジェクトやその中のフォルダーの表示名を変更すると、そのファイルまたはディレクトリの名前が変更されます。

このメソッドを呼び出す前に、アプリケーションは IShellFolder::GetAttributesOf を呼び出し、SFGAO_CANRENAME フラグが設定されていることを確認する必要があります。このフラグは本質的に名前空間クライアントへのヒントである点に注意してください。これは IShellFolder::SetNameOf が成功する、または失敗することを必ずしも意味するものではありません。

IShellFolder::SetNameOf の実装者は、オブジェクトの名前変更が完了したら、変更前と変更後の両方の絶対 PIDL を指定して SHChangeNotify を呼び出す必要があります。次の例は、フォルダーオブジェクトの名前変更に続く SHChangeNotify の呼び出しを示しています。

SHChangeNotify(SHCNE_RENAMEFOLDER, SHCNF_IDLIST, pidlFullOld, pidlFullNew);

この呼び出しにより、ビューに変更前と変更後の両方の名前が表示されるのを防ぎます。

#define global IID_IShellFolder "{000214E6-0000-0000-C000-000000000046}"
#usecom global IShellFolder IID_IShellFolder "{}"
#comfunc global IShellFolder_ParseDisplayName  3 sptr,sptr,wstr,var,var,var
#comfunc global IShellFolder_EnumObjects       4 sptr,int,sptr
#comfunc global IShellFolder_BindToObject      5 var,sptr,var,sptr
#comfunc global IShellFolder_BindToStorage     6 var,sptr,var,sptr
#comfunc global IShellFolder_CompareIDs        7 sptr,var,var
#comfunc global IShellFolder_CreateViewObject  8 sptr,var,sptr
#comfunc global IShellFolder_GetAttributesOf   9 int,var,var
#comfunc global IShellFolder_GetUIObjectOf     10 sptr,int,var,var,var,sptr
#comfunc global IShellFolder_GetDisplayNameOf  11 var,int,var
#comfunc global IShellFolder_SetNameOf         12 sptr,var,wstr,int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。