通过

异步模型

  • 项目

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

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

若要创建异步上下文，请初始化 WS_ASYNC_CONTEXT 结构的 回调 和 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 helper 函数。

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

启动异步 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