RpcAsyncCancelCall function (rpcasync.h)
The client calls the RpcAsyncCancelCall function to cancel an asynchronous call.
Syntax
RPC_STATUS RpcAsyncCancelCall(
PRPC_ASYNC_STATE pAsync,
BOOL fAbort
);
Parameters
pAsync
Pointer to the RPC_ASYNC_STATE structure that contains asynchronous call information.
fAbort
If TRUE, the call is canceled immediately. If FALSE, wait for the server to complete the call.
Return value
| Value | Meaning |
|---|---|
|
The cancellation request was processed. |
|
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 RpcAsyncCancelCall function sends a cancel notification to the server and client side and the asynchronous call is canceled immediately, without waiting for a response from the server. Note that in a multithreaded application, an async call can only be canceled by the client after the thread that originated the call has returned from it with success. This is necessary to ensure that the call will not be canceled asynchronously by another thread after it has failed synchronously while being issued. In general, if an async call fails synchronously it should not be canceled asynchronously. The client application must ensure this behavior if calls may be issued and canceled on different threads.
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 must call RpcAsyncCompleteCall to complete the call and the return value will indicate whether the call completed, failed, or was canceled. However, the client must still wait for the original call to complete before calling RpcAsyncCompleteCall.
In a nonabortive cancel (fAbortCall is FALSE) the RpcAsyncCancelCall function notifies the server of the cancel and the client waits for the server to complete the call. There is no built-in time-out mechanism. If you want the call to time out, the client should first issue a nonabortive cancel using its own time-out mechanism. If the call times out, then the client can issue an abortive cancel.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps | UWP apps] |
| Minimum supported server | Windows 2000 Server [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | rpcasync.h (include Rpc.h) |
| Library | Rpcrt4.lib |
| DLL | Rpcrt4.dll |