共用方式為

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
 Success
E_PENDING
 Windows XP 和更早版本： 如果已設定 IEIFLAG_ASYNC 旗標，這個傳回值會用來向殼層指出物件為自由執行緒。

備註

Microsoft Windows XP 和更早版本： 這個方法會傳回影像的路徑，並指定影像的呈現方式。 IExtractImage：：GetLocation 是自由執行緒，也就是支援多執行緒 Apartment 模型 (MTA) ，因此它可以放在背景執行緒中。 物件也必須公開 IRunnableTask 介面，讓呼叫的應用程式可以視需要啟動和停止擷取程式。

您應該傳回符合 prgSize所定義界限內的影像。 使用 Windows 2000 和更新版本系統時，您可以將 IEIFLAG_ORIGSIZE 設定為使用沒有標準外觀比例的物件，而且它們會正確顯示。 您不需要填入矩形未使用的部分。 如果您嘗試搭配舊版 Shell 使用非標準外觀比例影像，則會縮放以符合 prgSize 矩形。 視外觀比例與指定的外觀比例不同而定，影像可能會扭曲不良。

需求

   
最低支援的用戶端 Windows 2000 Professional、Windows XP [僅限桌面應用程式]
最低支援的伺服器 Windows Server 2003 [僅限桌面應用程式]
目標平台 Windows
標頭 shobjidl_core.h (包含 Shobjidl.h)
Dll Shell32.dll (4.70 版或更新版本)