IExtractImage：：GetLocation 方法 (shobjidl_core.h)

  • 项目

获取要提取的图像的路径。

语法

HRESULT GetLocation(
  [out]     LPWSTR     pszPathBuffer,
  [in]      DWORD      cch,
  [out]     DWORD      *pdwPriority,
  [in]      const SIZE *prgSize,
  [in]      DWORD      dwRecClrDepth,
  [in, out] DWORD      *pdwFlags
);

参数

[out] pszPathBuffer

类型： LPWSTR

用于返回路径说明的缓冲区。 此值标识图像，因此可以避免多次加载同一个图像。

[in] cch

类型：DWORD

pszPathBuffer 的大小（以字符为单位）。

[out] pdwPriority

类型： DWORD*

未使用。

Microsoft Windows XP 及更早版本：在 pdwFlags 中设置IEIFLAG_ASYNC标志时，用于返回项的优先级的指针。 此参数不得为 NULL。 如果此参数为 NULL，则函数将失败，无论 是否设置了IEIFLAG_ASYNC 标志。

此参数通常用于指示提取图像所需的时间。 如果希望更好地控制缩略图的提取顺序，可以定义多个优先级，最多 32 位。 只要分配给不同优先级的整数值从低优先级增加到高优先级，你使用的实际数字就不重要。 它们仅用于确定图像的提取顺序。 有三个标准优先级级别：

IEI_PRIORITY_MAX

最大优先级。

IEI_PRIORITY_MIN

最低优先级。

IEIT_PRIORITY_NORMAL

正常优先级。

Microsoft Windows XP。 未使用。

[in] prgSize

类型： const SIZE*

指向具有所需图像宽度和高度的 SIZE 结构的指针。 不得为 NULL。

[in] dwRecClrDepth

类型：DWORD

建议的颜色深度（以每像素位数为单位）。 不得为 NULL。

[in, out] pdwFlags

类型： DWORD*

指定如何处理映像的标志。 值必须是以下一个或多个：

IEIFLAG_ASPECT

用于要求对象使用提供的纵横比。 如果设置了此标志，则会在 prgSize 中传递具有所需纵横比的矩形。 此标志不能与 IEIFLAG_SCREEN一起使用。

IEIFLAG_ASYNC

未使用。 缩略图始终在后台线程上提取。

Microsoft Windows XP 及更早版本。 用于询问此实例是否支持异步 (自由线程) 提取。 如果此标志由调用应用程序设置， IExtractImage：：GetLocation 可能会返回 E_PENDING，向调用应用程序指示在另一个线程上提取图像。 如果返回 E_PENDING ，则以 pdwPriority 返回项的优先级。

IEIFLAG_CACHE

不支持。

Windows XP 及更早版本： 由 对象设置，以指示它不会缓存图像。 如果返回此标志，Shell 将缓存映像的副本。

IEIFLAG_GLEAM

不支持。

IEIFLAG_NOBORDER (0x0100)

不支持。

IEIFLAG_NOSTAMP (0x0080)

不支持。

IEIFLAG_OFFLINE

用于告知对象仅使用本地内容进行呈现。

IEIFLAG_ORIGSIZE

版本 5.0。 用于告知对象将图像呈现为 在 prgSize 中传递的近似大小，但在必要时对其进行裁剪。

IEIFLAG_QUALITY (0x0200)

传递给 IExtractImage：：Extract 方法以指示请求更高质量的图像。

如果未设置此标志，则无论用户请求的大小如何，如果文件有嵌入的缩略图， IExtractImage 将检索嵌入的缩略图。 例如，如果文件为 2000x2000 像素，但嵌入的缩略图仅为 100x100 像素，并且用户未设置此标志，但请求 1000x1000 像素缩略图， 则 IExtractImage 始终返回 100x100 像素的缩略图。 这是设计使然，因为 IExtractImage 不会纵向扩展。 如果需要更大的缩略图 (通常嵌入的缩略图为 160x160) ，则必须设置此标志。

IEIFLAG_REFRESH (0x0400)

由 对象返回，指示应在项的快捷菜单上显示 刷新缩略图 。

IEIFLAG_SCREEN

用于指示对象像在屏幕中一样呈现。 此标志不能与 IEIFLAG_ASPECT 一起使用。

返回值

类型： HRESULT

此方法可能会返回 COM 定义的错误代码或下列代码之一：

返回代码 说明
S_OK
 成功
E_PENDING
 Windows XP 及更早版本： 如果设置了 IEIFLAG_ASYNC 标志，则此返回值用于向 Shell 指示对象是自由线程的。

注解

Microsoft Windows XP 及更早版本： 此方法返回图像的路径并指定图像的呈现方式。 IExtractImage：：GetLocation 是自由线程的，即支持多线程单元模型 (MTA) ，因此可以将其放置在后台线程中。 对象还必须公开 IRunnableTask 接口，以便调用应用程序可以根据需要启动和停止提取过程。

应返回适合 prgSize 定义的边界内的图像。 使用 Windows 2000 及更高版本的系统，你可以将 IEIFLAG_ORIGSIZE 设置为使用没有标准纵横比的对象，它们将正确显示。 无需填充矩形的未使用部分。 如果尝试在早期版本的 Shell 中使用非标准纵横比图像，则会拉伸该图像以适应 prgSize 矩形。 根据纵横比与指定的不同程度，图像可能会严重扭曲。

要求

   
最低受支持的客户端 Windows 2000 专业版、Windows XP [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
目标平台 Windows
标头 shobjidl_core.h (包括 Shobjidl.h)
DLL Shell32.dll (版本 4.70 或更高版本)