IMoniker：：GetDisplayName 方法 (objidl.h)

  • 项目

检索名字对象的显示名称。

语法

HRESULT GetDisplayName(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [out] LPOLESTR *ppszDisplayName
);

parameters

[in] pbc

指向要用于此操作的绑定上下文上的 IBindCtx 接口的指针。 绑定上下文缓存绑定过程中绑定的对象，包含应用于使用绑定上下文的所有操作的参数，并提供名字对象实现应检索有关其环境的信息的方法。

[in] pmkToLeft

如果名字对象是复合名字对象的一部分，则指向此名字对象左侧的名字对象指针。 此参数主要由名字对象实现者用于启用复合名字对象的各个组件之间的协作。 名字对象客户端应传递 NULL。

[out] ppszDisplayName

指针变量的地址，该变量接收指向名字对象的显示名称字符串的指针。 实现必须使用 IMalloc：：Alloc 来分配 ppszDisplayName 中返回的字符串，调用方负责调用 IMalloc：：Free 以释放它。 调用方和此方法的实现都使用 CoGetMalloc 返回的 COM 任务分配器。 如果发生错误，则实现必须将 *ppszDisplayName 设置为 NULL。

返回值

此方法可以返回E_OUTOFMEMORY的标准返回值，以及以下值。

返回代码 说明
S_OK
 该方法已成功完成。
MK_E_EXCEEDEDDEADLINE
 无法在绑定上下文 BIND_OPTS 结构指定的时间限制内完成绑定操作。
E_NOTIMPL
 没有显示名称。

注解

GetDisplayName 提供一个字符串，该字符串是名字对象的可显示表示形式。 显示名称不是名字对象内部状态的完整表示形式;它只是一种可由用户读取的表单。 因此，尽管两个不同的名字对象具有相同的显示名称，但 (但很少见) 。 虽然不能保证在调用 MkParseDisplayName 函数时，名字对象的显示名称可以解析回该名字对象，但这种情况很少见。

给调用方的说明

检索名字对象的显示名称可能是一项开销高昂的操作。 为了提高效率，你可能希望缓存对 GetDisplayName 的第一次成功调用的结果，而不是重复调用。

实施者说明

如果要编写名字对象类，其中显示名称不会更改，只需缓存显示名称，并在请求时提供缓存的名称。 如果显示名称可以随时间而更改，则获取当前显示名称可能意味着名字对象必须访问对象的存储或绑定到对象，其中任一操作都可能很昂贵。 如果是这种情况，如果无法在绑定上下文BIND_OPTS结构中指定的时间检索名称，则 GetDisplayName 的实现应返回 MK_E_EXCEEDEDDEADLINE 。

旨在作为泛型复合名字对象一部分的名称对象应包含任何前面的分隔符 (，例如“”) 作为其显示名称的一部分。 例如，项名字对象返回的显示名称包括使用 CreateItemMoniker 函数创建时指定的分隔符。 文件名字对象的显示名称不包括分隔符，因为文件名字对象应始终是复合的最左侧组件。

特定于实现的注释

实现 注释
反名字对象 对于此名字对象中包含的每个反名字对象，此方法返回“\..”的一个实例。
类名字对象 类名字对象的显示名称采用以下形式：clsid：string-clsid-no-curly-braces *[“;” clsid-param=value]：。 例如，clsid：a7b90590-36fd-11cf-857d-00aa006d2ea4：。
文件名字对象 此方法返回名字对象表示的路径。
泛型复合名字对象 此方法返回由复合的每个组件名字对象返回的显示名称串联。
项名字对象 此方法返回分隔符的串联以及创建项名字对象时指定的项名称。
OBJREF 名字对象 此方法获取 OBJREF 名字对象的显示名称。 显示名称是一种 64 位编码，用于封装正在运行的对象的计算机位置、进程终结点和接口指针 ID (IPID) 。 为了将来的兼容性，显示名称仅限于可以指定为 URL 的一部分的字符。
指针名字对象 此方法返回E_NOTIMPL。
URL 名字对象 URL 名字对象尝试返回其完整的 URL 字符串。 如果名字对象是使用部分 URL 字符串创建的 (请参阅 CreateURLMonikerEx) ，它将首先尝试在绑定上下文中的SZ_URLCONTEXT下查找 URL 名字对象，然后查找其左侧的名字对象以获取上下文信息。 如果无法返回其完整 URL 字符串，它将返回其部分 URL 字符串。

要求

   
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 objidl.h

请参阅

IMoniker

MkParseDisplayName