Windows Dev Center

IParseDisplayName::ParseDisplayName method

Parses the specified display name and creates a corresponding moniker.

Syntax


HRESULT ParseDisplayName(
  [in]  IBindCtx *pbc,
  [in]  LPOLESTR pszDisplayName,
  [out] ULONG    *pchEaten,
  [out] IMoniker **ppmkOut
);

Parameters

pbc [in]

A pointer to the bind context to be used in this binding operation. See IBindCtx.

pszDisplayName [in]

The display name to be parsed.

pchEaten [out]

A pointer to a variable that receives the number of characters in the display name that correspond to the ppmkOut moniker.

ppmkOut [out]

A pointer to an 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 AddRef; it is the caller's responsibility to call Release.

Return value

This method can return the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following values.

Return codeDescription
S_OK

The method completed successfully.

MK_E_SYNTAX

There is a syntax error in the display name. Parsing failed because pszDisplayName 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 not valid.

 

Remarks

In general, the maximum prefix of pszDisplayName 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 or MkParseDisplayNameEx. In the initial step of the parsing operation, these functions 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 loops of MkParseDisplayName and MkParseDisplayNameEx find 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 or MkParseDisplayNameEx function passes NULL in the pmkToLeft parameter. If the moniker currently held 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 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::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.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

OleIdl.h

IDL

OleIdl.idl

IID

IID_IParseDisplayName is defined as 0000011a-0000-0000-C000-000000000046

See also

IMoniker::ParseDisplayName
IParseDisplayName
MkParseDisplayName
MkParseDisplayNameEx

 

 

Community Additions

ADD
Show:
© 2015 Microsoft