IMoniker::GetDisplayName - OLE Programmer's Reference

OLE Programmer's Reference

Home Index About

Custom Search

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

Last news from Greatis Software

    Nostalgia .Net     .Net is powerful, but not all-powerful, so sometimes we need to use Win32 API for our .Net applications. It's simple enough with Platform Invoke if you have Win32 skill, but we do not always have time to dig the ancient documentation, declare the special types that are compatible with Win32, find the values of the Win32's constants and so on. Nostalgia .Net offers several simple-to-use classes, and components that will allow you to forget about the headache of Win32 and just use the power of Win32 in your application the same way as you use the native. Net classes. More »

Recommended software for developers

    Ultimate Pack     Component pack for Delphi and C++ Builder that contains runtime form designer, runtime object inspector, print suite and much more for the very special price. More »

    Form Designer .Net     Unique runtime form design solution that allows to edit any form in .Net WinForms application at runtime with full source codes for only 300 euro! More »

    Print Suite .Net     Print Suite .Net is a set of components for easy printing texts, images and grids from your WinForms applications. Full C# source codes are available More »

    Gradient Controls .Net     Gradient Controls .Net offers controls with gradient background feature. Labels, panels and so on... Full C# source codes are available More »

    Greatis iGrid     iGrid plots drawing grid right over your desktop, so you can use it everywhere, with any drawing application without any special plugins for different graphic editors. More »

All the contacts and projects

Dmitry Vasiliev (just.dmitry)

More Online Helps

Win32 Programmer's Reference
Win32 Multimedia Programmer's Reference
OLE Programmer's Reference
Microsoft Windows Pen API Programmer's Reference
Microsoft Windows Sockets 2 Reference
Microsoft Windows Telephony API (TAPI) Programmer's Reference
Unix Manual Pages

greatis just4fun network