IExtractIconW：：GetIconLocation 方法 (shlobj_core.h)

  • 项目

获取图标的位置和索引。

语法

HRESULT GetIconLocation(
        UINT  uFlags,
  [out] PWSTR 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作为返回值时，它通常会创建一个后台线程来提取图标。 它从没有GIL_ASYNC标志的线程调用 GetIconLocation 来检索图标位置。 然后，它调用 IExtractIcon：：Extract 来提取图标。 返回E_PENDING表示对象是自由线程。 换句话说，它可以安全地由多个线程同时调用。

在找到所需图标但图标缓存中不存在该图标的情况下，通常会设置 GIL_DEFAULTICON 标志。 图标提取是一个低优先级的后台进程，因此其他进程可能会延迟。 在提取最终图标、将其添加到缓存并使其可用期间，默认图标将代替最终图标。

要求

要求 值
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 shlobj_core.h
DLL Shell32.dll (4.0 或更高版本)