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 parses the display name to extract a component of the string that it can convert into a moniker, using the maximum number of characters from the left side of the string.

Syntax 

HRESULT ParseDisplayName(
  IBindCtx* 
pbc,
  LPOLESTR 
pszDisplayName, 
  ULONG* 
pchEaten,
  IMoniker** 
ppmkOut 
);

Parameters

pbc

[in] Pointer to the bind context to be used in this binding operation.

pszDisplayName

[in] Pointer to a zero-terminated string containing the display name to be parsed. For Microsoft Win32® applications, the LPOLESTR type indicates a wide character string (two bytes per character); otherwise, the string has one byte per character.

pchEaten

[out] Pointer to the number of characters in the display name that correspond to the ppmkOutmoniker.

ppmkOut

[out] Address of IMoniker* pointer variable that receives the interface pointer to the resulting moniker.

If an error occurs, the implementation sets * ppmkOutto NULL.

If * ppmkOutis non-NULL, the implementation must call (*ppmkOut)->IUnknown::AddRef;so it is the caller's responsibility to call (*ppmkOut)->IUnknown::Release.

Return Value

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The parse operation was successful.

MK_E_SYNTAX

Syntax error in the display name.

Parsing failed because szDisplayNamecould only be partially resolved into a moniker. In this case, * pchEatenhas the number of characters that were successfully parsed into a moniker prefix.

The parameter ppmkOutshould be NULL.

MK_E_NOOBJECT

The display name does not identify a component in this namespace.

E_INVALIDARG

One or more parameters are invalid.

Remarks

In general, the maximum prefix of szDisplayNamethat is syntactically valid and that represents an object should be consumed by this method and converted to a moniker.

Typically, this method is called by MkParseDisplayName. In the initial step of the parsing operation, the MkParseDisplayNamefunction can retrieve the IParseDisplayNameinterface directly from an instance of a class identified with either the @ProgID or ProgID notation. Subsequent parsing steps can query for the interface on an intermediate object.

The main loop of MkParseDisplayNamefinds the next moniker piece by calling the equivalent method in the IMonikerinterface, that is, IMoniker::ParseDisplayName, on the moniker that it currently holds. In this call to IMoniker::ParseDisplayName, the MkParseDisplayNamefunction passes NULL in the pmkToLeftparameter.

If the moniker currently held by MkParseDisplayNameis a generic composite, the call to IMoniker::ParseDisplayNameis forwarded by that composite onto its last piece, passing the prefix of the composite to the left of the piece in pmkToLeft.

Some moniker classes will be able to handle this parsing internally to themselves because they are designed to designate only certain kinds of objects. Others will need to bind to the object that they designate to accomplish the parsing process.

As is usual, these objects should not be released by IMoniker::ParseDisplayNamebut instead should be transferred to the bind context through IBindCtx::RegisterObjectBoundor IBindCtx::GetRunningObjectTablefollowed by IRunningObjectTable::Registerfor release at a later time.

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

Requirements

Header Oleidl.h, oleidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also