Returns the display name
that is, the user-readable representation
of this moniker.
| IBindCtx *pbc,
||//Bind context to be used
| IMoniker *pmkToLeft,
||//Moniker to the left in the composite
| LPOLESTR *ppszDisplayName
||//Receives the display name
[in] Points to the bind context to be used in this operation. The bind context
caches objects bound during the binding process, contains parameters that
apply to all operations using the bind context, and provides the means by which the
moniker implementation should retrieve information about its environment. For
more information, see IBindCtx
[in] Points to the moniker to the left of this moniker, if this moniker is
part of a composite. This parameter is primarily used by moniker implementors to
enable cooperation between the various components of a composite moniker;
moniker clients can usually pass NULL.
[out] Receives a pointer to a zero-terminated string containing the display
name of this moniker. If an error occurs, *ppszDisplayName
is set to NULL; otherwise, the implementation must use IMalloc::Alloc
to allocate the string returned in ppszDisplayName
, and the caller is responsible for calling IMalloc::Free
to free it. Both caller and callee use the allocator returned by CoGetMalloc
(MEMCTX_TASK, ...). For Win32 applications, the LPOLESTR
type indicates a wide character string (two bytes per character); otherwise,
the string has one byte per character.
Indicates the display name was successfully returned.
Indicates that the binding operation could not be completed within the time
limit specified by the bind context's BIND_OPTS
Indicates insufficient memory.
There is no display name.
As examples of display names, a file moniker's display name is the path the
moniker represents, and an item moniker's display name is the string contained in
the moniker. However, a display name is not necessarily a complete
representation of a moniker's internal state; it is simply a form readable by users. As a
result, it is possible (though rare) for two different monikers to have the
same display name. There is also no guarantee that the display name of a moniker
can be parsed back into that moniker when calling the MkParseDisplayName
API function with it, though failure to do so is also rare.
Notes to Callers
It's possible that retrieving a moniker's display name may be an expensive
operation. For efficiency, you may want to cache the results of the first
successful call to IMoniker::GetDisplayName
, rather than making repeated calls.
Notes to Implementors
If you are writing a moniker class in which the display name does not change,
simply cache the display name and return that when requested. If the display
name can change over time, getting the current display name might mean that the
moniker has to access the object's storage or bind to the object, either of
which can be expensive operations. If this is the case, your implementation of IMoniker::GetDisplayName
should return MK_E_EXCEEDEDDEADLINE if the name cannot be retrieved by the
time specified in the bind context's BIND_OPTS
A moniker that is intended to be part of a generic composite moniker should
include any preceding delimiter (such as '\') as part of its display name. For
example, the display name returned by an item moniker includes the delimiter
specified when it was created with the CreateItemMoniker
API function. The display name for a file moniker does not include a
delimiter because file monikers always expect to be the leftmost component of a
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages