IShellItemImageFactory：：GetImage 方法 (shobjidl_core.h)

發行項
03/05/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線程上完成擷取。

如需如何使用此方法的完整範例，請參閱使用 Image Factory 範例。

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	shobjidl_core.h (包括 Shobjidl.h)

共用方式為