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. Multiple clients can register callback interfaces for the same bind operation. Each client specifies the notifications it is interested in receiving in the grfBSCOption parameter.

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.