IDBAsynchNotify::OnProgress

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

HRESULT OnProgress (
   HCHAPTER   hChapter,
   ULONG      ulOperation,
   ULONG      ulProgress,
   ULONG      ulProgressMax,
   ULONG      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, this is DB_NULL_HCHAPTER.

ulOperation
[in]
The operation about which status is being returned. One of the following:

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

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 IDBAsynchStatus::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 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 initializedand the full range of interfaces are 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 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 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 consumer 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.

Consumers 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.