共用方式為

非同步模型

  • 發行項

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

以非同步方式呼叫時，函式仍可同步或非同步地完成。 如果函式以同步方式完成，它會傳回指出最終成功或錯誤的值，而且此值一律不是 WS_S_ASYNC (請參閱 Windows Web 服務傳回值) 。 不過，傳回值 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 協助程式函式。

非同步函式範例示範如何實作和使用遵循非同步模型的函式。

啟動非同步 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