IExtractIconA：：GetIconLocation 方法 (shlobj_core.h)

發行項
03/05/2024

取得圖示的位置和索引。

語法

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

參數

uFlags

類型： UINT

下列一或多個值。此參數也可以是 NULL。

GIL_ASYNC (0x0020)

設定此旗標，以判斷是否應該以異步方式擷取圖示。如果可以快速擷取圖示，通常會忽略此旗標。如果擷取需要更多時間， GetIconLocation 應該會傳回E_PENDING。如需進一步的討論，請參閱。

GIL_DEFAULTICON (0x0040)

擷取後援圖示的相關信息。後援圖示通常會在擷取並新增至快取時使用。

GIL_FORSHELL (0x0002)

圖示會顯示在Shell資料夾中。

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*

int 的指標，接收 pszIconFile 所指向之檔案中圖標的索引。

[out] pwFlags

類型： UINT*

UINT 值的指標，可接收零或下列值的組合。

GIL_DONTCACHE (0x0010)

呼叫的應用程式不會快取此圖示的實體影像位。

GIL_NOTFILENAME (0x0008)

位置不是檔名/索引組。 pszIconFile 和 piIndex 中的值無法傳遞至 ExtractIcon 或 ExtractIconEx。

省略此旗標時， pszIconFile 中傳回的值是.ico檔案或可包含圖示的檔案的完整路徑名稱。此外， piIndex 中傳回的值是該檔案中的索引，可識別要使用的圖示。因此，當省略GIL_NOTFILENAME旗標時，這些值可以傳遞至 ExtractIcon 或 ExtractIconEx。

GIL_PERCLASS (0x0004)

這個類別的所有物件都有相同的圖示。 Shell 會在內部使用此旗標。 IExtractIcon 的一般實作不需要此旗標，因為旗標表示不需要圖示處理程式，才能根據每個物件解析圖示。實作每個類別圖示的建議方法是註冊類別的DefaultIcon。

GIL_PERINSTANCE (0x0002)

這個類別的每個物件都有自己的圖示。 Shell 會在內部使用此旗標來處理 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作為傳回值時，通常會建立背景線程來擷取圖示。它會從該線程呼叫 GetIconLocation ，而不使用 GIL_ASYNC 旗標，以擷取圖示位置。然後它會呼叫 IExtractIcon：：Extract 來擷取圖示。傳回E_PENDING表示對像是自由線程的。換句話說，它可以由多個線程同時呼叫。

在找到所需的圖示的情況下，通常會設定 GIL_DEFAULTICON 旗標，但該圖示不存在於圖示快取中。圖示擷取是低優先順序的背景進程，因此其他進程可能會延遲。默認圖示將會在擷取最終圖示、新增至快取及提供時，取代最終圖示。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	shlobj_core.h
Dll	Shell32.dll (4.0 版或更新版本)