Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This 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 the IMonikerinterface and in certain functions related to monikers.

A bind context includes the following information:

  • A BIND_OPTSstructure 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, so it acts as 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::GetRunningObjectTablemethod rather than using the GetRunningObjectTablefunction. This allows future enhancements to the system's IBindCtximplementation 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 ("ExceededDeadline", "ConnectManually", and so on) 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 IBindCtximplementation, accessible though a call to the CreateBindCtxfunction, that is suitable for all situations.

When to Use

Anyone writing a new moniker class by implementing the IMonikerinterface must call IBindCtxmethods in the implementation of several IMonikermethods.

Moniker providers (servers that hand out monikers to identify their objects) may also need to call IBindCtxmethods from their implementations of the IOleItemContaineror IParseDisplayNameinterface.

Moniker clients (objects that use monikers to acquire interface pointers to other objects) typically do not call many IBindCtxmethods. Instead, they simply pass a bind context as a parameter in a call to an IMonikermethod.

To acquire an interface pointer and activate the indicated object (called binding to an object), moniker clients typically do the following:

  1. Call the CreateBindCtxfunction to create a bind context and get a pointer to the IBindCtxinterface on the bind context object.

  2. If desired, although this is rarely necessary, the moniker client can call the IBindCtx::SetBindOptionsmethod to specify the bind options.

  3. Pass the bind context as a parameter to the desired IMonikermethod (usually IMoniker::BindToObject).

  4. Call the IUnknown::Releasemethod on the bind context to release it.

Although applications that act as link containers (container applications that allow their documents to contain linked objects) are moniker clients, they rarely call IMonikermethods directly.

Generally, they manipulate linked objects through the system implementation (in the default handler) of the IOleLinkinterface. This implementation calls the appropriate IMonikermethods as needed and, in doing so, passes pointers to IBindCtxinterfaces on the proper bind context objects.

Methods

The following table shows the methods for this interface in the order that the compiler calls the methods. Like all COM interfaces, this interface inherits the methods for the IUnknowninterface.

IUnknown method Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments the reference count.

Release

Decrements the reference count.

IBindCtx method 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.

Remarks

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

Requirements

Header objidl.h, objidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also