IMoniker::GetDisplayName method (objidl.h)

Article
10/13/2021

Retrieves the display name for the moniker.

Syntax

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

Parameters

[in] pbc

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

[in] pmkToLeft

If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is used primarily by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.

[out] ppszDisplayName

The address of a pointer variable that receives a pointer to the display name string for the 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 the implementation of this method use the COM task allocator returned by CoGetMalloc. If an error occurs, the implementation must set *ppszDisplayName should be set to NULL.

Return value

This method can return the standard return values E_OUTOFMEMORY, as well as the following values.

Return code	Description
S_OK	The method completed successfully.
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

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.

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

Implementation-specific Notes

Implementation	Notes
Anti-moniker	For each anti-moniker contained in this moniker, this method return one instance of "\..".
Class moniker	The display name for class monikers is of the following form: clsid:string-clsid-no-curly-braces [";" clsid-param=value*]:. For example, clsid:a7b90590-36fd-11cf-857d-00aa006d2ea4:.
File moniker	This method returns the path that the moniker represents.
Generic composite moniker	This method returns the concatenation of the display names returned by each component moniker of the composite.
Item moniker	This method returns the concatenation of the delimiter and the item name that were specified when the item moniker was created.
OBJREF moniker	This method obtains the display name for the OBJREF moniker. The display name is a 64-bit encoding that encapsulates the machine location, process endpoint, and interface pointer ID (IPID) of the running object. For future compatibility, the display name is restricted to characters that can be specified as part of a URL.
Pointer moniker	This method returns E_NOTIMPL.
URL moniker	The URL moniker attempts to return its full URL string. If the moniker was created with a partial URL string (see CreateURLMonikerEx), it will first attempt to find an URL moniker in the bind context under SZ_URLCONTEXT and will next look to the moniker to its left for contextual information. If it cannot return its full URL string, it will return its partial URL string.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	objidl.h