IMoniker::BindToObject

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method binds to the object named by the moniker.

Syntax

HRESULT BindToObject( 
  IBindCtx* pbc, 
  IMoniker* pmkToLeft, 
  REFIID riidResult, 
  void** ppvResult
);

Parameters

• pbc
  [in] Pointer to the IBindCtx interface on the bind context object, which is used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment.

• pmkToLeft
  [in] If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.

• riidResult
  [in] Reference to the identifier of the interface the client wants to use to communicate with the object that the moniker identifies.

• ppvResult
  [out] Address of the pointer variable that receives the interface pointer requested in riid.

  Upon successful return, *ppvResult contains the requested interface pointer to the object the moniker identifies. When successful, the implementation must call the IUnknown::AddRef method on the moniker.

  It is the caller's responsibility to release the object with a call to the IUnknown::Release method.

  If an error occurs, *ppvResult should be NULL.

Return Value

The method supports the standard return values, E_UNEXPECTED and E_OUTOFMEMORY. The following table shows the additional return values for this method.

Remarks

IMoniker::BindToObject implements the primary function of a moniker, which is to locate the object identified by the moniker and return a pointer to one of its interfaces.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Notes to Callers

If you are using a moniker as a persistent connection between two objects, you activate the connection by calling IMoniker::BindToObject.

You typically call IMoniker::BindToObject during the following process:

1. Create a bind context object with a call to the CreateBindCtx function.
2. Call IMoniker::BindToObject using the moniker, retrieving a pointer to a desired interface on the identified object.
3. Release the bind context.
4. Through the acquired interface pointer, perform the desired operations on the object.
5. When finished with the object, release the object's interface pointer.

The following code example shows how to complete these steps.

// pMnk is an IMoniker * that points to a previously acquired moniker 
// ICellRange is a custom interface designed for an object that is a 
//            range of spreadsheet cells 
ICellRange *pCellRange; 
IBindCtx *pbc; 
 
CreateBindCtx( 0, &pbc ); 
pMnk->BindToObject( pbc, NULL, IID_ICellRange, &pCellRange ); 
pbc->Release(); 
// pCellRange now points to the object; safe to use pCellRange 
pCellRange->Release(); 

You can also use the BindMoniker function when you only intend one binding operation and do not need to retain the bind context object. This helper function encapsulates the creation of the bind context, calling IMoniker::BindToObject, and releasing the bind context.

COM containers that support links to objects use monikers to locate and get access to the linked object, but typically do not call IMoniker::BindToObject directly.

Instead, when a user activates a link in a container, the link container usually calls the IOleObject::DoVerb method, using the link handler's implementation, which calls IMoniker::BindToObject on the moniker stored in the linked object (if it cannot handle the verb).

Notes to Implementers

What your implementation does depends on whether you expect your moniker to have a prefix, that is, whether you expect the pmkToLeft parameter to be NULL or not.

For example, an item moniker, which identifies an object within a container, expects that pmkToLeft identifies the container. An item moniker consequently uses pmkToLeft to request services from that container.

If you expect your moniker to have a prefix, you should use the pmkToLeft parameter (for instance, calling IMoniker::BindToObject on it) to request services from the object it identifies.

If you expect your moniker to have no prefix, your IMoniker::BindToObject implementation should first check the Running Object Table (ROT) to see if the object is already running.

To acquire a pointer to the ROT, your implementation should call the IBindCtx::GetRunningObjectTable method on the pbc parameter.

You can then call the IRunningObjectTable::GetObject method to see if the current moniker has been registered in the ROT. If so, you can immediately call the IUnknown::QueryInterface method to get a pointer to the interface requested by the caller.

Requirements

See Also

Reference

BindMoniker
CreateBindCtx
IMoniker::GetDisplayName
IOleObject::DoVerb
IUnknown::AddRef
IUnknown::Release
BIND_OPTS