IDBAsynchNotify::OnStop

OnStop is called by the provider to indicate that asynchronous processing has stopped.

HRESULT OnStop (
   HCHAPTER   hChapter,
   ULONG      ulOperation,
   HRESULT      hrStatus,
   LPOLESTR   pwszStatusText);

Parameters

hChapter
[in]

The chapter for which the operation has stopped. 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 that has stopped. One of the following:

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

hrStatus

[in]
Status code indicating the completion result of the asynchronous operation. This may be one of the following status codes, or some result specific to the asynchronous operation being executed:

S_OK
The asynchronous operation completed successfully.

DB_E_CANCELED
The asynchronous operation was canceled.

E_OUTOFMEMORY
The provider ran out of memory attempting to execute the asynchronous operation.

E_FAIL
The asynchronous operation failed for a provider-specific reason.

pwszStatusText

[in]
Additional information about the error, or the resource associated with the error. If no additional information is available, this string is empty.

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::OnStop.

Return Code

S_OK
The method succeeded.

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

This method is called once per operation, when all asynchronous phases for that operation have completed. OnStop is always called, whether the asynchronous operation succeeded, failed, or was aborted by the consumer.

For operations that complete successfully, OnProgress is always called prior to OnStop with ulProgress equal to ulProgressMax. The only exception is if the listener has explicitly requested not to receive further OnProgress notifications by returning E_NOTIMPL or DB_S_UNWANTEDOPERATION, and the provider has optimized by not making additional calls to OnProgress.

Consumers should be prepared to handle new values of ulOperation by returning S_OK or DB_S_UNWANTEDOPERATION.