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

项目
08/26/2023

将文件对象或文件夹的显示名称转换为项标识符列表。

语法

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 值的指针，该值接收已分析的显示名称的字符数。如果应用程序不需要此信息，请将 pchEaten 设置为 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 隐式验证项是否存在，除非该行为被特殊的绑定上下文参数重写。

查询某些属性可能相对较慢，并且会占用大量内存。例如，为了确定是否共享文件，Shell 将加载网络组件。此过程可能需要加载多个 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

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

语法

参数

返回值

注解

要求

另请参阅

反馈

反馈

其他资源