IDBAsynchStatus::Abort

  • Article

Cancels an asynchronously executing operation.

Syntax

HRESULT Abort(
   HCHAPTER   hChapter,
   ULONG      ulOperation);

Parameters

  • hChapter
    [in] The handle of the chapter for which to abort the operation. If the object being called is not a rowset object or the operation does not apply to a chapter, the caller must set hChapter to DB_NULL_HCHAPTER.

  • ulOperation
    [in] The operation to abort. This should be the following value:

    DBASYNCHOP_OPEN ? The request to cancel applies to the asynchronous opening or population of a rowset or to the asynchronous initialization of a data source object.

Return Code

  • S_OK
    The request to cancel the asynchronous operation was processed. This does not guarantee that the operation itself was canceled. To determine whether the operation was canceled, the consumer should call IDBAsynchStatus::GetStatus and check for DB_E_CANCELED; however, it might not be returned in the very next call.

  • DB_E_CANTCANCEL
    The asynchronous operation cannot be canceled.

  • DB_E_CANCELED
    The request to abort the asynchronous operation was canceled during notifications. The operation is still being executed asynchronously.

  • E_FAIL
    A provider-specific error occurred.

  • E_UNEXPECTED
    IDBAsynchStatus::Abort was called on a data source object on which IDBInitialize::Initialize has not been called.

    IDBAsynchStatus::Abort was called on a data source object on which IDBInitialize::Initialize was called but subsequently canceled prior to initialization. The data source object is still uninitialized.

    IDBAsynchStatus::Abort was called on a rowset on which ITransaction::Commit or ITransaction::Abort was previously called, and the rowset did not survive the commit or abort and is in a zombie state.

    IDBAsynchStatus::Abort was called on a rowset that was asynchronously canceled in its initialization phase. The rowset is in a zombie state.

Comments

After receiving a request to cancel, if the provider supports cancellation of the operation, it calls IDBAsynchNotify::OnProgress with a ulAsynchPhase of DBASYNCHPHASE_CANCELED for all listeners. If no listeners attempt to deny the cancellation by returning S_FALSE, the operation is canceled and the provider calls IDBAsynchNotify::OnStop for all listeners with an hrStatus of DB_E_CANCELED. If any listeners deny the cancellation of the operation by returning S_FALSE from the IDBAsynchNotify::OnProgress notification, the provider returns DB_E_CANCELED from the IDBAsynchStatus::Abort function and continues processing the operation.

Aborting the initialization of a rowset or data source object might leave the rowset or data source object in a zombie state, such that all methods other than IUnknown methods return E_UNEXPECTED. When this happens, the only possible action for the consumer is to release the rowset or data source object.

Calling IDBAsynchStatus::Abort and passing a value for ulOperation other than DBASYNCHOP_OPEN returns S_OK. This does not imply that the operation completed or was canceled.

Note

Consumers should avoid requesting more than one asynchronous scoped operation (IScopedOperations::Copy, Delete, or Move) at a time, because there is no way for the methods of IDBAsynchStatus or IDBAsynchNotify to request or provide information per operation. If multiple asynchronous scoped operations are underway, it is undefined and provider-specific which operation is reported by IDBAsynchStatus::GetStatus or IDBAsynchNotify::Notify or is affected by a call to IDBAsynchStatus::Abort.

If multiple IScopedOperations operations are invoked asynchronously on the same row instance, the behavior of IDBAsynchStatus and IDBAsynchNotify is undefined. (For more information on asynchronous operations, see Asynchronous Scoped Operations in Asynchronous Processing.

See Also

Reference

IDBAsynchNotify::OnStop