IBindCtx - OLE Programmer's Reference (ole.hlp)

IBindCtx

The IBindCtx interface provides access to a bind context, which is an object that stores information about a particular moniker binding operation. You pass a bind context as a parameter when calling many methods of IMoniker and in certain API functions related to monikers.

A bind context includes the following information:

A BIND_OPTS structure containing a set of parameters that do not change during the binding operation. When a composite moniker is bound, each component uses the same bind context; a bind context is thus a mechanism for passing the same parameters to each component of a composite moniker.
A set of pointers to objects that the binding operation has activated. The bind context holds pointers to these bound objects, keeping them loaded and thus eliminating redundant activations if the objects are needed again during subsequent binding operations.
A pointer to the Running Object Table on the machine of the process that started the bind operation. Moniker implementations that need to access the Running Object Table should use the IBindCtx::GetRunningObjectTable method rather than using the GetRunningObjectTable API function. This allows future enhancements to the system's IBindCtx implementation to modify binding behavior.
A table of interface pointers, each associated with a string key. This capability enables moniker implementations to store interface pointers under a well-known string so that they can later be retrieved from the bind context. For example, OLE defines several string keys (e.g., "ExceededDeadline", "ConnectManually") that can be used to store a pointer to the object that caused an error during a binding operation.

When to Implement
You do not need to implement this interface. The system provides an IBindCtx implementation, accessible using the CreateBindCtx API function, that is suitable for all situations.

When to Use
The primary users of IBindCtx are those who write their own implementation of the IMoniker interface; they must call IBindCtx methods from the implementation of several IMoniker methods. Another category of IBindCtx users are moniker providers (that is, those who hand out monikers that identify their objects). They may need to call IBindCtx methods from their implementations of the IOleItemContainer or IParseDisplayName interfaces.

Moniker clients (that is, those who use monikers to acquire interface pointers to objects) typically don't call many IBindCtx methods; they simply pass a bind context as a parameter to the IMoniker method they're using. Moniker clients typically perform the following steps:

Call the CreateBindCtx API function to create a bind context.
Optionally, call the IBindCtx::SetBindOptions method in order to specify the bind options. Moniker clients rarely perform this step.
Pass the bind context as a parameter to the desired IMoniker method (most commonly IMoniker::BindToObject).
Call IUnknown::Release on the bind context to release it.

The most common example of moniker clients are applications that act as link containers, that is, container applications that allow their documents to contain linked objects. However, link containers are a special case in that they rarely call IMoniker methods directly. Generally, they manipulate linked objects through the IOleLink interface; the system-supplied linked object implements this interface and calls the appropriate IMoniker methods as needed. Consequently, the linked object is the one that passes bind contexts to the IMoniker methods.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

IBindCtx Methods	Description
RegisterObjectBound	Registers an object with the bind context.
RevokeObjectBound	Revokes an object's registration.
ReleaseBoundObjects	Releases all registered objects.
SetBindOptions	Sets the binding options.
GetBindOptions	Retrieves the binding options.
GetRunningObjectTable	Retrieves a pointer to the Running Object Table.
RegisterObjectParam	Associates an object with a string key.
GetObjectParam	Returns the object associated with a given string key.
EnumObjectParam	Enumerates all the string keys in the table.
RevokeObjectParam	Revokes association between an object and a string key.

See Also
CreateBindCtx, IMoniker, IOleItemContainer, IParseDisplayName

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