非同期モデル

Windows Web Services API のほとんどの操作は、同期的または非同期的に実行できます。 関数を同期的に呼び出すには、 WS_ASYNC_CONTEXT 構造体に null 値を渡します。 関数を非同期的に実行できるように指定するには、null 以外の WS_ASYNC_CONTEXT を関数に渡します。

非同期的に呼び出されると、関数は同期的にも非同期的にも完了できます。 関数が同期的に完了すると、最終的な成功またはエラーを示す値が返され、この値は常に WS_S_ASYNC 以外の値になります ( 「Windows Web サービスの戻り値」を参照してください)。 ただし、戻り値 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