Win32 API 日本語リファレンス
ホーム › UI.Shell › IShellItem

IShellItem

COM
📘 Microsoft Learn (日本語) · English
IID43826d1e-e718-42ee-bc55-a1e261c37bfe継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

シェル項目に関する情報を取得するためのメソッドを公開します。新しいコードでは、IShellItem および IShellItem2 が項目を表現する推奨手段です。

解説(Remarks)

実装するタイミング

このインターフェイスをサードパーティが実装することはありません。システムが提供する実装のみを使用してください。

メソッド 5

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT BindToHandler(IBindCtx* pbc, GUID* bhid, GUID* riid, void** ppv)

ハンドラー ID 値 (BHID) で指定された、項目のハンドラーにバインドします。

pbcIBindCtx*inバインド コンテキスト オブジェクト上の IBindCtx インターフェイスへのポインター。省略可能なパラメーターをハンドラーに渡すために使用します。バインド コンテキストの内容はハンドラー固有です。たとえば BHID_Stream にバインドする場合、バインド コンテキスト内の STGM フラグは、要求するアクセス モード (読み取り、または読み取り/書き込み) を示します。
bhidGUID*in

作成するハンドラーを指定する GUID への参照。Shlguid.h で定義されている次のいずれかの値です。

BHID_SFObject

使用を BindToObject に限定します。

BHID_SFUIObject

使用を GetUIObjectOf に限定します。

BHID_SFViewObject

使用を CreateViewObject に限定します。

BHID_Storage

ストレージ RIID の取得を試みますが、失敗した場合はシェルの実装にフォールバックします。

BHID_Stream

使用を IStream に限定します。

BHID_LinkTargetItem

CLSID_ShellItem は、この項目のターゲット (SFGAO_LINK のみ可) で初期化されます。SFGAO_LINK の説明については SFGAO を参照してください。

BHID_StorageEnum

項目がフォルダーの場合、ストレージの内容を列挙するための IEnumShellItems オブジェクトを取得します。

BHID_Transfer

Windows Vista で導入: 項目がフォルダーの場合、ITransferSource または ITransferDestination オブジェクトを取得します。

BHID_PropertyStore

Windows Vista で導入: 使用を IPropertyStore または IPropertyStoreFactory に限定します。

BHID_ThumbnailHandler

Windows Vista で導入: 使用を IExtractImage または IThumbnailProvider に限定します。

BHID_EnumItems

Windows Vista で導入: 項目がフォルダーの場合、フォルダー内のすべての項目を列挙する IEnumShellItems オブジェクトを取得します。これにはフォルダー、非フォルダー、および隠し項目が含まれます。

BHID_DataObject

Windows Vista で導入: 単一の項目または項目の配列で使用する IDataObject オブジェクトを取得します。

BHID_AssociationArray

Windows Vista で導入: 単一の項目または項目の配列で使用する IQueryAssociations オブジェクトを取得します。

BHID_Filter

Windows Vista で導入: 使用を IFilter に限定します。

BHID_EnumAssocHandlers

Windows 7 で導入: 指定した項目に対して推奨される関連付けハンドラーを列挙するために使用する IEnumAssocHandlers オブジェクトを取得します。

BHID_RandomAccessStream

Windows 8 で導入: 項目に対する IRandomAccessStream オブジェクトを取得します。

BHID_FilePlaceholder

Windows 8.1 で導入: プレースホルダー ファイル機能を提供するために使用するオブジェクトを取得します。

riidGUID*in取得するオブジェクト型の IID。
ppvvoid**outこのメソッドが返るとき、rbhid で指定されたハンドラーが返す riid 型のポインターが格納されます。

戻り値

型: HRESULT

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

vtbl 4 HRESULT GetParent(IShellItem** ppsi)

IShellItem オブジェクトの親を取得します。

ppsiIShellItem**out親の IShellItem インターフェイスへのポインターのアドレス。

戻り値

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。

vtbl 5 HRESULT GetDisplayName(SIGDN sigdnName, LPWSTR* ppszName)

IShellItem オブジェクトの表示名を取得します。

sigdnNameSIGDNin名前の表現方法を示す SIGDN 値のいずれか。
ppszNameLPWSTR*outこの関数が正常に返ったとき、取得された表示名へのポインターのアドレスを受け取る値。

戻り値

型: HRESULT

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

解説(Remarks)

ppszName が指す文字列が不要になったときに解放するのは、呼び出し元の責任です。メモリを解放するには、*ppszName に対して CoTaskMemFree を呼び出してください。

vtbl 6 HRESULT GetAttributes(SFGAO_FLAGS sfgaoMask, SFGAO_FLAGS* psfgaoAttribs)

IShellItem オブジェクトの要求された属性セットを取得します。

sfgaoMaskSFGAO_FLAGSin取得する属性を指定します。SFGAO 値の 1 つ以上を指定します。取得する属性を決定するにはビットごとの OR 演算子を使用します。
psfgaoAttribsSFGAO_FLAGS*outこのメソッドが正常に返ったとき、要求された属性を格納する値へのポインター。SFGAO 値の 1 つ以上です。sfgaoMask で指定された属性のみが返され、その他の属性値は未定義です。

戻り値

型: HRESULT

返された属性が sfgaoMask で要求されたものと完全に一致する場合は S_OK を、完全には一致しない場合は S_FALSE を、それ以外の場合は標準の COM エラー値を返します。

vtbl 7 HRESULT Compare(IShellItem* psi, DWORD hint, INT* piOrder)

2 つの IShellItem オブジェクトを比較します。

psiIShellItem*in既存の IShellItem オブジェクトと比較する IShellItem オブジェクトへのポインター。
hintDWORDin比較の実行方法を決定する SICHINTF 値のいずれか。このパラメーターに指定可能な値の一覧については SICHINTF を参照してください。
piOrderINT*outこのパラメーターは比較の結果を受け取ります。2 つの項目が同じ場合、このパラメーターは 0 になります。異なる場合は 0 以外の値になります。

戻り値

型: HRESULT

項目が同じ場合は S_OK を、異なる場合は S_FALSE を、それ以外の場合はエラー値を返します。

解説(Remarks)

2 番目のパラメーターで使用されるデータ型 SICHINTF は、次のように定義されています。

typedef DWORD SICHINTF;
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IShellItem "{43826D1E-E718-42EE-BC55-A1E261C37BFE}"
#usecom global IShellItem IID_IShellItem "{9AC9FBE1-E0A2-4AD6-B4EE-E212013EA917}"
#comfunc global IShellItem_BindToHandler   3 sptr,var,var,sptr
#comfunc global IShellItem_GetParent       4 sptr
#comfunc global IShellItem_GetDisplayName  5 int,var
#comfunc global IShellItem_GetAttributes   6 int,var
#comfunc global IShellItem_Compare         7 sptr,int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。