IMoniker::GetDisplayName - OLE Programmer's Reference (ole.hlp)

IMoniker::GetDisplayName

Returns the display name that is, the user-readable representation of this moniker.

HRESULT GetDisplayName(

IBindCtx *pbc,	//Bind context to be used
IMoniker *pmkToLeft,	//Moniker to the left in the composite
LPOLESTR *ppszDisplayName	//Receives the display name
);

Parameters
pbc

[in] Points to 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] Points to the moniker to the left of this moniker, if this moniker is part of a composite. This parameter is primarily used by moniker implementors to enable cooperation between the various components of a composite moniker; moniker clients can usually pass NULL.

ppszDisplayName

[out] Receives a pointer to a zero-terminated string containing the display name of this moniker. If an error occurs, *ppszDisplayName is set to NULL; otherwise, 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 caller and callee use the allocator returned by CoGetMalloc(MEMCTX_TASK, ...). For Win32 applications, the LPOLESTR type indicates a wide character string (two bytes per character); otherwise, the string has one byte per character.

Return Values
S_OK

Indicates the display name was successfully returned.

MK_E_EXCEEDEDDEADLINE

Indicates that the binding operation could not be completed within the time limit specified by the bind context's BIND_OPTS structure.

E_OUTOFMEMORY

Indicates insufficient memory.

E_NOTIMPL

There is no display name.

Comments
As examples of display names, a file moniker's display name is the path the moniker represents, and an item moniker's display name is the string contained in the moniker. However, a display name is not necessarily a complete representation of a moniker's internal state; it is simply a form readable by users. As a result, it is possible (though rare) for two different monikers to have the same display name. There is also no guarantee that the display name of a moniker can be parsed back into that moniker when calling the MkParseDisplayName API function with it, though failure to do so is also rare.

Notes to Callers
It's 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 Implementors
If you are writing a moniker class in which the display name does not change, simply cache the display name and return that 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 API function. The display name for a file moniker does not include a delimiter because file monikers always expect to be the leftmost component of a composite.

See Also
IMoniker::ParseDisplayName, MkParseDisplayName

More Online Helps

Win32 Programmer's Reference (win32.hlp)
Win32 Multimedia Programmer's Reference (mmedia.hlp)
Microsoft Windows Pen API Programmer's Reference (penapi.hlp)
Microsoft Windows Sockets 2 Reference (sock2.hlp)
Microsoft Windows Telephony API (TAPI) Programmer's Reference (sock2.hlp)
Unix Manual Pages

greatis just4fun network