CreateURLMoniker

Creates an URL moniker from either a full URL string or from a base context URL moniker and a partial URL string.

HRESULT CreateURLMoniker(

IMoniker *pmkContext,	//Pointer to the base context moniker
LPWSTR szURL,	//Display name to be parsed
IMoniker **ppmk	//Indirect pointer to IMoniker for the new URL moniker
);

Parameters

pmkContext

[in] Pointer to the IMoniker interface for the URL moniker to use as the base context when the szURL parameter is a partial URL string. The pmkContext parameter can be NULL. In this case, one of the following methods is used to provide the context:

• The szURL parameter is a full URL string needing no further context.

• The leftmost portion of the moniker contains the URL context.

• The moniker retrieves the URL context from the bind-context during IMoniker::BindToObject or IMoniker::BindToStorage.

szURL

[in] Display name to be parsed.

ppmk

[out] Indirect pointer to an IMoniker interface for the new URL moniker.

Return Values

S_OK

The operation was successful.

E_OUTOFMEMORY

The operation ran out of memory.

MK_E_SYNTAX

A moniker could not be created because szURL does not correspond to valid URL syntax for a full or partial URL. This is uncommon, since most parsing of the URL occurs during binding and also since the syntax for URLs is extremely flexible.

Remarks

Partial URLs are similar to relative paths within file systems, in that resolution to an object requires a context outside the partial string alone. Full URL strings are like fully-qualified paths; they are self-contained and often location-independent.

When creating an URL moniker from a partial URL string specified in szURL, the caller can specify a context with a partial URL moniker in the pmkContext parameter. In this case, the CreateURLMoniker function retrieves the display name of pmkContext (by calling the IMoniker::GetDisplayName method) and manually composes it with szURL according to URL composition rules.

The caller can alternately create a moniker from a partial URL string when the pmkContext parameter is set to NULL. In this case, the resulting moniker obtains further context during binding (either through IMoniker::BindToObject or IMoniker::BindToStorage). The moniker goes through the following steps to obtain the additional context:

1. First, it obtains the URL context from the passed IBindCtx by using the following call:

IBindCtx::GetObjectParam(SZ_URLCONTEXT, (IUnknown**)&pmkContext)
 

1. Then, the moniker obtains the URL context from its leftmost portion which contains another URL moniker from which to obtain the URL context.

See Also

TBD