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

[アーティクル]
08/26/2023

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

構文

HRESULT GetIconLocation(
        UINT uFlags,
  [out] PSTR 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 以降)