RpcAsyncInitializeHandle function (rpcasync.h)

Article
02/22/2024

The client calls the RpcAsyncInitializeHandle function to initialize the RPC_ASYNC_STATE structure to be used to make an asynchronous call.

Syntax

RPC_STATUS RpcAsyncInitializeHandle(
  PRPC_ASYNC_STATE pAsync,
  unsigned int     Size
);

Parameters

pAsync

Pointer to the RPC_ASYNC_STATE structure that contains asynchronous call information.

Size

Size of the RPC_ASYNC_STATE structure.

Return value

Value	Meaning
RPC_S_OK	The call succeeded.
RPC_S_INVALID_ARG	The size is either too small or too large.
RPC_S_INVALID_ASYNC_HANDLE	pAsync points to invalid memory.

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

Remarks

The client creates a new RPC_ASYNC_STATE structure and a pointer to that structure and calls RpcAsyncInitializeHandle with the pointer as an input parameter. The RpcAsyncInitializeHandle function initializes the fields that it uses to maintain the state of an asynchronous remote call. When the call to RpcAsyncInitializeHandle returns successfully, the client can set the notification type and any fields related to that notification type in the RPC_ASYNC_STATE structure. The client application uses a pointer to this structure to make an asynchronous call.

The client should not attempt to alter the Size, Signature, Lock, and StubInfo members of the RPC_ASYNC_STATE structure; doing so will invalidate the handle.

Note In Windows 2000, after an asynchronous call is completed, the RPC_ASYNC_STATE structure must be reinitialized prior to being used for another asynchronous call. In Windows XP and later, the RPC_ASYNC_STATE structure is ready for immediate re-use subsequent to a completed asynchronous call.

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