This method binds to the object named by the moniker.

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

Parameters

pbc

[in] Pointer to the IBindCtxinterface 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 wishes to use to communicate with the object that the moniker identifies.

ppvResult

[out] Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, * ppvResultcontains the requested interface pointer to the object the moniker identifies. When successful, the implementation must call IUnknown::AddRefon the moniker. It is the caller's responsibility to release the object with a call to IUnknown::Release. If an error occurs, * ppvResultshould be NULL.

Return Values

The method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY, as well as the values described in the following table.

S_OK

The binding operation was successful.

MK_E_NOOBJECT

The object identified by this moniker, or some object identified by the composite moniker of which this moniker is a part, could not be found.

MK_E_EXCEEDEDDEADLINE

The binding operation could not be completed within the time limit specified by the bind context's BIND_OPTSstructure.

MK_E_CONNECTMANUALLY

The binding operation requires assistance from the end user. The most common reasons for returning this value are that a password is needed or that a floppy needs to be mounted. When this value is returned, retrieve the moniker that caused the error with a call to IBindCtx::GetObjectParamwith the key "ConnectManually". You can then call IMoniker::GetDisplayNameto get the display name, display a dialog box that communicates the desired information, such as instructions to mount a floppy or a request for a password, and then retry the binding operation.

MK_E_INTERMEDIATEINTERFACENOTSUPPORTED

An intermediate object was found but it did not support an interface required to complete the binding operation. For example, an item moniker returns this value if its container does not support the IOleItemContainerinterface.

STG_E_ACCESSDENIED

Unable to access the storage object.

IOleItemContainer::GetObjecterrors

If the moniker used to bind to an object contains an item moniker, errors associated with this method can be returned.

Remarks

IMoniker::BindToObjectimplements 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.

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::BindToObjectduring the following process:

1. Create a bind context object with a call to the CreateBindCtxfunction.
2. Call IMoniker::BindToObjectusing 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 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 BindMonikerfunction 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::BindToObjectdirectly. 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::BindToObjecton 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 pmkToLeftparameter to be NULL or not. For example, an item moniker, which identifies an object within a container, expects that pmkToLeftidentifies the container. An item moniker consequently uses pmkToLeftto request services from that container. If you expect your moniker to have a prefix, you should use the pmkToLeftparameter (for instance, calling IMoniker::BindToObjecton it) to request services from the object it identifies.

   If you expect your moniker to have no prefix, your IMoniker::BindToObjectimplementation 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::GetRunningObjectTableon the pbcparameter. You can then call the IRunningObjectTable::GetObjectmethod to see if the current moniker has been registered in the ROT. If so, you can immediately call IUnknown::QueryInterfaceto get a pointer to the interface requested by the caller.

   Requirements

   Runs On	Versions	Defined in	Include	Link to
   Windows CE OS	2.0 and later	Oaidl.h

   Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

   See Also

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

   
   

   ---

   Last updated on Friday, May 26, 2006

   © 2004 Microsoft Corporation. All rights reserved.