SHGetDataFromIDListA 函式 (shlobj_core.h)

發行項
03/02/2024

從相對標識碼清單中擷取擴充屬性數據。

語法

SHSTDAPI SHGetDataFromIDListA(
  [in]  IShellFolder    *psf,
  [in]  PCUITEMID_CHILD pidl,
        int             nFormat,
  [out] void            *pv,
        int             cb
);

參數

[in] psf

類型： IShellFolder*

父 IShellFolder 介面的位址。這必須是 pidl 參數所參考之 ITEMIDLIST 結構的直接父代。

[in] pidl

類型： PCUITEMID_CHILD

ITEMIDLIST 結構的指標，可識別物件相對於 psf 中指定的資料夾。

nFormat

類型： int

要求數據的格式。此參數必須設定為下列其中一個值。

SHGDFIL_FINDDATA

用於檔案系統物件的格式。 pv 參數是WIN32_FIND_DATA結構的位址。

SHGDFIL_NETRESOURCE

用於網路資源的格式。 pv 參數是 NETRESOURCE 結構的位址。

SHGDFIL_DESCRIPTIONID

4.71 版。用於網路資源的格式。 pv 參數是 SHDESCRIPTIONID 結構的位址。

[out] pv

類型： void*

緩衝區的指標，當此函式成功傳回時，會收到要求的數據。此緩衝區的格式是由 nFormat 決定。

如果 nFormatSHGDFIL_NETRESOURCE，則有兩個可能的情況。如果緩衝區夠大，則網路名稱、本機名稱、提供者和批註) (欄位的 net 資源字串資訊將會放在緩衝區中。如果緩衝區不夠大，則只會將 net 資源結構放入緩衝區，而字串資訊指標會是 NULL。

cb

類型： int

pv 的緩衝區大小，以位元組為單位。

傳回值

類型： HRESULT

如果成功，則傳回S_OK，否則傳回E_INVALIDARG。

備註

此函式只會擷取存在於專案標識符清單指標中的資訊， (PIDL) 。由於 PIDL 的內容取決於建立 PIDL 的資料夾物件，因此不保證所有要求的資訊都可以使用。此外，傳回的資訊會反映建立 PIDL 時的對象狀態。物件的目前狀態可能不同。例如，如果您將 nFormat 設定為 SHGDFIL_FINDDATA，函式可能會只將有意義的值指派給 WIN32_FIND_DATA 結構的某些成員。其餘成員會設定為零。若要擷取文件系統檔案或資料夾的完整目前資訊，請使用 GetFileTime 或 FindFirstFile 等標準文件系統功能。

如果 psf、 pidl、 pv 或 cb 參數不符合 nFormat 參數，或 nFormat 不是上述特定SHGDFIL_值之一，則會傳回E_INVALIDARG。

注意

shlobj_core.h 標頭會將SHGetDataFromIDList定義為別名，根據UNICODE預處理器常數的定義，自動選取此函式的ANSI或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	shlobj_core.h (包含 Shlobj.h、Shlobj_core.h)
程式庫	Shell32.lib
Dll	Shell32.dll (4.0 版或更新版本)
API 集合	ext-ms-win-shell32-l1-2-1 (於 Windows 10 10.0.10240 版)