Export (0) Print
Expand All
Expand Minimize

RpcAsyncCancelCall function

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

Syntax


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 value

ValueMeaning
RPC_S_OK

The cancellation request was processed.

RPC_S_INVALID_ASYNC_HANDLE

The asynchronous handle is invalid.

 

Note  For a list of valid error codes, see RPC Return Values.

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

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Rpcasync.h (include Rpc.h)

Library

Rpcrt4.lib

DLL

Rpcrt4.dll

See also

Asynchronous RPC
RPC_ASYNC_STATE
RpcAsyncAbortCall
RpcAsyncCompleteCall
RpcAsyncGetCallHandle
RpcAsyncGetCallStatus
RpcAsyncInitializeHandle
RpcServerTestCancel

 

 

Community Additions

ADD
Show:
© 2014 Microsoft