IOleClientSite::GetMoniker  FSXISS

Returns a moniker to an object s client site. An object can force the assignment of its own or its container s moniker by specifying a value for dwAssign.

HRESULT GetMoniker(

Parameters

dwAssign

[in] Specifies whether to get a moniker only if one already exists, force assignment of a moniker, create a temporary moniker, or remove a moniker that has been assigned. In practice, you will usually request that the container force assignment of the moniker. Values defining these choices are contained in the enumeration OLEGETMONIKER5FIC_6X.

dwWhichMoniker

[in] DWORD that specifies whether to return the container s moniker, the object s moniker relative to the container, or the object s full moniker. In practice, you will usually request the object s full moniker. Values defining these choices are contained in the enumeration OLEWHICHMK27EJCN5.

ppmk

[out] Indirect pointer to the IMoniker interface on the moniker for the object s client site. If an error is returned, this parameter must be set to NULL. Each time a container receives a call to IOleClientSite::GetMoniker, it must increase the reference count on the pointer it returns. It is the caller s responsibility to call Release when it is done with the pointer.

Return Values

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

S_OK

Requested moniker returned successfully.

E_NOTIMPL

This container cannot assign monikers to objects. This is the case with OLE 1 containers.

Remarks

Containers implement IOleClientSite::GetMoniker as a way of passing out monikers for their embedded objects to clients wishing to link to those objects.

When a link is made to an embedded object or to a pseudo-object within it (a range of cells in a spreadsheet, for example), the object needs a moniker to construct the composite moniker indicating the source of the link. If the embedded object does not already have a moniker, it can call IOleClientSite::GetMoniker to request one.

Every container that expects to contain links to embeddings should support IOleClientSite::GetMoniker to give out OLEWHICHMK_CONTAINER, thus enabling link tracking when the link client and link source files move, but maintain the same relative position.

An object must not persistently store its full moniker or its container s moniker, because these can change while the object is not loaded. For example, either the container or the object could be renamed, in which event, storing the container s moniker or the object s full moniker would make it impossible for a client to track a link to the object.

In some very specialized cases, an object may no longer need a moniker previously assigned to it and may wish to have it removed as an optimization. In such cases, the object can call IOleClientSite::GetMoniker with OLEGETMONIKER_UNASSIGN to have the moniker removed.

See Also