IMoniker::GetDisplayName 方法 (objidl.h)

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

语法

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

参数

[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 的第一次成功调用的结果,而不是进行重复调用。

实现者的注释

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

旨在成为泛型复合名字对象一部分的名字对象应包括任何前面的分隔符 (,例如“') 作为其显示名称的一部分。 例如,项名字对象返回的显示名称包括使用 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