Windows apps
Collapse the table of content
Expand the table of content
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

WsAsyncExecute function

Helper function for implementing an asynchronous operation.


  _In_     WS_ASYNC_STATE*         asyncState,
  _In_opt_ WS_ASYNC_FUNCTION       operation,
  _In_     WS_CALLBACK_MODEL       callbackModel,
  _In_     void*                   callbackState,
  _In_opt_ const WS_ASYNC_CONTEXT* asyncContext,
  _In_opt_ WS_ERROR*               error


asyncState [in]

A pointer to the WS_ASYNC_STATE structure used during the asynchronous operation. This is a state maintenance parameter not intended for direct use. The application must allocate the WS_ASYNC_STATE structure and ensure that it is kept alive during the entire asynchronous operation. The WS_ASYNC_STATE structure can be reused after an asynchronous operation has completed.

operation [in, optional]

Represents the initial asynchronous operation to be performed.

callbackModel [in]

Indicates whether the callback is being invoked long or short. For more information, see WS_CALLBACK_MODEL

callbackState [in]

A void pointer to a user-defined value that is passed to each WS_ASYNC_FUNCTION.

asyncContext [in, optional]

Pointer to information for invoking the function asynchronously. Pass NULL to invoke the function synchronously.

error [in, optional]

Pointer to a WS_ERROR structure that receives additional error information if the function fails.

Return value

If the function succeeds, it returns NO_ERROR; otherwise, it returns an HRESULT error code.


For an understaning of how WWSAPI handles asynchronous operations, see the Asynchronous Model topic.

In many cases, an asynchronous operation is composed of other asynchronous operations. Each asynchronous operation may return WS_S_ASYNC indicating the callback will be invoked, or any other success or failure code, in which case the callback will not be invoked. The operation must be prepared to accept a NULL WS_ASYNC_CONTEXT indicating that the caller is requesting the operation to be performed synchronously. It must also ensure that the callback is invoked appropriately. In complex asynchronous operations, WsAsyncExecute simplifies these details.

WsAsyncExecute operates by invoking a user-defined callback which can initiate an asynchrnous operation and indicate a function to be invoked when the asynchronous operation is complete. This sequence continues until the callback does not set another function to invoke. At this point, the callback specified by the WS_ASYNC_CONTEXT will be invoked if any of the operations completed asynchronously.

The WS_ASYNC_STATE parameter is used by WsAsyncExecute to maintain its state, and is not intended to be initialized, inspected, or used by the caller. The caller however, must allocate the WS_ASYNC_STATE and ensure that it is kept alive during the entire asynchronous operation. The WS_ASYNC_STATE may be reused once the asynchronous operation is complete.

The examples AsyncAdd3ExplicitExample and AsyncAdd3ImplicitExample demonstrate implementing the same asynchronous function manually using WsAsyncExecute.


Minimum supported client

Windows 7 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2 [desktop apps | Windows Store apps]









Community Additions

© 2017 Microsoft