LPWPUQUEUEAPC

WPUQueueApc 関数は、オーバーラップ I/O の完了ルーチンを呼び出せるようにするため、指定されたスレッドにユーザーモードの非同期プロシージャ呼び出し (APC) をキューイングします。

エラーが発生しない場合、 WPUQueueApc は 0 を返し、指定されたスレッドに対して完了ルーチンをキューイングします。それ以外の場合は SOCKET_ERROR を返し、具体的なエラーコードは lpErrno で取得できます。

この関数は、指定されたスレッドに対して APC 関数をキューイングします。Windows では、これはユーザーモードの非同期プロシージャ呼び出し (APC) を使用して行われます。APC は、指定されたスレッドがアラート可能な待機状態でブロックされているときにのみ実行され、コールバックが直接行われます。この呼び出しは割り込みコンテキスト内でも安全に使用できます。

LPWSAUSERAPC は次のように定義されています。

typedef void ( CALLBACK FAR * LPWSAUSERAPC )( DWORD dwContext );

APC の仕組みは単一のコンテキスト値しかサポートしないため、lpfnUserApc 自体を、より多くのパラメーターを伴うクライアント指定の完了ルーチンにすることはできません。サービスプロバイダーは代わりに、自身の APC 関数へのポインターを渡す必要があります。その APC 関数は、渡された dwContext の値を使ってオーバーラップ操作の結果情報にアクセスし、クライアント指定の完了ルーチンを呼び出します。

ユーザーモードのコンポーネントがオーバーラップ I/O を実装しているサービスプロバイダーでは、APC の仕組みの典型的な使い方は次のとおりです。

- I/O 操作が完了すると、プロバイダーは小さなバッファーを確保し、クライアントが指定した完了プロシージャへのポインターと、そのプロシージャに渡すパラメーター値を詰め込みます。 - そのバッファーへのポインターを dwContext の値として、自身の中間プロシージャを対象プロシージャ lpfnUserApc として指定し、APC をキューイングします。 - 対象のスレッドが最終的にアラート可能な待機状態に入ると、サービスプロバイダーの中間プロシージャが適切なスレッドコンテキストで呼び出されます。 - 中間プロシージャは、パラメーターを取り出してバッファーを解放し、クライアントが指定した完了プロシージャを呼び出すだけです。