IExtractIconW::GetIconLocation メソッド (shlobj_core.h)

[アーティクル]
03/15/2023

アイコンの場所とインデックスを取得します。

構文

HRESULT GetIconLocation(
        UINT  uFlags,
  [out] PWSTR pszIconFile,
        UINT  cchMax,
  [out] int   *piIndex,
  [out] UINT  *pwFlags
);

パラメーター

uFlags

型: UINT

次の値の 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が設定されている場合はブロックしないでください。

[out] pszIconFile

種類: PTSTR

アイコンの場所を受け取るバッファーへのポインター。アイコンの場所は、アイコンを含むファイルを識別する null で終わる文字列です。

cchMax

型: UINT

pszIconFile が指すバッファーのサイズ (文字単位)。

[out] piIndex

型: int*

pszIconFile が指すファイル内のアイコンのインデックスを受け取る int へのポインター。

[out] pwFlags

種類: UINT*

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 シールドでアイコンにスタンプを付けてはなりません。

戻り値

種類: HRESULT

関数が有効な場所を返した場合はS_OKを返し、シェルで既定のアイコンを使用する必要がある場合はS_FALSEを返します。 GIL_ASYNC フラグが uFlags で設定されている場合、メソッドはE_PENDINGを返して、アイコンの抽出に時間がかかることを示すことができます。

注釈

クライアントが uFlags でGIL_ASYNC フラグを設定し、戻り値としてE_PENDINGを受け取ると、通常、アイコンを抽出するバックグラウンドスレッドが作成されます。 GIL_ASYNC フラグを指定せずに、そのスレッドから GetIconLocation を呼び出して、アイコンの場所を取得します。その後、 IExtractIcon::Extract を呼び出してアイコンを抽出します。 E_PENDINGを返すということは、オブジェクトがフリースレッドであることを意味します。つまり、複数のスレッドで同時に呼び出しても安全です。

通常、GIL_DEFAULTICON フラグは、目的のアイコンが見つかった場合に設定されますが、そのアイコンはアイコンキャッシュに存在しません。アイコンの抽出は優先度の低いバックグラウンドプロセスであるため、他のプロセスによって遅延する可能性があります。既定のアイコンは、最終的なアイコンが抽出され、キャッシュに追加され、使用可能になるのにかかる時間の間に、最終的なアイコンの代わりに表示されます。

要件

要件	値
サポートされている最小のクライアント	Windows XP (デスクトップアプリのみ)
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	shlobj_core.h
[DLL]	Shell32.dll (バージョン 4.0 以降)