PFN_WSK_RECEIVE_EVENT コールバック関数 (wsk.h)

[アーティクル]
08/08/2023

WskReceiveEvent イベントコールバック関数は、接続指向ソケットでデータが受信されたことを WSK アプリケーションに通知します。

構文

PFN_WSK_RECEIVE_EVENT PfnWskReceiveEvent;

NTSTATUS PfnWskReceiveEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATA_INDICATION DataIndication,
  [in]           SIZE_T BytesIndicated,
  [in, out]      SIZE_T *BytesAccepted
)
{...}

パラメーター

[in, optional] SocketContext

データを受信した接続指向ソケットのソケットコンテキストへのポインター。 WSK アプリケーションは、次のいずれかの方法で WSK サブシステムへのこのポインターを提供しました。

ソケットを作成するために WskSocket 関数を呼び出しました。
ソケットを作成するために WskSocketConnect 関数を呼び出しました。
ソケットを受信接続として受け入れるために、WskAccept 関数を呼び出しました。
その WskAcceptEvent イベントコールバック関数は、ソケットを受信接続として受け入れるために呼び出されました。

[in] Flags

次のフラグの組み合わせのビットごとの OR を含む ULONG 値。

値	意味
WSK_FLAG_RELEASE_ASAP	受信したデータを含むデータバッファーは、可能であれば WSK アプリケーションで保持しないでください。 WSK アプリケーションでバッファーが保持されている場合は、 WskRelease 関数を呼び出して、できるだけ早くバッファーを解放する必要があります。
WSK_FLAG_ENTIRE_MESSAGE	データバッファーには、メッセージ全体またはメッセージの最後の部分が含まれます。メッセージ全体を構成するものの解釈は、トランスポートプロトコル固有です。 TCP の場合、このフラグは、データバッファー内のデータを構成する 1 つ以上の TCP セグメントに対してプッシュビットが設定されたことを示します。
WSK_FLAG_AT_DISPATCH_LEVEL	WSK サブシステムは、IRQL = DISPATCH_LEVELで WskReceiveEvent イベントコールバック関数を呼び出しました。このフラグが設定されていない場合、WSK サブシステムは、IRQL <= DISPATCH_LEVELで WskReceiveEvent イベントコールバック関数を呼び出している可能性があります。

[in, optional] DataIndication

受信したデータを記述するWSK_DATA_INDICATION 構造体のリンクされたリストへのポインター。このパラメーターが NULL の場合、ソケットは機能しなくなり、WSK アプリケーションは WskCloseSocket 関数を呼び出して、できるだけ早くソケットを閉じる必要があります。

[in] BytesIndicated

WSK_DATA_INDICATION構造体のリンクされたリストによって記述された受信データのバイト数。

[in, out] BytesAccepted

WSK アプリケーションによって受け入れられる受信データのバイト数を受け取る、SIZE_T型指定された変数へのポインター。この変数は、WSK アプリケーションが受信データの合計バイト数の一部を受け入れる場合にのみ設定する必要があります。 WSK アプリケーションが受信したすべてのデータを受け入れる場合、この変数を設定する必要はありません。 WskReceiveEvent イベントコールバック関数がSTATUS_SUCCESS以外の状態を返す場合、WSK サブシステムはこの変数の値を無視します。

戻り値

WSK アプリケーションの WskReceiveEvent イベントコールバック関数は、次のいずれかの NTSTATUS コードを返すことができます。

リターンコード	説明
STATUS_SUCCESS	WSK アプリケーションは、受信したデータの少なくとも一部を受け入れた。 WSK アプリケーションが受信したすべてのデータを受け入れた場合、WSK サブシステムは、ソケットで新しいデータを受信したときに、WskReceiveEvent イベントコールバック関数を再度呼び出すことができます。ただし、WSK アプリケーションが受信したデータの一部のみを受け入れた場合、WSK アプリケーションが WskReceive 関数を呼び出すまで、WSK サブシステムは WskReceiveEvent イベントコールバック関数を再度呼び出しません。 WSK アプリケーションが WskReceive 関数を呼び出すと、WSK サブシステムは、バッファーに格納された残りのデータを含む WskReceiveEvent イベントコールバック関数の呼び出しを再開し、ソケットで新しいデータを受信します。 WSK アプリケーションは、長さ 0 のバッファーを使用して WskReceive 関数を呼び出すことができます。これにより、WSK サブシステムは WskReceive を呼び出さずに WskReceiveEvent イベントコールバック関数の呼び出しを再開し、ソケットからデータを受信します。
STATUS_PENDING	WSK アプリケーションはデータを受け入れたが、WSK_DATA_INDICATION構造のリンクされたリストに含まれるすべてのデータを取得しなかった。 WSK アプリケーションは、すべてのデータが取得されるまで、WSK_DATA_INDICATION構造のリンクされたリストを保持します。 WSK アプリケーションは、すべてのデータを取得した後、 WskRelease 関数を呼び出して、WSK_DATA_INDICATION構造体のリンクされたリストを WSK サブシステムに解放します。 WSK サブシステムは、ソケットで新しいデータを受信したときに、WskReceiveEvent イベントコールバック関数を再度呼び出すことができます。
STATUS_DATA_NOT_ACCEPTED	WSK アプリケーションがデータを受け入れませんでした。この状況では、可能であれば、WSK サブシステムに基になるトランスポートバッファーがデータに格納されます。それ以外の場合はプロトコルで必要になります。 WSK サブシステムは、 WSK アプリケーションが WskReceive 関数を呼び出すまで、 WskReceiveEvent イベントコールバック関数を再度呼び出しません。 WSK アプリケーションが WskReceive 関数を呼び出すと、WSK サブシステムは、バッファーに格納された残りのデータを含む WskReceiveEvent イベントコールバック関数の呼び出しを再開し、ソケットで新しいデータを受信します。 WSK アプリケーションは、長さ 0 のバッファーを使用して WskReceive 関数を呼び出すことができます。これにより、WSK サブシステムは WskReceive を呼び出さずに WskReceiveEvent イベントコールバック関数の呼び出しを再開し、ソケットからデータを受信します。

注釈

WSK サブシステムは、イベントコールバック関数が以前に SO_WSK_EVENT_CALLBACK ソケットオプションで有効になっていた場合にのみ、接続指向ソケットで新しいデータを受信したときに、WSK アプリケーションの WskReceiveEvent イベントコールバック関数を呼び出します。ソケットのイベントコールバック関数を有効にする方法の詳細については、「イベントコールバック関数の有効化と無効化」を参照してください。

WSK アプリケーションの WskReceiveEvent イベントコールバック関数が接続指向ソケットで有効になっており、アプリケーションで同じ接続指向ソケット上の WskReceive 関数の呼び出しも保留中の場合、データが到着すると、 WskReceive 関数の保留中の呼び出しが WskReceiveEvent イベントコールバック関数よりも優先されます。 WSK サブシステムは、アプリケーションの WskReceiveEvent イベントコールバック関数を呼び出します。これは、 WskReceive 関数の保留中の呼び出しからキューに登録された IRP がない場合のみです。ただし、WSK アプリケーションでは、WskReceive 関数の呼び出しが保留中の接続指向ソケットに対して、WSK サブシステムがアプリケーションの WskReceiveEvent イベントコールバック関数を呼び出さないと想定しないでください。競合状態は、WSK サブシステムがソケットの WSK アプリケーションの WskReceiveEvent イベントコールバック関数を引き続き呼び出すことができる場所に存在します。 WSK アプリケーションが接続指向ソケットに対してアプリケーションの WskReceiveEvent イベントコールバック関数を呼び出さないことを WSK アプリケーションが確認する唯一の方法は、ソケットでアプリケーションの WskReceiveEvent イベントコールバック関数を無効にすることです。

注意

Winsock Kernel (WSK) は、このコールバックを順次呼び出すので、データを受信するとすぐに呼び出されるとは限りません。

WSK サブシステムは、WSK アプリケーションの WskReceiveEvent イベントコールバック関数を IRQL <= DISPATCH_LEVELで呼び出します。

WSK アプリケーションの WskReceiveEvent イベントコールバック関数は、WSK 完了関数またはイベントコールバック関数のコンテキストで、他の WSK 要求の完了を待つ必要はありません。コールバックは、他の WSK 要求を開始できますが (DISPATCH_LEVELで時間がかかりすぎないことを前提とします)、IRQL = PASSIVE_LEVEL でコールバックが呼び出された場合でも、その完了を待つ必要はありません。

要件

要件	値
サポートされている最小のクライアント	Windows Vista 以降のバージョンの Windows オペレーティングシステムで使用できます。
対象プラットフォーム	Windows
ヘッダー	wsk.h (Wsk.h を含む)
IRQL	<= DISPATCH_LEVEL