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

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

WskReceiveFrom 関数は、リモートトランスポートアドレスからデータグラムと関連する制御情報を受け取ります。

構文

PFN_WSK_RECEIVE_FROM PfnWskReceiveFrom;

NTSTATUS PfnWskReceiveFrom(
  [in]            PWSK_SOCKET Socket,
  [in]            PWSK_BUF Buffer,
                  ULONG Flags,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PULONG ControlLength,
  [out, optional] PCMSGHDR ControlInfo,
  [out, optional] PULONG ControlFlags,
  [in, out]       PIRP Irp
)
{...}

パラメーター

[in] Socket

データグラムを受信するデータグラムソケットのソケットオブジェクトを指定するWSK_SOCKET構造体へのポインター。

[in] Buffer

ソケットからデータグラムを受信するデータバッファーを記述する初期化された WSK_BUF 構造体へのポインター。

Flags

このパラメーターは、システムで使用するために予約されています。 WSK アプリケーションでは、このパラメーターを 0 に設定する必要があります。

[out, optional] RemoteAddress

受信したデータグラムの送信元のリモートトランスポートアドレスを受信する呼び出し元によって割り当てられたバッファーへのポインター。バッファーは、ページ以外のメモリに配置する必要があります。バッファーは、WSK アプリケーションがデータグラムソケットの作成時に指定したアドレスファミリに対応する特定の SOCKADDR 構造体型を格納するのに十分な大きさにする必要もあります。このポインターは省略可能であり、 NULL にすることができます。

[in, out] ControlLength

ControlInfo パラメーターによって指されるバッファーのサイズを指定する ULONG へのポインター。受信操作が完了すると、変数は、受信したデータグラムに関連付けられている制御情報のサイズを受け取ります。返される値が 0 の場合、データグラムの制御情報は存在しません。このポインターは省略可能であり、 NULL にすることができます。このパラメーターが NULL の場合、 ControlInfo パラメーターは無視されます。

[out, optional] ControlInfo

受信したデータグラムに関連付けられている制御情報を受け取る呼び出し元によって割り当てられたバッファーへのポインター。データグラムに関連付けられている制御情報データは、それぞれ CMSGHDR 構造体で始まる 1 つ以上の制御データ・オブジェクトで構成されます。受信したデータグラムに制御情報が存在しない場合、バッファーの内容は未定義です。このポインターは省略可能であり、 NULL にすることができます。 ControlInfoLength パラメーターが NULL の場合、ControlInfo パラメーターは NULL である必要があります。

[out, optional] ControlFlags

次のフラグの組み合わせのビットごとの OR を受け取る ULONG 型の変数へのポインター。

MSG_BCAST

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

MSG_MCAST

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

MSG_TRUNC

データグラムのサイズが Buffer パラメーターで指定されたバッファーのサイズより大きかったため、データグラムが切り捨てられました。

MSG_CTRUNC

制御情報のバイト数が ControlInfo パラメーターで指定されたバッファーのサイズより大きかったため、制御情報データが切り捨てられました。

このパラメーターは省略可能であり、 NULL にすることができます。

[in, out] Irp

WSK サブシステムが非同期的に受信操作を完了するために使用する呼び出し元によって割り当てられた IRP へのポインター。 WSK 関数で IRP を使用する方法の詳細については、「 Winsock カーネル関数での IRP の使用」を参照してください。

戻り値

WskReceiveFrom は 、次のいずれかの NTSTATUS コードを返します。

リターンコード	説明
STATUS_SUCCESS	ソケットからデータが正常に受信されました。 IRP は成功状態で完了します。 IRP の IoStatus.Information フィールドには、受信したバイト数が含まれています。
STATUS_PENDING	WSK サブシステムは、ソケットからデータグラムをすぐに受信できませんでした。 WSK サブシステムは、ソケットからデータグラムを受信した後に IRP を完了します。受信操作の状態は、IRP の IoStatus.Status フィールドに返されます。操作が成功した場合、IRP の IoStatus.Information フィールドには、受信したバイト数が含まれます。
STATUS_FILE_FORCED_CLOSED	ソケットは機能しなくなりました。 IRP は失敗状態で完了します。 WSK アプリケーションは、できるだけ早くソケットを閉じるには、WskCloseSocket 関数を呼び出す必要があります。
その他の状態コード	エラーが発生しました。 IRP は失敗状態で完了します。

注釈

WSK アプリケーションでデータグラムソケットの固定リモートトランスポートアドレスが設定されている場合、他のリモートトランスポートアドレスから受信したデータグラムは WSK サブシステムによって破棄されます。データグラムソケットのリモートトランスポートアドレスの設定の詳細については、「 SIO_WSK_SET_REMOTE_ADDRESS」を参照してください。

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

WskReceiveFrom 関数がSTATUS_PENDINGを返す場合、Buffer パラメーターによって指されるWSK_BUF構造体に記述されている MDL チェーンは、IRP が完了するまでメモリ内でロックされたままになります。さらに、 ControlInfoLength パラメーターによって指される変数、 ControlInfo パラメーターによって指されるバッファー、および ControlFlags パラメーターによって指される変数も、IRP が完了するまで有効なままである必要があります。 WSK アプリケーションが ExAllocateXxx 関数のいずれかを使用してこれらのバッファーまたは変数を割り当てた場合、IRP が完了するまで、対応する ExFreeXxx 関数を使用してメモリを解放することはできません。 WSK アプリケーションがこれらのバッファーまたは変数をスタックに割り当てた場合、IRP が完了するまで WskReceiveFrom 関数を呼び出す関数からを返すことはできません。

要件

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