IExtractIconW
COM公式ドキュメント
フォルダー内のオブジェクトの 1 つに関連付けられたアイコンをクライアントが取得できるようにするメソッドを公開します。(Unicode)
解説(Remarks)
オブジェクトのアイコンを取得するには 2 つの方法があります。最も簡単な方法は SHGetFileInfo を呼び出すことです。ただし、この方法は柔軟性に欠け、動作が遅くなる場合があります。項目のアイコンを取得するより柔軟で効率的な方法は、IExtractIcon を使用することです。シェルは、フォルダーの内容を表示する際にアイコンを取得するために IExtractIcon を使用します。IExtractIcon を使用してオブジェクトのアイコンを取得するには、次の手順を実行します。
- オブジェクトを含むフォルダーの IShellFolder インターフェイスへのポインターを取得します。
- オブジェクトの項目識別子リスト (PIDL) へのポインターと IExtractIcon のインターフェイス ID (IID_IExtractIcon) を指定して、IShellFolder::GetUIObjectOf を呼び出します。フォルダーはアイコン抽出を処理するオブジェクトを作成し、そのオブジェクトの IExtractIcon インターフェイス ポインターを返します。
- IExtractIcon::GetIconLocation を呼び出してアイコンの場所を取得します。
- IExtractIcon::Extract を呼び出してアイコンのハンドルを取得します。
名前空間拡張は、そのオブジェクトのアイコンを提供するために IExtractIcon を実装します。クライアントは、フォルダーの IShellFolder::GetUIObjectOf メソッドを呼び出すことで、フォルダー内のオブジェクトの IExtractIcon インターフェイス ポインターを取得します。IShellFolder::GetUIObjectOf の実装は、アイコン抽出を処理するオブジェクトを作成し、そのオブジェクトの IExtractIcon インターフェイスへのポインターを返す必要があります。
アイコン ハンドラーも IExtractIcon を実装します。アイコン ハンドラーは、ファイル型のメンバーにアイコンを動的に割り当てることができるシェル拡張ハンドラーの一種です。
アプリケーションで SHGetFileInfo よりも柔軟な方法でオブジェクトのアイコンを取得する必要がある場合は、このインターフェイスを呼び出します。
shlobj_core.h ヘッダーは、IExtractIcon を、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして定義しています。エンコード中立のエイリアスの使用とエンコード中立でないコードを混在させると、不一致が発生し、コンパイル エラーまたは実行時エラーが生じる可能性があります。詳細については、関数プロトタイプの規則を参照してください。
メソッド 2
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
アイコンの場所とインデックスを取得します。(Unicode)
| uFlags | DWORD | in | 次の値の 1 つ以上です。このパラメーターは NULL にすることもできます。 GIL_ASYNC (0x0020)アイコンを非同期に抽出すべきかどうかを判定するには、このフラグを設定します。アイコンをすばやく抽出できる場合、通常このフラグは無視されます。抽出により多くの時間がかかる場合、GetIconLocation は E_PENDING を返す必要があります。詳細については「解説」を参照してください。 GIL_DEFAULTICON (0x0040)フォールバック アイコンに関する情報を取得します。フォールバック アイコンは通常、目的のアイコンが抽出されてキャッシュに追加されるまでの間に使用されます。 GIL_FORSHELL (0x0002)アイコンはシェル フォルダーに表示されます。 GIL_FORSHORTCUT (0x0080)アイコンはショートカットを示します。ただし、アイコン抽出側はショートカット オーバーレイを適用すべきではありません。それは後で行われます。ショートカット アイコンは状態に依存しません。 GIL_OPENICON (0x0001)開いた状態と閉じた状態の両方のイメージが利用可能な場合、アイコンは開いた状態になります。このフラグが指定されていない場合、アイコンは通常状態または閉じた状態になります。このフラグは通常、フォルダー オブジェクトに使用されます。 GIL_CHECKSHIELD (0x0200)pwFlags に GIL_SHIELD または GIL_FORCENOSHIELD のいずれかを明示的に返します。GIL_ASYNC が設定されている場合はブロックしないでください。 |
| pszIconFile | LPWSTR | out | アイコンの場所を受け取るバッファーへのポインターです。アイコンの場所は、アイコンを含むファイルを識別する null で終わる文字列です。 |
| cchMax | DWORD | in | pszIconFile が指すバッファーのサイズ (文字数) です。 |
| piIndex | INT* | out | pszIconFile が指すファイル内のアイコンのインデックスを受け取る int へのポインターです。 |
| pwFlags | DWORD* | out | 0 または次の値の組み合わせを受け取る UINT 値へのポインターです。 GIL_DONTCACHE (0x0010)このアイコンの物理イメージ ビットは、呼び出し側アプリケーションによってキャッシュされません。 GIL_NOTFILENAME (0x0008)場所はファイル名/インデックスのペアではありません。pszIconFile および piIndex の値を ExtractIcon または ExtractIconEx に渡すことはできません。 このフラグが省略された場合、pszIconFile で返される値は、.ico ファイルまたはアイコンを含むことができるファイルへの完全修飾パス名です。また、piIndex で返される値は、そのファイル内でどのアイコンを使用するかを識別するインデックスです。したがって、GIL_NOTFILENAME フラグが省略されている場合、これらの値を ExtractIcon または ExtractIconEx に渡すことができます。 GIL_PERCLASS (0x0004)このクラスのすべてのオブジェクトは同じアイコンを持ちます。このフラグはシェルによって内部的に使用されます。このフラグは、アイコン ハンドラーがオブジェクト単位でアイコンを解決する必要がないことを意味するため、IExtractIcon の一般的な実装ではこのフラグは必要ありません。クラス単位のアイコンを実装する推奨方法は、クラスに対して DefaultIcon を登録することです。 GIL_PERINSTANCE (0x0002)このクラスの各オブジェクトは独自のアイコンを持ちます。このフラグはシェルによって内部的に使用され、Setup.exe のように同じ名前のオブジェクトが異なるアイコンを持ち得るケースを処理します。IExtractIcon の一般的な実装では、このフラグは必要ありません。 GIL_SIMULATEDOC (0x0001)呼び出し側アプリケーションは、指定されたアイコンを使用してドキュメント アイコンを作成する必要があります。 GIL_SHIELD (0x0200)Windows Vista のみ。呼び出し側アプリケーションは、アイコンに UAC シールドをスタンプする必要があります。 GIL_FORCENOSHIELD (0x0400)Windows Vista のみ。呼び出し側アプリケーションは、アイコンに UAC シールドをスタンプしてはなりません。 - pwFlags.GIL_DONTCACHE (0x0010)このアイコンの物理イメージ ビットは、呼び出し側アプリケーションによってキャッシュされません。 - pwFlags.GIL_FORCENOSHIELD (0x0400)Windows Vista のみ。呼び出し側アプリケーションは、アイコンに UAC シールドをスタンプしてはなりません。 - pwFlags.GIL_NOTFILENAME (0x0008)場所はファイル名/インデックスのペアではありません。pszIconFile および piIndex の値を ExtractIcon または ExtractIconEx に渡すことはできません。 このフラグが省略された場合、pszIconFile で返される値は、.ico ファイルまたはアイコンを含むことができるファイルへの完全修飾パス名です。また、piIndex で返される値は、そのファイル内でどのアイコンを使用するかを識別するインデックスです。したがって、GIL_NOTFILENAME フラグが省略されている場合、これらの値を ExtractIcon または ExtractIconEx に渡すことができます。 - pwFlags.GIL_PERCLASS (0x0004)このクラスのすべてのオブジェクトは同じアイコンを持ちます。このフラグはシェルによって内部的に使用されます。このフラグは、アイコン ハンドラーがオブジェクト単位でアイコンを解決する必要がないことを意味するため、IExtractIcon の一般的な実装ではこのフラグは必要ありません。クラス単位のアイコンを実装する推奨方法は、クラスに対して DefaultIcon を登録することです。 - pwFlags.GIL_PERINSTANCE (0x0002)このクラスの各オブジェクトは独自のアイコンを持ちます。このフラグはシェルによって内部的に使用され、Setup.exe のように同じ名前のオブジェクトが異なるアイコンを持ち得るケースを処理します。IExtractIcon の一般的な実装では、このフラグは必要ありません。 - pwFlags.GIL_SHIELD (0x0200)Windows Vista のみ。呼び出し側アプリケーションは、アイコンに UAC シールドをスタンプする必要があります。 - pwFlags.GIL_SIMULATEDOC (0x0001)呼び出し側アプリケーションは、指定されたアイコンを使用してドキュメント アイコンを作成する必要があります。 - uFlags.GIL_ASYNC (0x0020)アイコンを非同期に抽出すべきかどうかを判定するには、このフラグを設定します。アイコンをすばやく抽出できる場合、通常このフラグは無視されます。抽出により多くの時間がかかる場合、GetIconLocation は E_PENDING を返す必要があります。詳細については「解説」を参照してください。 - uFlags.GIL_CHECKSHIELD (0x0200)pwFlags に GIL_SHIELD または GIL_FORCENOSHIELD のいずれかを明示的に返します。GIL_ASYNC が設定されている場合はブロックしないでください。 - uFlags.GIL_DEFAULTICON (0x0040)フォールバック アイコンに関する情報を取得します。フォールバック アイコンは通常、目的のアイコンが抽出されてキャッシュに追加されるまでの間に使用されます。 - uFlags.GIL_FORSHELL (0x0002)アイコンはシェル フォルダーに表示されます。 - uFlags.GIL_FORSHORTCUT (0x0080)アイコンはショートカットを示します。ただし、アイコン抽出側はショートカット オーバーレイを適用すべきではありません。それは後で行われます。ショートカット アイコンは状態に依存しません。 - uFlags.GIL_OPENICON (0x0001)開いた状態と閉じた状態の両方のイメージが利用可能な場合、アイコンは開いた状態になります。このフラグが指定されていない場合、アイコンは通常状態または閉じた状態になります。このフラグは通常、フォルダー オブジェクトに使用されます。 |
戻り値
型: HRESULT
関数が有効な場所を返した場合は S_OK を返します。シェルが既定のアイコンを使用すべき場合は S_FALSE を返します。uFlags に GIL_ASYNC フラグが設定されている場合、このメソッドは E_PENDING を返して、アイコン抽出に時間がかかることを示すことができます。
解説(Remarks)
クライアントが uFlags に GIL_ASYNC フラグを設定し、戻り値として E_PENDING を受け取った場合、通常はアイコンを抽出するためのバックグラウンド スレッドを作成します。そのスレッドから GIL_ASYNC フラグを指定せずに GetIconLocation を呼び出し、アイコンの場所を取得します。次に IExtractIcon::Extract を呼び出してアイコンを抽出します。E_PENDING を返すことは、そのオブジェクトがフリー スレッドであることを意味します。言い換えると、複数のスレッドから同時に安全に呼び出すことができます。
GIL_DEFAULTICON フラグは通常、目的のアイコンは見つかったものの、そのアイコンがアイコン キャッシュに存在しない場合に設定されます。アイコン抽出は優先度の低いバックグラウンド処理であるため、他のプロセスによって遅延することがあります。最終的なアイコンが抽出され、キャッシュに追加されて利用可能になるまでの間、既定のアイコンが最終的なアイコンの代わりに表示されます。
指定された場所からアイコン イメージを抽出します。(Unicode)
| pszFile | LPWSTR | in | アイコンの場所を指定する null で終わる文字列へのポインターです。 |
| nIconIndex | DWORD | in | pszFile が指すファイル内のアイコンのインデックスです。 |
| phiconLarge | HICON* | outoptional | 大きいアイコンのハンドルを受け取る HICON 値へのポインターです。このパラメーターは NULL にすることができます。 |
| phiconSmall | HICON* | outoptional | 小さいアイコンのハンドルを受け取る HICON 値へのポインターです。このパラメーターは NULL にすることができます。 |
| nIconSize | DWORD | in | アイコンの希望するサイズ (ピクセル単位) です。下位ワードには大きいアイコンのサイズが、上位ワードには小さいアイコンのサイズが格納されます。指定するサイズは幅または高さを表します。アイコンの幅は常にその高さと等しくなります。 |
戻り値
解説(Remarks)
アイコンの場所とインデックスは、IExtractIcon::GetIconLocation メソッドが返す値と同じです。IExtractIcon::Extract 関数が S_FALSE を返す場合、これらの値は ExtractIcon の呼び出しに対する正当なパラメーターを構成するアイコン ファイル名とインデックスを指定する必要があります。IExtractIcon::Extract が S_FALSE を返さない場合、pszFile および nIconIndex パラメーターの意味について何も想定すべきではありません。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IExtractIconW "{000214FA-0000-0000-C000-000000000046}" #usecom global IExtractIconW IID_IExtractIconW "{}" #comfunc global IExtractIconW_GetIconLocation 3 int,var,int,var,var #comfunc global IExtractIconW_Extract 4 wstr,int,sptr,sptr,int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IExtractIconW "{000214FA-0000-0000-C000-000000000046}" #usecom global IExtractIconW IID_IExtractIconW "{}" #comfunc global IExtractIconW_GetIconLocation 3 int,sptr,int,sptr,sptr #comfunc global IExtractIconW_Extract 4 wstr,int,sptr,sptr,int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。