Contents Previous Page Next Page
IParseDisplayName::ParseDisplayName

Parses a display name and returns a moniker representing it.

HRESULT ParseDisplayName(

    IBindCtx*
pbc,                   //Pointer to bind context                                                         
                                                                                                                      
    LPWSTR  szDisplayName,          //Display name to be parsed                                                       
                                                                                                                      
    ULONG *pcchEaten,               //Pointer to the number of characters of the display name successfully parsed     
                                                                                                                      
    IMoniker **ppmk                 //Indirect pointer to a moniker                                                   
                                                                                                                      
   );                                                                                                                 
                                                                                                                      

Parameters

pbc

[in] Pointer to the bind context in which to accumulate bound objects.

szDisplayName

[in] Display name to be parsed.

pcchEaten

[out] Pointer to the number of characters of the display name that were consumed in this parse.

ppmk

[out] Indirect pointer to the resulting moniker.

Return Values

S_OK

The operation was successful.

MK_E_SYNTAX

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

E_INVALIDARG

One or more parameters are invalid.

Remarks

In general, the maximal prefix of szDisplayName that is syntactically valid and that represents an object should be consumed.

The initial step of MkParseDisplayName[Ex] can retrieve this interface directly from an instance of the class identified with either ô@ProgIDö or ôProgIDö notation. Later parsing steps can request this interface on an intermediate object.

The main loop of MkParseDisplayName[Ex] finds the next moniker piece by calling the IMoniker-equivalent function (IMoniker::ParseDisplayName) on the moniker-so-far that it holds on to, passing NULL in the pmkToLeft parameter. In case the moniker-so-far is a generic composite, this 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.

If a syntax error occurs, then NULL should be returned through ppmkOut and MK_E_SYNTAX returned. In addition, the number of characters of the display name that were successfully parsed should be returned through pcchEaten.

See Also

MkParseDisplayNameEx