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;如果 Shell 应使用默认图标，则返回S_FALSE。如果在 uFlags 中设置了GIL_ASYNC标志，则该方法可以返回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 或更高版本)

通过