IShellItemImageFactory：：GetImage 方法（shobjidl_core.h）

项目
11/20/2024

获取表示 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）

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

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 [仅限桌面应用]
目标平台	窗户
标头	shobjidl_core.h （包括 Shobjidl.h）

通过