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

IShellIconOverlayIdentifier

COM
📘 Microsoft Learn (日本語) · English
IID0c6c4200-c589-11d0-999a-00c04fd655e1継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

アイコンオーバーレイハンドラーとシェルの間のすべての通信を処理するメソッドを公開します。

解説(Remarks)

アイコンオーバーレイは、Windows エクスプローラーやデスクトップ上でシェルオブジェクトを表すアイコンの左下隅に配置される小さな画像です。オブジェクトの通常のアイコンに追加情報を付与するために使用されます。よく使われるアイコンオーバーレイの例として、ファイルやフォルダーが実際にはリンクであることを示す小さな矢印があります。アイコンオーバーレイハンドラーを実装して登録することで、シェルオブジェクトにカスタムのアイコンオーバーレイを指定できます。

アイコンオーバーレイハンドラーは、特定のアイコンオーバーレイに関連付けられた Component Object Model (COM) オブジェクトです。アイコンオーバーレイハンドラーの一般的な説明については、How to Implement Icon Overlay Handlers を参照してください。

このインターフェイスは、すべてのアイコンオーバーレイハンドラーで実装する必要があります。

このインターフェイスは、通常アプリケーションから呼び出されることはありません。

メソッド 3

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

vtbl 3 HRESULT IsMemberOf(LPWSTR pwszPath, DWORD dwAttrib)

アイコンオーバーレイをシェルオブジェクトのアイコンに追加すべきかどうかを指定します。

pwszPathLPWSTRinシェルオブジェクトの完全修飾パスを含む Unicode 文字列。
dwAttribDWORDinオブジェクトの属性。ファイル属性とそれに関連するフラグの完全な一覧については、File Attribute Constants を参照してください。

戻り値

型: HRESULT

このメソッドは、次のいずれかを返します。

戻り値 説明
S_OK
 アイコンオーバーレイを表示すべきである。
S_FALSE
 アイコンオーバーレイを表示すべきではない。
E_FAIL
 操作が失敗した。

解説(Remarks)

シェルは、特定のオブジェクトに対してハンドラーのアイコンオーバーレイを表示すべきかどうかを判断するために、このメソッドを呼び出します。アイコンオーバーレイハンドラーは通常、特定のファイル群を対象として動作するように設計されています。典型的な例は、特定のファイル名拡張子によって識別されるファイルの種類です。アイコンオーバーレイハンドラーは、そのファイルの種類に属するすべてのメンバーに対してアイコンオーバーレイを要求することがあります。ハンドラーによっては、ファイルの種類のメンバーが特定の状態にある場合にのみアイコンオーバーレイを要求するものもあります。ただし、アイコンオーバーレイハンドラーは、任意のオブジェクトに対して自由にアイコンオーバーレイを要求できます。

vtbl 4 HRESULT GetOverlayInfo(LPWSTR pwszIconFile, INT cchMax, INT* pIndex, DWORD* pdwFlags)

アイコンオーバーレイのビットマップの場所を提供します。

pwszIconFileLPWSTRoutアイコンを含むファイルの完全修飾パスを含む、null 終端の Unicode 文字列。.dll、.exe、.ico のいずれのファイル形式も使用できます。ファイル名を返す場合は、pdwFlags に ISIOI_ICONFILE フラグを設定する必要があります。
cchMaxINTinpwszIconFile バッファーのサイズ (Unicode 文字数)。
pIndexINT*out複数のアイコンを含むファイル内でアイコンを識別するために使用するインデックス値へのポインター。インデックスを返す場合は、pdwFlags に ISIOI_ICONINDEX フラグを設定する必要があります。
pdwFlagsDWORD*out

メソッドが返す情報を指定するビットマップへのポインター。このパラメーターには、次の値のいずれか一方または両方を指定できます。

ISIOI_ICONFILE (0x00000001)

アイコンファイルのパスが pwszIconFile を通じて返されます。

ISIOI_ICONINDEX (0x00000002)

pwszIconFile に複数のアイコンが含まれています。アイコンのインデックスが pIndex を通じて返されます。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、ハンドラーのアイコンオーバーレイをシステムイメージリストに追加できるようにするために、起動時にシェルから呼び出されます。初期化が完了した後、シェルはハンドラーのアイコンオーバーレイを表示する必要があるときに GetOverlayInfo を呼び出します。

注 初期化中に画像がシステムイメージリストに読み込まれると、その後変更することはできません。初期化後、ファイル名とインデックスはアイコンオーバーレイを識別するためだけに使用されます。システムが新しいアイコンオーバーレイを読み込むことはありません。GetOverlayInfo が呼び出されたとき、ハンドラーは関数が最初に呼び出されたときに指定したものと同じファイル名とインデックスを返す必要があります。
vtbl 5 HRESULT GetPriority(INT* pPriority)

アイコンオーバーレイの優先度を指定します。

pPriorityINT*outオーバーレイ識別子の優先度を示す値のアドレス。指定できる値は 0 から 100 の範囲で、0 が最も高い優先度です。

戻り値

型: HRESULT

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

解説(Remarks)

あるオブジェクトに対して複数のアイコンオーバーレイが利用可能な場合、最も優先度の高いものが選択されます。シェルには、多くのケースについて優先度を決定する一連の内部ルールがあります。GetPriority が返す値は、シェルの内部ルールが適用されないケースで使用されます。通常は、この値を 0 に設定してください。ただし、同じオブジェクトに対してアイコンオーバーレイアイコンを要求できるアイコンオーバーレイハンドラーを 2 つ以上実装している場合には、優先度の値が役立ちます。優先度の値を適切に設定することで、要求されたアイコンオーバーレイのうちどれを表示するかを指定できます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IShellIconOverlayIdentifier "{0C6C4200-C589-11D0-999A-00C04FD655E1}"
#usecom global IShellIconOverlayIdentifier IID_IShellIconOverlayIdentifier "{}"
#comfunc global IShellIconOverlayIdentifier_IsMemberOf      3 wstr,int
#comfunc global IShellIconOverlayIdentifier_GetOverlayInfo  4 var,int,var,var
#comfunc global IShellIconOverlayIdentifier_GetPriority     5 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。