IShellFolder：:P arseDisplayName 方法 (shobjidl_core.h)

  • 發行項

將檔案對象的顯示名稱或資料夾轉譯成專案識別碼清單。

語法

HRESULT ParseDisplayName(
  [in]      HWND             hwnd,
  [in]      IBindCtx         *pbc,
  [in]      LPWSTR           pszDisplayName,
  [out]     ULONG            *pchEaten,
  [out]     PIDLIST_RELATIVE *ppidl,
  [in, out] ULONG            *pdwAttributes
);

參數

[in] hwnd

類型： HWND

視窗控制代碼。 如果客戶端顯示對話框或消息框，客戶端應該提供視窗句柄。 否則，請將 hwnd 設定為 NULL。

[in] pbc

類型： IBindCtx*

選擇性。 系結內容的指標，用來將參數當做輸入和輸出傳遞至剖析函式。 這些傳遞的參數通常專屬於數據源，並由數據源擁有者記載。 例如，檔案系統數據源會使用STR_FILE_SYS_BIND_DATA系結內容參數，接受 (剖析為WIN32_FIND_DATA結構) 的名稱。 STR_PARSE_PREFER_FOLDER_BROWSING 可以傳遞，以指出 URL 會在可能的情況下使用檔案系統數據源進行剖析。 使用 CreateBindCtx 建構系結內容物件，並使用 IBindCtx：：RegisterObjectParam 填入值。 如需這些完整清單，請參閱 系結內容字串密鑰 。

如果未將數據傳遞至剖析函式或從剖析函式接收數據，這個值可以是 NULL。

[in] pszDisplayName

類型： LPWSTR

以 Null 結尾的 Unicode 字串，其顯示名稱為 。 因為每個 Shell 資料夾都會定義自己的剖析語法，所以此字串可能採用的格式可能會有所不同。 例如，桌面資料夾接受 「C：\My Docs\My File.txt」 等路徑。 它也會接受命名空間中具有與這些專案相關聯之 GUID 的參考，這些專案使用 “：：{GUID}” 語法。 例如，若要從桌面資料夾擷取控制面板的完整標識碼清單，您可以使用下列專案：

::{CLSID for Control Panel}\::{CLSID for printers folder}

[out] pchEaten

類型： ULONG*

ULONG 值的指標，接收已剖析之顯示名稱的字元數。 如果您的應用程式不需要這項資訊，請將 pch為 NULL 設定為 NULL，而且不會傳回任何值。

[out] ppidl

類型： PIDLIST_RELATIVE*

當這個方法傳回時，會包含 物件的 PIDL 指標。 傳回的專案識別碼清單會指定相對於剖析資料夾的專案。 如果與 pszDisplayName 相關聯的對象位於剖析資料夾中，則傳回的專案標識碼清單只會包含一個 SHITEMID 結構。 如果對象位於剖析資料夾的子資料夾中，則傳回的專案識別符清單將包含多個 SHITEMID 結構。 如果發生錯誤，則會在此位址中傳回 NULL 。

不再需要時，呼叫者必須呼叫 CoTaskMemFree 來釋出此資源。

[in, out] pdwAttributes

類型： ULONG*

用來查詢檔案屬性的值。 如果未使用，它應該設定為 NULL。 若要查詢一或多個屬性，請使用代表感興趣屬性的 SFGAO 旗標來初始化此參數。 傳回時，將會設定為 true 且 已要求的屬性。

傳回值

類型： HRESULT

如果此方法成功，則會傳回 S_OK。 否則，它會傳回 HRESULT 錯誤碼。

備註

某些 Shell 資料夾可能無法實作 IShellFolder：:P arseDisplayName。 每個確實會定義其剖析語法的資料夾。

ParseDisplayName 不預期會處理相對路徑或父資料夾指標 (“.” 或 “.”。) 。 呼叫端必須適當地移除這些專案。

請勿在 pdwAttributes 中使用SFGAO_VALIDATE旗標，以確認其名稱正在剖析的專案是否存在。 IShellFolder：:P arseDisplayName 會隱含地驗證專案是否存在，除非特殊系結內容參數會覆寫該行為。

查詢某些屬性可能相當慢，而且使用大量的記憶體。 例如，若要判斷檔案是否共用，殼層會載入網路元件。 此程式可能需要載入數個 DLL。 pdwAttributes 的目的是讓您只將查詢限制為所需的資訊。 下列代碼段說明如何找出檔案是否已壓縮。

LPITEMIDLIST pidl;
ULONG cbEaten;
DWORD dwAttribs = SFGAO_COMPRESSED;

hres = psf->ParseDisplayName(NULL,
                             NULL,
                             lpwszDisplayName,
                             &cbEaten,  // This can be NULL
                             &pidl,
                             &dwAttribs);

if(dwAttribs & SFGAO_COMPRESSED)
{
    // Do something with the compressed file
}

由於 pdwAttributes 是 in/out 參數，因此應該一律初始化。 如果您傳入未初始化的值，可能會不小心設定部分位。 IShellFolder：:P arseDisplayName 接著會查詢對應的屬性，這可能會導致不必要的延遲或記憶體需求。 如果您不想查詢屬性，請將 pdwAttributes 設定為 NULL 以避免無法預期的行為。

這個方法類似於 IParseDisplayName：:P arseDisplayName 方法。

規格需求

需求 值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限傳統型應用程式]
目標平台 Windows
標頭 shobjidl_core.h (包括 Shobjidl.h)
Dll Shell32.dll (4.0 版或更新版本)

另請參閱

IShellFolder

IShellFolder2

IShellFolder：：GetAttributesOf

IShellLink