Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method returns the display name.

Syntax 

HRESULT GetDisplayName( 
  IBindCtx* 
pbc, 
  IMoniker* 
pmkToLeft, 
  LPOlESTR* 
ppszDisplayName
);

Parameters

pbc

[in] Pointer to the IBindCtxinterface 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] Address of LPOLESTRpointer variable that receives a pointer to the display name string.

When successful, this string is a zero-terminated wide character string (two bytes per character) that contains the display name of the moniker.

The implementation must use the IMalloc::Allocmethod to allocate the string returned in ppszDisplayName, and the caller is responsible for calling the IMalloc::Freemethod to free it.

Both the caller and the implementation of this method use the COM task allocator returned by the CoGetMallocfunction.

If an error occurs, the implementation must set * ppszDisplayNameshould be set to NULL.

Return Value

The method supports the standard return value E_OUTOFMEMORY.

The following table shows the additional return values for this method.

Value Description

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

E_NOTIMPL

There is no display name.

Remarks

IMoniker::GetDisplayNameprovides 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 MkParseDisplayNamefunction 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.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

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::GetDisplayNameshould return MK_E_EXCEEDEDDEADLINE if the name cannot be retrieved by the time specified in the bind context's BIND_OPTSstructure.

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

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.

Requirements

Header objidl.h, objidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also