IMoniker::GetDisplayName

Gets the display name , which is a user-readable representation of this moniker.

HRESULT GetDisplayName(

IBindCtx *pbc,

//Pointer to bind context to be used

IMoniker *pmkToLeft,

//Pointer to moniker to the left in the composite

LPOLESTR *ppszDisplayName

//Indirect pointer to the display name

);

Parameters

pbc: [in] Pointer to the IBindCtx interface on 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.
pmkToLeft: [in] If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.
ppszDisplayName: [out] When successful, indirect pointer to a zero-terminated wide character string (two bytes per character) containing the display name of this moniker. 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 the caller and and the one called use the OLE task allocator returned by CoGetMalloc. If an error occurs, ppszDisplayName should be set to NULL.

Return Values

The method supports the standard return value E_OUTOFMEMORY

, as well as the following:

S_OK: The display name was successfully supplied.
MK_E_EXCEEDEDDEADLINE: The binding operation could not be completed within the time limit specified by the bind context’s BIND_OPTS structure.
E_NOTIMPL: There is no display name.

Remarks

IMoniker::GetDisplayName provides a string that is a displayable representation of the moniker. A display name is not a complete representation of a moniker’s internal state; it is simply a form that can be read by users. As a result, it is possible (though rare) for two different monikers to have the same display name. While there is no guarantee that the display name of a moniker can be parsed back into that moniker when calling the MkParseDisplayName function with it, failure to do so is rare.

As examples, the file moniker implementation of this method supplies the path the moniker represents, and an item moniker’s display name is the string identifying the item that is contained in the moniker.

Notes to Callers

It is 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 Implementers

If you are writing a moniker class in which the display name does not change, simply cache the display name and supply the cached name 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 structure.

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 function. The display name for a file moniker does not include a delimiter because file monikers are always expected to be the leftmost component of a composite.

IBindCtx *pbc,	//Pointer to bind context to be used
IMoniker *pmkToLeft,	//Pointer to moniker to the left in the composite
LPOLESTR *ppszDisplayName	//Indirect pointer to the display name
);