IParseDisplayName::ParseDisplayName

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.

HRESULT ParseDisplayName(
  IBindCtx *pbc,     //Pointer to bind context
  LPOLESTR pszDisplayName, 
                     //Pointer to string containing display name
  ULONG *pchEaten,   //Pointer to length, in characters, of display 
                     //name
  IMoniker **ppmkOut //Address of output variable that receives the 
                     //resulting IMoniker interface pointer
);

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 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 ppmkOut moniker.
ppmkOut: [out] Address of IMoniker* pointer variable that receives the interface pointer to the resulting moniker. If an error occurs, the implementation sets *ppmkOut to NULL. If *ppmkOut is non-NULL, the implementation must call (*ppmkOut)->IUnknown::AddRef; so it is the caller's responsibility to call (*ppmkOut)->IUnknown::Release.

Return Values

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 szDisplayName could only be partially resolved into a moniker. In this case, *pchEaten has the number of characters that were successfully parsed into a moniker prefix. The parameter ppmkOut should 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 szDisplayName that 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[Ex]. In the initial step of the parsing operation, the MkParseDisplayName[Ex] function can retrieve the IParseDisplayName interface 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 MkParseDisplayName[Ex] finds the next moniker piece by calling the equivalent method in the IMoniker interface, that is, IMoniker::ParseDisplayName, on the moniker that it currently holds. In this call to IMoniker::ParseDisplayName, the MkParseDisplayName[Ex] function passes NULL in the pmkToLeft parameter. If the moniker currently held by MkParseDisplayName[Ex] is a generic composite, the call to IMoniker::ParseDisplayName is 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 since 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::ParseDisplayName but instead should be transferred to the bind context via IBindCtx::RegisterObjectBound or IBindCtx::GetRunningObjectTable followed by IRunningObjectTable::Register for release at a later time.

QuickInfo

  Windows NT: Use version 3.1 or later.
  Windows: Use Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in oleidl.h.