Asynchronous URL Binding

OLE DB Programmer's Reference

Consumers wishing to poll for status, cancel an operation, or receive notifications of progress when requesting a bind by calling IBindResource::Bind or ICreateRow::CreateRow should set the DBBINDURLFLAG_WAITFORINIT flag. When this flag is set, Bind or CreateRow immediately returns an uninitialized object. The consumer may call IUnknown::QueryInterface on the uninitialized object for IDBAsynchStatus to poll for status or call QueryInterface for IConnectionPointContainer to register the consumer's IDBAsynchNotify interface as a notification sink. The consumer then calls IUnknown::QueryInterface for the IDBInitialize interface and calls IDBInitialize::Initialize to initiate the bind or create operation and initialize the object. All objects that can be bound using the DBBINDURLFLAG_WAITFORINIT flag should support the optional interfaces IDBInitialize, IConnectionPointContainer, and IDBAsynchStatus.

The returned object must be fully defined by the call to IBindResource::Bind or ICreateRow::CreateRow. All bind flags and properties required to define the object being returned must be specified at the time the call is made. Before calling IDBInitialize::Initialize, it is not possible to set properties or call other methods that affect initialization. The DBBINDURLFLAG_WAITFORINIT flag can be used only to set up notification and polling channels. The consumer is limited to registering an IDBAsynchNotify notification sink for initialization of notifications and obtaining an IDBAsynchStatus interface pointer to poll for status or cancel the operation.

Providers may not be able to uninitialize an object bound using DBBINDURLFLAG_WAITFORINIT and on IDBInitialize::Uninitialize may return E_UNEXPECTED.

Consumers wishing to bind asynchronously to a data source, rowset, row, or stream object must set the DBBINDURLFLAG_ASYNCHRONOUS bit of dwBindURLFlags prior to calling IBindResource::Bind or ICreateRow::CreateRow. (Note: Only Bind can bind to data source objects.) If this flag is set, the provider returns immediately from the call to Bind or CreateRow, returning S_OK if the operation has completed immediately, or DB_S_ASYNCHRONOUS if the operation will continue asynchronously. Consumers can call IDBAsynchStatus::GetStatus to get the status of the operation or can register for progress notifications by setting the DBBINDURLFLAG_WAITFORINIT flag and passing the consumer's IDBAsynchNotify interface to the requested object's connection point. The consumer must explicitly request an asynchronous operation. Otherwise, Bind or CreateRow does not return until the requested object is completely bound. The DBBINDURLFLAG_WAITFORINIT flag transfers the latency of the bind to the IDBInitialize::Initialize call.

1998-2001 Microsoft Corporation. All rights reserved.