Uses the moniker to bind to the object it identifies. The binding process involves finding the object, putting it into the running state if necessary, and supplying the caller with a pointer to a specified interface on the identified object.
HRESULT BindToObject(
IBindCtx *pbc, //Pointer to bind context object to be used
IMoniker *pmkToLeft, //Pointer to moniker that precedes this one
//in the composite
REFIID riidResult, //IID of interface pointer requested
void **ppvResult //Address of output variable that receives
//the interface pointer requested in riidResult
);
The method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY, as well as the following:
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.
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:
The following code fragment illustrates 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 don't 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 IOleObject::DoVerb, using the link handler's implementation, which calls IMoniker::BindToObject on the moniker stored in the linked object (if it cannot handle the verb).
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 IBindCtx::GetRunningObjectTable 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 IUnknown::QueryInterface to get a pointer to the interface requested by the caller.
When your IMoniker::BindToObject implementation binds to some object, it should use the pbc parameter to call IBindCtx::RegisterObjectBound to store a reference to the bound object in the bind context. This ensures that the bound object remains running until the bind context is released, which can avoid the expense of having a subsequent binding operation load it again later.
If the bind context's BIND_OPTS structure specifies the BINDFLAGS_JUSTTESTEXISTENCE flag, your implementation has the option of returning NULL in ppvResult (although you can also ignore the flag and perform the complete binding operation).
Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in objidl.h.
BindMoniker, IMoniker::BindToStorage