IDBAsynchNotify::OnStop

OLE DB Programmer's Reference

Called by the provider to indicate that asynchronous processing has stopped.

HRESULT OnStop (    HCHAPTER   hChapter,    DBASYNCHOP 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, the caller must set hChapter to DB_NULL_HCHAPTER.

ulOperation

[in]
The operation that has stopped.

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

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 about 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 after 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, after all asynchronous phases for that operation have completed. IDBAsynchNotify::OnStop is always called, whether the asynchronous operation succeeded, failed, or was aborted by the consumer.

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

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

See Also