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

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

WskControlSocket 関数は、ソケットに対して制御操作を実行します。

構文

PFN_WSK_CONTROL_SOCKET PfnWskControlSocket;

NTSTATUS PfnWskControlSocket(
  [in]            PWSK_SOCKET Socket,
  [in]            WSK_CONTROL_SOCKET_TYPE RequestType,
  [in]            ULONG ControlCode,
  [in]            ULONG Level,
  [in]            SIZE_T InputSize,
  [in, optional]  PVOID InputBuffer,
  [in]            SIZE_T OutputSize,
  [out, optional] PVOID OutputBuffer,
  [out, optional] SIZE_T *OutputSizeReturned,
  [in, out]       PIRP Irp
)
{...}

パラメーター

[in] Socket

制御操作が実行されているソケットのソケットオブジェクトを指定するWSK_SOCKET構造体へのポインター。

[in] RequestType

実行されるコントロール操作の種類を示す値。 WSK アプリケーションは、このパラメーターを次のいずれかの値に設定します。

WskSetOption

ソケットオプションの状態または値を設定します。

WskGetOption

ソケットオプションの状態または値を取得します。

WskIoctl

I/O 制御操作を実行します。

[in] ControlCode

RequestType パラメーターが WskSetOption または WskGetOption に設定されている場合、ControlCode パラメーターは、値が設定または取得される特定のソケットオプションを指定します。 WSK サブシステムでサポートされるソケットオプションの詳細については、「 WSK ソケットオプション」を参照してください。基になるネットワークプロトコルでは、追加のソケットオプションがサポートされる場合があります。

RequestType パラメーターが WskIoctl に設定されている場合、ControlCode パラメーターは、実行されている特定の I/O 制御操作を指定します。 WSK サブシステムでサポートされる I/O 制御操作の詳細については、「 WSK ソケット IOCTL 操作」を参照してください。基になるネットワークプロトコルでは、追加のソケット I/O 制御操作がサポートされる場合があります。

[in] Level

ソケットオプションの値が設定または取得されるネットワークスタック内のレベル。 WSK サブシステム・レベルのソケット・オプションの場合、WSK アプリケーションはこのパラメーターをSOL_SOCKETに設定する必要があります。トランスポートプロトコルまたはネットワークプロトコルレベルのソケットオプションの場合、WSK アプリケーションは、このパラメーターを基になるトランスポートの適切なレベルに設定する必要があります。

RequestType パラメーターが WskIoctl に設定されている場合、Level パラメーターは無視されます。

[in] InputSize

InputBuffer パラメーターによって指されるバッファー内のデータのバイト数。

[in, optional] InputBuffer

指定した制御操作を実行するために必要な入力データを提供する呼び出し元によって割り当てられたバッファー。指定した制御操作に入力データが必要ない場合、WSK アプリケーションはこのパラメーターを NULL に設定し、 InputSize パラメーターを 0 に設定する必要があります。

[in] OutputSize

OutputBuffer パラメーターによって指されるバッファーのサイズ。

[out, optional] OutputBuffer

指定された制御操作によって返される出力データを受け取る呼び出し元によって割り当てられたバッファー。指定した制御操作によって出力データが返されない場合、WSK アプリケーションはこのパラメーターを NULL に設定し、 OutputSize パラメーターを 0 に設定する必要があります。

[out, optional] OutputSizeReturned

OutputBuffer パラメーターによって指されるバッファーで返されるデータのバイト数を受け取る ULONG 型の変数へのポインター。 WSK アプリケーションでは、次のすべてが当てはまる場合を除き、 OutputSizeReturned パラメーターを NULL に設定する必要があります。

Irp パラメーターは NULL に設定されています。
実行されている操作は、 OutputBuffer パラメーターによって指されるバッファー内の出力データを返します。
実行されている操作によって返される出力データのバイト数が不明です。

[in, out] Irp

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

RequestType パラメーターが WskSetOption または WskGetOption に設定されている場合、Irp パラメーターは必須、省略可能、または設定または取得される特定のソケットオプションに応じて NULL である必要があります。サポートされている各ソケットオプションの Irp パラメーターの要件の詳細については、「 WSK ソケットオプション」を参照してください。

RequestType パラメーターが WskIoctl に設定されている場合、Irp パラメーターは必須、省略可能、または実行されている特定の I/O 制御操作に応じて NULL である必要があります。サポートされている各 I/O 制御操作の Irp パラメーターの要件の詳細については、「 WSK ソケット IOCTL 操作」を参照してください。

戻り値

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

リターンコード	説明
STATUS_SUCCESS	制御操作が正常に完了しました。 WSK アプリケーションが Irp パラメーターで IRP へのポインターを指定した場合、IRP は成功状態で完了し、 OutputBuffer パラメーターによって指されるバッファーに返されるバイト数は、IRP の IoStatus.Information フィールドに返されます。
STATUS_PENDING	WSK サブシステムが制御操作をすぐに完了できませんでした。 WSK サブシステムは、制御操作が完了した後に IRP を完了します。コントロール操作の状態は、IRP の IoStatus.Status フィールドに返されます。操作が成功した場合、 OutputBuffer パラメーターによって指されるバッファーで返されるバイト数は、IRP の IoStatus.Information フィールドに返されます。
STATUS_EVENT_PENDING	WSK サブシステムが制御操作をすぐに完了できませんでした。この値は、WSK アプリケーションがそのイベントコールバック関数の現在進行中の呼び出しがあり、 Irp パラメーターが NULL の場合に、ソケットでイベントコールバック関数を無効にしている場合にのみ返されます。イベントコールバック関数の無効化の詳細については、「 SO_WSK_EVENT_CALLBACK」を参照してください。
STATUS_FILE_FORCED_CLOSED	ソケットは機能しなくなりました。 IRP は失敗状態で完了します。 WSK アプリケーションは、できるだけ早くソケットを閉じるには、WskCloseSocket 関数を呼び出す必要があります。
その他の状態コード	エラーが発生しました。 IRP は失敗状態で完了します。

注釈

WSK アプリケーションが RequestType パラメーターで WskSetOption または WskGetOption を指定する場合、ソケットオプションごとに入力バッファーと出力バッファーを使用する方法の詳細については、「WSK ソケットオプション」を参照してください。

WSK アプリケーションが RequestType パラメーターで WskIoctl を指定する場合、入出力制御操作ごとに入出力バッファーがどのように使用されるかの詳細については、「WSK ソケット IOCTL 操作」を参照してください。

WskControlSocket 関数がSTATUS_PENDINGを返す場合は、InputBuffer パラメーターまたは OutputBuffer パラメーターが指すバッファーは、IRP が完了するまで有効なままである必要があります。 WSK アプリケーションが ExAllocateXxx 関数のいずれかを使用してバッファーを割り当てた場合、IRP が完了するまで、対応する ExFreeXxx 関数を使用してメモリを解放することはできません。 WSK アプリケーションがスタック上のバッファーを割り当てた場合、IRP が完了するまで 、WskControlSocket 関数を呼び出す関数からを返すことはできません。

WskControlSocket 関数の呼び出し元は、RequestType パラメーターが WskIoctl に設定され、ControlCode パラメーターが SIO_ADDRESS_LIST_QUERY、SIO_ADDRESS_LIST_CHANGE、または SIO_ADDRESS_LIST_SORT に設定されている場合を除き、IRQL <= DISPATCH_LEVELで実行されている必要があります。このような場合、呼び出し元は IRQL = PASSIVE_LEVELで実行されている必要があります。

要件

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