IShellItemImageFactory：：GetImage 方法 (shobjidl_core.h)

项目
08/26/2023

获取表示 IShellItem 的 HBITMAP。默认行为是加载缩略图。如果当前 IShellItem 没有缩略图，它将检索项图标的 HBITMAP 。如果当前未缓存缩略图或图标，则会提取该缩略图或图标。

语法

HRESULT GetImage(
  [in]  SIZE    size,
  [in]  SIIGBF  flags,
  [out] HBITMAP *phbm
);

参数

[in] size

类型： SIZE

一个结构，指定要接收的图像的大小。

[in] flags

类型： SIIGBF

以下一项或多项：

SIIGBF_RESIZETOFIT (0x00000000)

根据需要收缩位图以适应大小，保留其纵横比。

SIIGBF_BIGGERSIZEOK (0x00000001)

如果调用方想要拉伸返回的图像本身，则由调用方传递。例如，如果调用方传递图标大小为 80x80，则可能会返回 96x96 缩略图。如果调用方需要拉伸图像，则可以将此操作用作性能优化。请注意， IShellItemImageFactory 的 Shell 实现执行 GDI 拉伸 blit。如果调用方希望图像拉伸质量高于通过该机制提供的图像拉伸质量，则应传递此标志并自行执行拉伸。

SIIGBF_MEMORYONLY (0x00000002)

仅当项已位于内存中时，才返回该项。即使该项已缓存，也不要访问磁盘。请注意，仅返回已缓存的图标，如果项具有尚未缓存的每个实例图标，则此图标可以回退到每个类的图标。检索缩略图（即使已缓存）始终需要访问磁盘，因此，如果不传递SIIGBF_MEMORYONLY，则不应从 UI 线程调用 GetImage。

SIIGBF_ICONONLY (0x00000004)

仅返回图标，不返回缩略图。

SIIGBF_THUMBNAILONLY (0x00000008)

仅返回缩略图，不返回图标。请注意，并非所有项都有缩略图，因此在这些情况下 ，SIIGBF_THUMBNAILONLY 将导致方法失败。

SIIGBF_INCACHEONLY (0x00000010)

允许访问磁盘，但只允许检索缓存的项。这会返回缓存的缩略图（如果可用）。如果没有缓存的缩略图可用，它将返回缓存的每个实例图标，但不提取缩略图或图标。

SIIGBF_CROPTOSQUARE (0x00000020)

在 Windows 8 中引入。如有必要，请将位图裁剪为正方形。

SIIGBF_WIDETHUMBNAILS (0x00000040)

在 Windows 8 中引入。将位图拉伸并裁剪为 0.7 纵横比。

SIIGBF_ICONBACKGROUND (0x00000080)

在 Windows 8 中引入。如果返回图标，请使用关联应用的注册背景色绘制背景。

SIIGBF_SCALEUP (0x00000100)

在 Windows 8 中引入。如有必要，请拉伸位图，使高度和宽度适合给定的大小。

[out] phbm

类型： HBITMAP*

指向一个值的指针，当此方法成功返回时，该值接收检索到的位图的句柄。调用方负责在不再需要时通过 DeleteObject 释放检索到的资源。

返回值

类型： HRESULT

如果该方法成功，则返回 S_OK。否则，将返回 HRESULT 错误代码。

注解

图标提取可能很耗时。通常不应从 UI 线程调用此方法，以避免导致该线程变得无响应。如果设置了 SIIGBF_INCACHEONLY 标志，则可以在 UI 线程上调用 IShellItemImageFactory：：GetImage。但是，如果在缓存中找不到图像，则调用应用程序应准备好启动后台线程以提取图像。绝不应在 UI 线程上执行提取。

有关如何使用此方法的完整示例，请参阅使用映像工厂示例。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	shobjidl_core.h (包括 Shobjidl.h)