RpcAsyncCancelCall

The client calls the RpcAsyncCancelCall function to cancel an asynchronous call.

#include <rpc.h>
RPC_STATUS RPC_ENTRY RpcAsyncCancelCall(
    PRPC_ASYNC_STATE  pAsync
    BOOL  fAbortCall
   );

Parameters

pAsync
Pointer to the RPC_ASYNC_STATE structure that contains asynchronous call information.
fAbortCall
If TRUE, the call is canceled immediately. If FALSE, wait for the server to complete the call.

Return Values

Value Meaning
RPC_S_OK Cancel request was processed.
RPC_S_INVALID_ASYNC_HANDLE The asynchronous handle is invalid.

Remarks

There are two ways for a client to request cancellation of an asynchronous call—abortive and nonabortive. In an abortive cancel (fAbortCall is TRUE), the run-time environment sends a cancel notification to the server and client side of the asynchronous call is canceled immediately, without waiting for a response from the server.

The server checks for cancel requests from the client by calling RpcServerTestCancel. Depending on the state of the call at the time the cancel request was issued and how often the server checks for cancels, the call may or may not complete normally. The client application can call RpcAsyncCompleteCall and the return value will indicate whether the call completed, failed, or was canceled.

In a nonabortive cancel (fAbortCall is FALSE) the run-time environment notifies the server of the cancel and the client waits for the server to complete the call. There is no built-in timeout mechanism. If you want the call to time out, the client should first issue a nonabortive cancel using its own timeout mechanism. If the call times out, then the client can issue an abortive cancel.

See Also

Asynchronous RPC, RPC_ASYNC_STATE, RpcAsyncAbortCall, RpcAsyncCompleteCall, RpcAsyncGetCallHandle, RpcAsyncGetCallStatus, RpcAsyncInitializeHandle, RpcAsyncRegisterInfo, RpcServerTestCancel