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

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

WskReceiveFromEvent イベントコールバック関数は、1 つ以上のデータグラムがデータグラムソケットで受信されたことを WSK アプリケーションに通知します。

構文

PFN_WSK_RECEIVE_FROM_EVENT PfnWskReceiveFromEvent;

NTSTATUS PfnWskReceiveFromEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATAGRAM_INDICATION DataIndication
)
{...}

パラメーター

[in, optional] SocketContext

データグラムを受信したデータグラムソケットのソケットコンテキストへのポインター。 WSK アプリケーションは、 WskSocket 関数を呼び出してデータグラムソケットを作成するときに、WSK サブシステムへのこのポインターを提供しました。

[in] Flags

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

MSG_BCAST

データグラムは、リンク層ブロードキャストとして、またはブロードキャスト・アドレスである宛先トランスポート・アドレスを使用して受信されました。

MSG_MCAST

データグラムは、マルチキャストアドレスである宛先トランスポートアドレスで受信されました。

WSK_FLAG_AT_DISPATCH_LEVEL

WSK サブシステムは、IRQL = DISPATCH_LEVEL の WskReceiveFromEvent イベントコールバック関数と呼ばれます。このフラグが設定されていない場合、WSK サブシステムは IRQL <= DISPATCH_LEVELで WskReceiveFromEvent イベントコールバック関数を呼び出した可能性があります。

[in, optional] DataIndication

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

戻り値

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

リターンコード	説明
STATUS_SUCCESS	WSK アプリケーションは、データグラムを受け入れ、のリンクされたリストからすべてのデータグラムを取得しました WSK_DATAGRAM_INDICATION 構造体。 WSK サブシステムは、ソケットで新しいデータグラムを受信したときに、WskReceiveFromEvent イベントコールバック関数を再度呼び出すことができます。
STATUS_PENDING	WSK アプリケーションはデータグラムを受け入れたが、のリンクされたリストからすべてのデータグラムを取得しなかった WSK_DATAGRAM_INDICATION 構造体。 WSK アプリケーションは、すべてのデータグラムが取得されるまで、WSK_DATAGRAM_INDICATION構造体のリンクされたリストを保持します。 WSK アプリケーションは、すべてのデータグラムを取得した後、 WskRelease 関数を呼び出して、WSK_DATAGRAM_INDICATION構造体のリンクされたリストを WSK サブシステムに解放します。 WSK サブシステムは、ソケットで新しいデータグラムを受信したときに、WskReceiveFromEvent イベントコールバック関数を再度呼び出すことができます。
STATUS_DATA_NOT_ACCEPTED	WSK アプリケーションがデータグラムを受け入れませんでした。 WSK アプリケーションがこの状態コードを返す場合、WSK サブシステムは、WSK アプリケーションが WskReceiveFromEvent イベントコールバック関数を有効にした方法に応じて、異なる方法で応答します。 WSK アプリケーションが SO_WSK_EVENT_CALLBACK ソケットオプションを使用して WskReceiveFromEvent イベントコールバック関数を有効にした場合、WSK サブシステムは、可能であれば、またはプロトコルで必要な場合は、基になるトランスポートバッファーをデータグラムに格納します。 WSK サブシステムは WskReceiveFromEvent イベントコールバック関数を無効にし、WSK アプリケーションで SO_WSK_EVENT_CALLBACK ソケットオプションを使用してこのイベントコールバック関数を再度有効にするまで、 WskReceiveFromEvent イベントコールバック関数を再度呼び出しません。 WSK アプリケーションで WskReceiveFromEvent イベントコールバック関数が再び有効になると、WSK サブシステムは、バッファーに格納された残りのデータグラムと、ソケットで新しいデータグラムを受信したときに、WskReceiveFromEvent イベントコールバック関数の呼び出しを再開します。 WSK アプリケーションがを使用して WskReceiveFromEvent イベントコールバック関数を有効にした場合、クライアント制御操作WSK_SET_STATIC_EVENT_CALLBACKS、WSK サブシステムは WskReceiveFromEvent イベントコールバック関数を無効にしません。 WSK サブシステムは、ソケットで新しいデータグラムを受信したときに、WskReceiveFromEvent イベントコールバック関数の呼び出しを続行します。

注釈

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

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

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

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

要件

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