IExtractIconA
COM公式ドキュメント
フォルダー内のオブジェクトの 1 つに関連付けられているアイコンをクライアントが取得できるようにするメソッドを公開します。(ANSI)
解説(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。
アイコンの場所とインデックスを取得します。(ANSI)
| 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 | LPSTR | out | アイコンの場所を受け取るバッファーへのポインター。アイコンの場所は、アイコンを含むファイルを識別する null で終わる文字列です。 |
| cchMax | DWORD | in | pszIconFile が指すバッファーのサイズ (文字数)。 |
| piIndex | INT* | out | pszIconFile が指すファイル内のアイコンのインデックスを受け取る int へのポインター。 |
| pwFlags | DWORD* | out | ゼロ、または次の値の組み合わせを受け取る 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 シールドをアイコンにスタンプしてはなりません。 |
戻り値
型: 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 フラグは通常、目的のアイコンが見つかったものの、そのアイコンがアイコンキャッシュ内に存在しない場合に設定されます。アイコンの抽出は優先度の低いバックグラウンド処理であり、そのため他の処理によって遅延する場合があります。最終的なアイコンが抽出され、キャッシュに追加され、利用可能になるまでの間、その最終的なアイコンの代わりに既定のアイコンが表示されます。
指定された場所からアイコンイメージを抽出します。(ANSI)
| pszFile | LPSTR | 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_IExtractIconA "{000214EB-0000-0000-C000-000000000046}" #usecom global IExtractIconA IID_IExtractIconA "{}" #comfunc global IExtractIconA_GetIconLocation 3 int,var,int,var,var #comfunc global IExtractIconA_Extract 4 str,int,sptr,sptr,int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IExtractIconA "{000214EB-0000-0000-C000-000000000046}" #usecom global IExtractIconA IID_IExtractIconA "{}" #comfunc global IExtractIconA_GetIconLocation 3 int,sptr,int,sptr,sptr #comfunc global IExtractIconA_Extract 4 str,int,sptr,sptr,int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。