OLE DB Programmer's Reference |
Returns the status of an asynchronously executing operation.
HRESULT GetStatus ( HCHAPTER hChapter, ULONG ulOperation, DBCOUNTITEM *pulProgress, DBCOUNTITEM *pulProgressMax, ULONG *pulAsynchPhase, LPOLESTR *ppwszStatusText);
Parameters
DBASYNCHOP_OPENThe consumer requests information about the asynchronous opening or population of a rowset or about the asynchronous initialization of a data source object. If the provider is an OLE DB 2.5-compliant provider that supports direct URL binding, the consumer requests information about the asynchronous initialization or population of a data source, rowset, row, or stream object.
If pulProgress is a null pointer, no progress is returned.
If pulProgressMax is a null pointer, no expected maximum value is returned.
DBASYNCHPHASE_INITIALIZATIONThe object is in an initialization phase. The arguments pulProgress and pulProgressMax 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 was a result of calling ICommand::Execute for a command that updates, deletes, or inserts rows and if cParamSets is greater than 1, pulProgress and pulProgressMax may indicate the progress for a single set of parameters or for the full array of parameter sets.
DBASYNCHPHASE_POPULATIONThe 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 pulProgress and pulProgressMax 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 should therefore use this information as a rough estimate of 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_COMPLETEAll asynchronous processing of the object has completed. IDBAsynchStatus::GetStatus returns an HRESULT indicating the outcome of the operation. Typically, this will be the HRESULT that would have been returned had the operation been called synchronously. If the asynchronous operation was a result of calling ICommand::Execute for a command that updates, deletes, or inserts rows, pulProgress and pulProgressMax 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. If pulAsynchPhase is a null pointer, no status code is returned.
DBASYNCHPHASE_CANCELEDAsynchronous processing of the object was aborted. IDBAsynchStatus::GetStatus returns DB_E_CANCELED. If the asynchronous operation was a result of calling ICommand::Execute for a command that updates, deletes, or inserts rows, pulProgress is equal to the total number of rows, for all parameter sets, affected by the command prior to cancellation.
If *ppwszStatusText is non-null on input, the provider returns status associated with the particular element identified by *ppwszStatusText. If *ppwszStatusText does not indicate an element of ulOperation, the provider returns S_OK with pulProgress and pulProgressMax set to the same value. If the provider does not distinguish between elements based on a textual identifier, it sets *ppwszStatusText to NULL and returns information about the operation as a whole; otherwise, if *ppwszStatusText is non-null on input, the provider leaves *ppwszStatusText untouched.
If *ppwszStatusText is null on input, the provider sets *ppwszStatusText to a value indicating more information about the operation, or NULL if no such information is available or if IDBAsynchStatus::GetStatus returns an error. When *ppwszStatusText is null on input, the provider allocates memory for the status string and returns the address to this memory. The consumer releases this memory with IMalloc::Free when it no longer needs the string.
If ppwszStatusText is NULL on input, no status string is returned and the provider returns information about any element of the operation or about the operation in general.
Return Code
Asynchronous processing was canceled during data source object initialization. The data source object is in an uninitialized state.
IDBAsynchStatus::GetStatus was called on a rowset, ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.
IDBAsynchStatus::GetStatus was called on a rowset that was asynchronously canceled in its initialization phase. The rowset is in a zombie state.
Comments
If the rowset is initialized or populated asynchronously, it must support this method.
In addition to the return values listed, IDBAsynchStatus::GetStatus can return any HRESULT that would have been returned by the method that initiated the asynchronous operation, indicating the success or failure of the operation.
Some asynchronous operations might not be able to return any states other than "finished" and "not finished". They should set pulProgressMax to a value of 1, indicating the all-or-nothing granularity of their estimate, so their answers would be either 0/1 or 1/1.
A provider may change pulProgressMax in successive calls and even return a smaller ratio than previously, if this reflects an improving estimate of the degree of completion of the task.
The provider is not obliged to guarantee any further accuracy but is encouraged to do so in cases where reasonable estimates of completion are possible. Such efforts will improve user-interface quality because the main use of this function is likely to be to give progress feedback to the user. User satisfaction increases with the quality of feedback on an invisible, long-running task.
Calling IDBAsynchStatus::GetStatus on an initialized data source object or a populated rowset, or passing a value for ulOperation other than DBASYNCHOP_OPEN, returns S_OK with pulProgress and pulProgressMax set to the same value. If IDBAsynchStatus::GetStatus is called on an object created from the execution of a command that updates, deletes, or inserts rows, both pulProgress and pulProgressMax indicate the total number of rows affected by the command.
IDBAsynchNotify::OnProgress
1998-2001 Microsoft Corporation. All rights reserved.