# RegisterBindStatusCallback

Registers a callback interface with an existing bind context.

HRESULT RegisterBindStatusCallback(

IBindCtx *pbc, | //Pointer to the bind context in which to register the callback
IBindStatusCallback *pbsc, | //Pointer to callback interface to be registered
IBindStatusCallback **ppbscPrevious, | // Indirect pointer to previously registered BindStatusCallback
DWORD dwReserved | //Reserved for future use
); |

Parameters

pbc
  [in] Pointer to the IBindCtx interface for the bind context in which the callback is to be registered.
pbsc
  [in] Pointer to the IBindStatusCallback interface to be registered.
ppbscPrevious
  [out] Indirect pointer to previously registered instance of IBindStatusCallback.
dwReserved
  [in] Reserved for future use.

Return Values

S_OK
  The operation was successful.
E_OUTOFMEMORY
  There was insufficient memory to register the callback with the bind context.
E_INVALIDARG
  One or more parameters are invalid.

Remarks

The callback interface that is registered with this function is used for all asynchronous bind operations involving the specified bind context until the callback interface is revoked through RevokeBindStatusCallback or until the bind context is destroyed.

If there was a previously registered IBindStatusCallback, this function removes it from the bind context and registers the new IBindStatusCallback.

RegisterBindStatusCallback allows the client to specify flags that determine the callback notifications that the client is capable of receiving. If the client does not wish to receive certain notifications, it can implement those callback methods as empty function stubs (returning E_NOTIMPL), and they will not be called.

RegisterBindStatusCallback allows multiple clients to each register a callback for the same bind context. During the bind operation, these callbacks are called in an arbitrary order, and the asynchronous moniker can set a policy and limit certain callback notifications to only one of the registered callbacks. For example, the notifications GetBindInfo, OnDataAvailable, or OnObjectAvailable are usually limited to a single registered callback interface. For this reason, a client should request to receive only those callback methods that it plans on implementing.

Specifically, even though multiple IBindStatusCallback interfaces can be registered on the bind context, only one moniker client will actually receive the following notifications: GetBindInfo, OnDataAvailable, or OnObjectAvailable. This client is the last one to register itself as capable of receiving these callbacks, and it is typically the client that calls IMoniker::BindToStorage or IMoniker::BindToObject and drives the bind operation.

In the current implementation of URL monikers, the clients are called in reverse of the order in which they were registered, with the exception of the last client to request the following notifications: GetBindInfo, OnDataAvailable, or OnObjectAvailable. The last client in the callback order is notified for these exceptions. However, it is recommended that you not depend heavily on this ordering for the URL moniker implementation. The only important point is that the registered client for GetBindInfo or OnDataAvailable, or OnObjectAvailable is last in the ordering.

See Also

IBindStatusCallback, RevokeBindStatusCallback