Share via

IMoniker::GetDisplayName (Compact 2013)

  • Article

3/26/2014

This method returns the display name.

Syntax

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

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] Address of LPOLESTR pointer 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::Alloc method to allocate the string returned in ppszDisplayName, and the caller is responsible for calling the IMalloc::Free method to free it.

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

    If an error occurs, the implementation must set *ppszDisplayName should 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_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.

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

Requirements

Header

objidl.h,
objidl.idl

Library

ole32.lib,
uuid.lib

See Also

Reference

IMoniker
CoGetMalloc
CreateItemMoniker
MkParseDisplayName
BIND_OPTS