4.1 WFSCancelAsyncRequest

HRESULT WFSCancelAsyncRequest( hService, RequestID )

Cancels the specified (or every) asynchronous request being performed on the specified service, before its (their) completion.

Parameters HSERVICE hService

Handle to the service as returned by WFSOpen or WFSAsyncOpen.

REQUESTID RequestID

The request identifier for the request to be canceled, as returned by the original function call (NULL to cancel all).

Mode Immediate

Comments If the RequestID parameter is set to NULL, the command will cancel all asynchronous requests that are in progress using the specified hService.

A previously initiated asynchronous request is canceled prior to completion by issuing the WFSCancelAsyncRequest function, specifying the request identifier returned by the asynchronous function. This function is immediate with respect to its calling application, but the cancellation process is inherently asynchronous. On completion, the specified request (or all requests) will have finished, with a completion message indicating a status of WFS_ERR_CANCELED, unless the cancel request was received by the service after the request had completed. Thus, WFSCancelAsyncRequest is not guaranteed to stop all asynchronous commands: normal completion messages may still be posted after the cancel. A robust application that uses asynchronous commands should be designed to accept these messages even after a cancel is issued.

The cancellation applies not only to the XFS Manager level, but also to the service provider level. The request is passed through the SPI, and the service provider normally then also cancels any physical I/O or other device operation in progress, in the appropriate manner for the device or service.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_CONNECTION_LOST

The connection to the service is lost.

WFS_ERR_INTERNAL_ERROR

An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.

WFS_ERR_INVALID_HSERVICE

The hService parameter is not a valid service handle.

WFS_ERR_INVALID_REQ_ID

The RequestID parameter does not correspond to an outstanding request on the service.

WFS_ERR_NOT_STARTED

The application has not previously performed a successful WFSStartUp.

WFS_ERR_OP_IN_PROGRESS

A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

See also WFSAsyncExecute