IBindStatusCallback

A client requesting an asynchronous bind operation must provide a notification object exposing the IBindStatusCallback interface. The asynchronous moniker provides information on the bind operation to the client by calling notification methods on the client's callback interface.

Besides providing notification methods, this interface also allows the client to pass additional bind information to the moniker. To obtain this additional bind information, the moniker calls two IBindStatusCallback methods (GetBindInfo and GetPriority) after receiving a call either to IMoniker::BindToObject or IMoniker::BindToStorage. IBindStatusCallback::QueryInterface provides extensibility to IBindStatusCallback because it allows the moniker to request additional interfaces from the client in case the bind operation requires additional information or negotiaion.

All methods in IBindStatusCallback can be called from within IMoniker::BindToObject or IMoniker::BindToStorage. These methods can also be called after the moniker returns if the bind information indicates asynchronous binding (BINDF_ASYNCHRONOUS).

Clients of asynchronous monikers register their callback interface in the bind context by calling the RegisterBindStatusCallback function.

During the bind operation, these callbacks are called in an arbitrary order, and the asynchronous moniker may set policy and limit certain callback notifications to only one of the registered callback interfaces. For example, the moniker may limit calls to the GetBindInfo, OnDataAvailable, or OnObjectAvailable methods to a single callback interface.

Note that, in the case of URL monikers, the policy is not documented and is likely to change. It is advised that only one registered callback interface (usually the last one registered) be responsible for the callbacks to the GetBindInfo, OnDataAvailable, and OnObjectAvailable methods.

When to Implement

Any client of an asynchronous moniker must implement this interface to obtain asynchronous behaviour. Typically, a client implements this interface on a separate object, similar to a site object, that it associates with a specific bind operation.

Note that most of the notification methods in this interface are optional. A client should implement only those notifications it is interested in receiving. The client can return E_UNIMP or S_OK for notification methods it does not wish to receive.

The methods in IBindStatusCallback do not identify the specific bind operation that the notification belongs to, so a client should provide a separate object instance for each simultaneous asynchronous bind operation it initiates.

When the client registers the interface in the bind context by calling RegisterBindStatusCallback, the bind context keeps a reference to the callback object. The moniker can optionally add references to this object.

When to Use

Implementations of asynchronous monikers will use this interface for two purposes:

Obtain additional bind information. Throughout the bind operation, the moniker can call the client to obtain additional binding information. For example, in the implementation of IMoniker::BindToStorage or IMoniker::BindToObject, the moniker calls IBindStatusCallback::GetBindInfo to check at least the BINDF_ASYNCHRONOUS flag. If this flag is not set, the bind operation cannot return until the object or storage object is available. As another example, the moniker can call IBindStatusCallback::GetPriority during its IMoniker::BindToStorage or IMoniker::BindToObject methods, or it can wait until a later point to get the priority of the bind operation. Also, the moniker can call IBindStatusCallback::QueryInterface to request a new interface from the client if the bind operation needs further information or additional services from the client.
Provide notifications. In the implementation of IMoniker::BindToStorage or IMoniker::BindToObject, the moniker can call any of the notification methods as well as the bind information methods. After returning from the call, the moniker can call notification methods to provide additional notification throughout the bind operation.

Methods in Vtable Order

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

IBindStatusCallback Methods	Description
GetBindInfo	Called by asynchronous moniker to get bind info
OnStartBinding	Tells the client which callback methods it is registered for receiving.
GetPriority	Gets data during asynchronous bind operations.
OnProgress	Indicates the current progress of this bind operation.
OnDataAvailable	Retrieves the current priority of this bind operation.
OnObjectAvailable	Called by asynchronous moniker to to pass the requested object interface pointer to the client.
OnLowResource	An asynchronous moniker calls this method when it detects low resources.
OnStopBinding	An asynchronous moniker calls this method to indicate the end of the bind operation.

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in urlmon.h.