WsAsyncExecute function (webservices.h)

Helper function for implementing an asynchronous operation.

Syntax

HRESULT WsAsyncExecute(
  [in]           WS_ASYNC_STATE         *asyncState,
  [in, optional] WS_ASYNC_FUNCTION      operation,
  [in]           WS_CALLBACK_MODEL      callbackModel,
  [in]           void                   *callbackState,
  [in, optional] const WS_ASYNC_CONTEXT *asyncContext,
  [in, optional] WS_ERROR               *error
);

Parameters

[in] asyncState

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.

[in, optional] operation

Represents the initial asynchronous operation to be performed.

[in] callbackModel

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

[in] callbackState

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

[in, optional] asyncContext

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

[in, optional] error

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.

Remarks

For an understanding 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.

Requirements