通过

异步模型

  • 项目

Windows Web 服务 API 中的大多数操作都可以同步或异步执行。 若要同步调用函数，请为 WS_ASYNC_CONTEXT 结构传递 null 值。 若要指定可以异步执行函数，请将非 null WS_ASYNC_CONTEXT 传递给该函数。

以异步方式调用时，函数仍可以同步或异步完成。 如果函数同步完成，它将返回一个指示最终成功或错误的值，并且此值始终不是 WS_S_ASYNC (请参阅 Windows Web Services 返回值) 。 但是，返回值 WS_S_ASYNC 指示函数将以异步方式完成。 当函数异步完成时，将调用回调以指示操作完成。 此回调指示最终成功或错误值。 如果操作同步完成，则不会调用回调。

若要创建异步上下文，请初始化WS_ASYNC_CONTEXT结构的 callback和 callbackState 字段。 callbackState 字段用于指定指向传递给 WS_ASYNC_CALLBACK 函数的用户定义数据的指针。

以下示例演示如何通过传递指向包含回调的 WS_ASYNC_CONTEXT 结构的指针和指向状态数据的指针来异步调用函数。

HRESULT ExampleAsyncFunction(WS_ASYNC_CONTEXT* asyncContext);
void ExampleAsyncFunction()
{
    // Set up the WS_ASYNC_CONTEXT structure.
    MyState* myState = ...;  \\ Declare a pointer to user-defined data.
    WS_ASYNC_CONTEXT asyncContext;
    asyncContext.callback = MyCallback;  \\ Set the callback.
    asyncContext.callbackState = myState; \\ Set the pointer to the user-defined data.

    // Start the asynchronous operation
    HRESULT hr = SomeFunction(&asyncContext);

    if (hr == WS_S_ASYNC)
    {
        // The operation is completing asynchronously.  The callback is called 
        // when the operation is complete.
    }
    else
    {
        // The operation completed synchronously.  The callback is not called.
    }
}
void CALLBACK MyCallback(HRESULT hr, WS_CALLBACK_MODEL callbackModel, void* callbackState)
{
    MyState* myState = (MyState*)callbackState;

    // The operation completed asynchronously.
}

异步函数仅在函数调用期间使用 WS_ASYNC_CONTEXT 结构， (在异步操作) 期间使用，因此可以在堆栈上安全地声明它。

如果除 WS_ASYNC_CONTEXT 结构之外的任何其他参数作为指针传递给异步函数，并且该函数以异步方式完成，则调用方有责任使这些参数指向的值保持活动状态， (在调用异步回调之前不释放) 。

回调可以执行的操作存在限制。 有关可能的操作 的详细信息，请参阅 WS_CALLBACK_MODEL。

实现异步函数时，请勿在异步函数返回到调用方之前在调用异步函数的同一线程上调用回调，因为这会中断异步模型。

实现需要执行一系列异步操作的函数时，请考虑使用 WsAsyncExecute 帮助程序函数。

异步函数示例演示如何实现和使用遵循异步模型的函数。

启动异步 IO 操作会消耗系统资源。 如果启动足够的 IO 操作，系统可能会变得无响应。 为防止这种情况，应用程序需要限制其启动的异步操作数。

异步模型使用以下 API 元素。

回调 描述
WS_ASYNC_CALLBACK 与异步模型一起使用的回调函数参数。
WS_ASYNC_FUNCTION 与 WsAsyncExecute 一起使用，以指定要在一系列异步操作中调用的下一个函数。

 

枚举 描述
WS_CALLBACK_MODEL 指定回调 (的线程行为，例如 ，WS_ASYNC_CALLBACK) 。

 

函数 说明
WsAsyncExecute 调用用户定义的回调，该回调可以启动异步操作，并指示在异步操作完成时应调用的函数。

 

结构 说明
WS_ASYNC_CONTEXT 指定异步回调和指向用户定义数据的指针，该数据将传递给异步回调。
WS_ASYNC_OPERATION 与 WsAsyncExecute 一起使用，以指定要在一系列异步操作中调用的下一个函数。
WS_ASYNC_STATE 由 WsAsyncExecute 用于管理异步操作的状态。

 

异步函数示例

WS_ASYNC_CALLBACK

WS_ASYNC_CONTEXT

WS_CALLBACK_MODEL

WsAsyncExecute