IDBAsynchNotify::OnProgress

OLE DB Programmer's Reference

Returns the progress of an asynchronous method call. This method makes no logical change to the state of the object.

HRESULT OnProgress (    HCHAPTER      hChapter,    DBASYNCHOP    ulOperation,    DBCOUNTITEM   ulProgress,    DBCOUNTITEM   ulProgressMax,    DBASYNCHPHASE ulAsynchPhase,    LPOLESTR      pwszStatusText);

Parameters

hChapter

[in]
The chapter handle. If the object calling this method is not a rowset or the operation does not apply to chapters, the caller must set hChapter to DB_NULL_HCHAPTER.

ulOperation

[in]
The operation about which status is being returned. Must be set to the following value:

DBASYNCHOP_OPEN—The information applies to the asynchronous opening or population of a rowset or the asynchronous initialization of a data source object.

ulProgress

[in]
Current progress of the asynchronous execution relative to the expected maximum indicated in the ulProgressMax parameter.

ulProgressMax

[in]
The expected maximum value of the ulProgress parameter for the duration of calls to IDBAsynchNotify::OnProgress for this phase. This value may change across calls to this method.

ulAsynchPhase

[in]
Additional information regarding the progress of the asynchronous operation. Valid values include:

DBASYNCHPHASE_CANCELED—A consumer has requested that the operation be canceled by calling IDBAsynchStatus::Abort. The listener can attempt to deny the cancellation by returning S_FALSE from the notification. If no listeners deny the cancellation, the provider will call IDBAsynchNotify::OnStop for all registered listeners with an hrStatus of DB_E_CANCELED.

DBASYNCHPHASE_INITIALIZATION—The object is in an initialization phase. The arguments ulProgress and ulProgressMax indicate an estimated ratio of completion. The object is not yet fully materialized. Attempting to call any other interfaces may fail, and the full set of interfaces may not be available on the object.

If the asynchronous operation is a result of calling ICommand::Execute for a command that updates, deletes, or inserts rows, and if cParamSets is greater than 1, ulProgress and ulProgressMax may indicate the progress for a single set of parameters or for the full array of parameter sets.

DBASYNCHPHASE_POPULATION—The object is in a population phase. Although the rowset is fully initialized and the full range of interfaces is available on the object, there may be additional rows not yet populated into the rowset.

While ulProgress and ulProgressMax can be based on the number of rows populated, they are generally based on the time or effort required to populate the rowset. A caller would therefore be better off using this information as a rough guide to how long the process might take, not the eventual row count.

This phase is returned only during population of a rowset. It is never returned in the initialization of a data source object or by the execution of a command that updates, deletes, or inserts rows.

DBASYNCHPHASE_COMPLETE—All asynchronous processing of the object has completed. If the asynchronous operation was a result of calling ICommand::Execute for a command that updates, deletes, or inserts rows, ulProgress and ulProgressMax are equal to the total number of rows affected by the command. If cParamSets is greater than 1, this is the total number of rows affected by all of the sets of parameters specified in the execution.

pwszStatusText

[in]
Textual information indicating additional information about the asynchronous operation, or NULL if no status text is available.

The provider owns the memory for pwszStatusText. The consumer can copy the text to its own memory but must not attempt to free pwszStatusText nor to reference it once it has returned from IDBAsynchNotify::OnProgress.

Return Code

S_OK: The method succeeded.
S_FALSE: The ulAsynchPhase was DBASYNCHPHASE_CANCELED, and the cancellation of the asynchronous operation was vetoed by the consumer.
The listener wants to cancel the asynchronous operation. The provider calls each listener's IDBAsynchNotify::OnProgress with a ulAsynchPhase of DBASYNCHPHASE_CANCELED. If none of the listeners deny the cancellation by returning S_FALSE to that notification, the asynchronous operation is canceled and IDBAsynchNotify::OnStop is called for each listener with an hrStatus of DB_E_CANCELED.
DB_S_UNWANTEDPHASE: The consumer is not interested in receiving this phase. The provider can optimize by making no further calls with this phase.
DB_S_UNWANTEDOPERATION: The consumer is not interested in receiving notifications for this operation. The provider can optimize by making no further calls to this method with this operation for this listener. Notifications for other operations are unaffected.
E_NOTIMPL: The consumer is not interested in receiving this notification. The provider can optimize by making no further calls to this method for this listener. Notifications for other methods are unaffected.
E_FAIL: A consumer-specific error occurred.

Comments

The provider calls this method repeatedly to indicate the current progress of the asynchronous operation, typically at reasonable intervals during a lengthy operation.

The listener can use the progress notification to provide progress information to the end user from the ulProgress, ulProgressMax, and pwszStatusText parameters, or to make programmatic decisions based on the ulAsynchPhase parameter.

Listeners should be prepared to handle unknown values of ulOperation by returning S_OK or DB_S_UNWANTEDOPERATION, and unknown values of ulAsynchPhase by returning S_OK or DB_S_UNWANTEDPHASE.

All listeners are always notified of the DBASYNCHPHASE_COMPLETE phase when all asynchronous processing has completed. If a listener registers for asynchronous notifications on a rowset after all processing has already completed, that listener's IDBAsynchNotify::OnProgress callback is immediately called with the DBASYNCHPHASE_COMPLETE phase. Listeners might or might not receive other phases.

The DBASYNCHPHASE_CANCELED phase is always passed to all listeners when asynchronous processing has been canceled. If a listener registers for asynchronous notifications on a rowset after processing has been canceled, that listener's IDBAsynchNotify::OnProgress callback is immediately called with the DBASYNCHPHASE_CANCELED phase. Listeners might or might not receive other phases.

See Also