IOleClientSite::GetMoniker

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(
  DWORD dwAssign,  //Value specifying how moniker is assigned
  DWORD dwWhichMoniker,
                   //Value specifying which moniker is assigned
  IMoniker ** ppmk //Address of output variable that receives the 
                   // IMoniker interface pointer
);

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 OLEGETMONIKER.
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 OLEWHICHMK.
ppmk: [out] Address of IMoniker* pointer variable that receives the interface pointer to the moniker for the object's client site. If an error occurs, the implementation must set *ppmk to NULL. Each time a container receives a call to IOleClientSite::GetMoniker, it must increase the reference count on the *ppmk 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.

QuickInfo

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