異步模型

Windows Web 服務 API 中的大部分作業都可以以同步或異步方式執行。 若要同步呼叫函式，請傳遞 WS_ASYNC_CONTEXT 結構的 Null 值。 若要指定函式可以異步執行，請將非 Null WS_ASYNC_CONTEXT 傳遞至函式。

以異步方式呼叫時，函式仍可以同步或異步完成。 如果函式以同步方式完成，它會傳回指出最終成功或錯誤的值，而此值一律不是 WS_S_ASYNC 以外的值（請參閱 Windows Web Services 傳回值）。 不過，WS_S_ASYNC的傳回值表示函式會以異步方式完成。 當函式以異步方式完成時，會叫用回呼以發出作業完成的訊號。 此回呼表示最終成功或錯誤值。 如果作業以同步方式完成，則不會呼叫回呼。

若要建立異步內容，請初始化 回呼 和 callbackSt ate WS_ASYNC_CONTEXT 結構的字段。 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_CONTEXT

WS_CALLBACK_MODEL

WsAsyncExecute