IMoniker::BindToObject - OLE Programmer's Reference (ole.hlp)

IMoniker::BindToObject

"Binds" the moniker; that is, returns a pointer to the object identified by the moniker. The binding process involves finding the object, getting it into the running state if it's not already, and acquiring an interface pointer to it.

HRESULT BindToObject(

IBindCtx *pbc,	//Bind context to be used
IMoniker *pmkToLeft,	//Moniker that precedes this one in the composite
REFIID riidResult,	//IID of interface pointer requested
void **ppvResult	//Receives an interface pointer to the object
);

Parameters
pbc

[in] Points to the bind context to be used for 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. For more information, see IBindCtx.

pmkToLeft

[in] Points to the moniker to the left of this moniker, if this moniker is part of a composite. This parameter is primarily used by moniker implementors to enable cooperation between the various components of a composite moniker; moniker clients can usually pass NULL.

riidResult

[in] Specifies the IID of the interface pointer requested.

ppvResult

[out] Receives a pointer to the object identified by the moniker. If an error occurs, the implementation sets *ppvResult to NULL. If *ppvResult is non-NULL, the implementation must call IUnknown::AddRef on the parameter; it is the caller's responsibility to call IUnknown::Release.

Return Values
S_OK

The binding operation was successful.

MK_E_NOOBJECT

Indicates that the object identifed 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

Indicates that the binding operation could not be completed within the time limit specified by the bind context's BIND_OPTS structure.

MK_E_CONNECTMANUALLY

Indicates a moniker whose binding requires assistance from the end user. You can retry the binding operation after showing the moniker's display name to request that the end user manually connect to the object. The most common reasons for returning this value are that a password is needed or that a floppy needs to be mounted. The caller should call IBindCtx::GetObjectParam with the key "ConnectManually" to retrieve the moniker that caused the error, get the display name, display a dialog box asking the user for a password, and so on.

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 IOleItemContainer interface.

E_UNEXPECTED

Indicates an unexpected error.

E_OUTOFMEMORY

Indicates insufficient memory.

STG_E_ACCESSDENIED

Unable to access the storage object.

IOleItemContainer::GetObject errors

Binding to a moniker containing an item moniker can return any of the errors associated with this function.

Comments
The IMoniker::BindToObject method implements the primary function of a moniker: returning an interface pointer to the object identified by the moniker.

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

You typically call IMoniker::BindToObject with the following steps:

Create a bind context by calling the CreateBindCtx API function.
Call the IMoniker::BindToObject method on the moniker, retrieving an interface pointer.
Release the bind context.
Use the interface pointer.
Release the interface pointer.

Here's a code fragment that illustrates these steps:

// pMnk is an IMoniker * that points to a previously-acquired moniker

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 API function, which encapsulates the first three steps described above.

Note that link containers are a special case in that they typically don't need to call IMoniker::BindToObject directly. When a user activates a linked object, the link container can typically calls IOleObject::DoVerb. The link handler's implementation of IOleObject::DoVerb calls IMoniker::BindToObject on the moniker stored in the linked object (if it cannot handle the verb).

Notes to Implementors
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 use IUnknown::QueryInterface to return the desired interface pointer.

When your IMoniker::BindToObject implementation binds to some object, it should call IBindCtx::RegisterObjectBound on the pbc parameter 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).

See Also
BindMoniker, IMoniker::BindToStorage

More Online Helps

Win32 Programmer's Reference (win32.hlp)
Win32 Multimedia Programmer's Reference (mmedia.hlp)
Microsoft Windows Pen API Programmer's Reference (penapi.hlp)
Microsoft Windows Sockets 2 Reference (sock2.hlp)
Microsoft Windows Telephony API (TAPI) Programmer's Reference (sock2.hlp)
Unix Manual Pages

greatis just4fun network