IMoniker::GetDisplayName

HRESULT IMoniker::GetDisplayName(pbc, pmkToLeft, lplpszDisplayName)

Most monikers have a textual representation which is meaningful to a human being. This function returns the current display name for this moniker, or NULL if none exists.

Some display names may change over time as the object to which the moniker refers moves about in the context in which it lives. Formula references between two Microsoft Excel spreadsheets are an example of this type of changing reference. A formula referring to cell "R1C1" in another sheet may change to the refer to "R2C1" (if a new row is inserted at the top of the second sheet) the reference still refers to the same actual cell, but now the cell has a different address in its sheet. This behavior leads to the general observation that obtaining the current display name of a moniker may have to access at least the storage of the object to which it refers, if not the object itself. Thus, it has the potential to be an expensive operation. As in other IMoniker functions, a bind context parameter is passed which includes a deadline within which the operation should complete, or fail with MK_E_EXCEEDEDDEADLINE if unable to do so.

A consequence of the possible unavailability of quick access to the display name of a moniker is that callers of this function most likely will want to cache the last successful result that they obtained, and use that if the current answer is inaccessible (this caching is the Microsoft Excel between-sheet behavior).

In the general case, the display name of a moniker is not unambiguous: there may be more than one moniker with the same display name, though in practice this will be rare. There is also no guarantee that a display name obtained from a moniker will parse back into that moniker in MkParseDisplayName, though failure to do so also will be rare. Display names should therefore be thought of as a merely a note or annotation on the moniker which aid a human being in distinguishing one moniker from another, rather than a completely equivalent representation of the moniker itself.

Notice that due to how display names are constructed in composites, a moniker which is a prefix of another necessarily has a display name which is a (string) prefix of the display name of the second moniker. The converse, however, does not necessarily hold.

A moniker which is designed to be used as part of a generic composite is responsible for including any preceding delimiter as part of its display name. Many such monikers take a parameter for this delimiter in their instance creation functions.

Argument	Type	Description
pbc	IBindCtx*	The bind context for this operation.
pmkToLeft	IMoniker*	The moniker to the left of this one in the composite in which it is found. Most monikers will not require this in IMoniker::GetDisplayName.
lplpszDisplayName	LPSTR*	On exit, the current display name for this moniker. NULL if the moniker does not have a display name or the deadline was exceeded.
return value	HRESULT	S_OK, MK_E_EXCEEDEDDEADLINE.