IMoniker::GetDisplayName  99L7EA

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

HRESULT GetDisplayName(

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 IBindCtx1JJ0LSF.

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::Alloc1THWWZM to allocate the string returned in ppszDisplayName, and the caller is responsible for calling IMalloc::Free62NW.NT to free it. Both the caller and and the one called use the OLE task allocator returned by CoGetMalloc1012PPO. 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_OPTS3_HO_Y. 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 MkParseDisplayName2DJJ.25 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_OPTS3_HO_Y. 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 CreateItemMonikerLHMVWY 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.

See Also