WSAIoctl 関数 (winsock2.h)

WSAIoctl 関数は、ソケットのモードを制御します。

構文

int WSAAPI WSAIoctl(
  [in]  SOCKET                             s,
  [in]  DWORD                              dwIoControlCode,
  [in]  LPVOID                             lpvInBuffer,
  [in]  DWORD                              cbInBuffer,
  [out] LPVOID                             lpvOutBuffer,
  [in]  DWORD                              cbOutBuffer,
  [out] LPDWORD                            lpcbBytesReturned,
  [in]  LPWSAOVERLAPPED                    lpOverlapped,
  [in]  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

パラメーター

[in] s

ソケットを識別する記述子。

[in] dwIoControlCode

実行する操作の制御コード。 Winsock IOCTLを参照してください。

[in] lpvInBuffer

入力バッファーへのポインター。

[in] cbInBuffer

入力バッファーのサイズ (バイト単位)。

[out] lpvOutBuffer

出力バッファーへのポインター。

[in] cbOutBuffer

出力バッファーのサイズ (バイト単位)。

[out] lpcbBytesReturned

出力の実際のバイト数へのポインター。

[in] lpOverlapped

WSAOVERLAPPED 構造体へのポインター (重複していないソケットの場合は無視されます)。

[in] lpCompletionRoutine

型: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

戻り値

正常に完了すると、WSAIoctl は 0 を返します。 それ以外の場合は、SOCKET_ERRORの値が返され、WSAGetLastError呼び出すことによって特定のエラー コードを取得できます。

備考

WSAIoctl 関数は、ソケット、トランスポート プロトコル、または通信サブシステムに関連付けられている操作パラメーターを設定または取得するために使用されます。

lpOverlapped lpCompletionRoutine の両方が NULL場合、この関数のソケットは重複していないソケットとして扱われます。 重複していないソケットの場合、lpOverlapped と lpCompletionRoutine パラメーター は無視されます。これにより、関数は標準の ioctlsocket 関数と同様に動作しますが、ソケット がブロック モードの場合は関数がブロックできます。 ソケット が非ブロッキング モードの場合、指定した操作をすぐに完了できないときに、この関数は WSAEWOULDBLOCK を返すことができます。 この場合、アプリケーションは、Windows メッセージ (WSAAsyncSelectを使用) またはイベント (WSAEventSelectを 使用) ベースのイベントを使用して、ソケットをブロック モードに変更し、対応するネットワーク イベント (SIO_ROUTING_INTERFACE_CHANGE や SIO_ADDRESS_LIST_CHANGEの場合はFD_ROUTING_INTERFACE_CHANGEやFD_ADDRESS_LIST_CHANGEなど) を待つ場合があります (WSAEventSelect使用)。

重複するソケットの場合、すぐに完了できない操作が開始され、完了は後で示されます。 返される lpcbBytesReturned パラメーターが指す DWORD 値は無視できます。 最終的な完了状態と返されるバイトは、操作が完了したときに適切な完了メソッドが通知されたときに取得できます。

サービス プロバイダーの実装によっては、IOCTL が無期限にブロックされる場合があります。 アプリケーションが WSAIoctl 呼び出しでのブロックを許容できない場合は、特にブロックする可能性が高い IOCTL に対して重複した I/O が推奨されます。

SIO_ADDRESS_LIST_CHANGE

SIO_FINDROUTE

SIO_FLUSH

SIO_GET_QOS

SIO_GET_GROUP_QOS

SIO_ROUTING_INTERFACE_CHANGE

SIO_SET_QOS

SIO_SET_GROUP_QOS

プロトコル固有の IOCTL によっては、ブロックされる可能性が特に高い場合もあります。 利用可能な情報については、関連するプロトコル固有の付属書を確認してください。

lpCompletionRoutine パラメーターが指す完了ルーチンのプロトタイプは次のとおりです。

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")


void CALLBACK CompletionRoutine (
  IN DWORD dwError,
  IN DWORD cbTransferred,
  IN LPWSAOVERLAPPED lpOverlapped,
  IN DWORD dwFlags 
);

CompletionRoutine は、アプリケーションが指定した関数名のプレースホルダーです。 dwError パラメーターは、lpOverlapped パラメーターで示されているように、重複する操作の完了状態 指定します。 cbTransferred パラメーターは、受信したバイト数を指定します。 dwFlags パラメーターは、この IOCTL には使用されません。 完了ルーチンは値を返しません。

現在定義されている ioctlsocket オペコード を保持するエンコード スキームを採用すると同時に、dwIoControlCode パラメーターが 32 ビット エンティティである限り、オペコード識別子領域をパーティション分割する便利な方法を提供できます。 dwIoControlCode パラメーターは、Windows Sockets 1.1 および Unix コントロール コードとの下位互換性を維持しながら、新しいコントロール コードを追加するときにプロトコルとベンダーの独立を可能にするために構築されています。 dwIoControlCode パラメーターの形式は次のとおりです。

O は、IOC_OUTと同様に、出力バッファーがコードに対して有効な場合に設定されます。 入力バッファーと出力バッファーの両方を使用する制御コードは、I と O の両方を設定します。

IOC_VOIDと同様に、コードのパラメーターがない場合は V が設定されます。

T は、IOCTL の型を定義する 2 ビット数量です。 次の値が定義されています。

0 IOCTL は、FIONREAD および FIONBIOと同様に、標準的な Unix IOCTL コードです。

1 IOCTL は、汎用の Windows ソケット 2 IOCTL コードです。 Windows ソケット 2 に対して定義された新しい IOCTL コードには、T == 1 が含まれます。

2 IOCTL は、特定のアドレス ファミリにのみ適用されます。

3 IOCTL は、IOC_VENDORと同様に、特定のベンダーのプロバイダーにのみ適用されます。 このタイプでは、会社に、仕入先/住所ファミリの パラメータに表示される仕入先番号を割り当てることができます。 その後、ベンダーは、クリアリングハウスに IOCTL を登録しなくても、そのベンダーに固有の新しい IOCTL を定義できるため、ベンダーの柔軟性とプライバシーが提供されます。

ベンダー/住所ファミリ コードを所有するベンダーを定義する 11 ビット数量(T == 3 の場合)、またはコードが適用されるアドレス ファミリ (T == 2 の場合) を含む 11 ビット数量です。 これが Unix IOCTL コード (T == 0) の場合、このパラメーターの値は Unix 上のコードと同じです。 これが汎用 Windows ソケット 2 IOCTL (T == 1) の場合、このパラメーターをコード パラメーターの拡張として使用して、追加のコード値を指定できます。

コード 操作の特定の IOCTL コードを含む 16 ビットの数量。

次の Unix IOCTL コード (コマンド) がサポートされています。

次の Windows ソケット 2 コマンドがサポートされています。

重複した操作がすぐに完了すると、WSAIoctl 0 の値が返され、lpcbBytesReturned パラメーターが出力バッファー内のバイト数で更新されます。 重複した操作が正常に開始され、後で完了する場合、この関数はSOCKET_ERRORを返し、エラー コード WSA_IO_PENDINGを示します。 この場合、lpcbBytesReturned は更新されません。 重複する操作が完了すると、出力バッファー内のデータ量は、完了ルーチンの cbTransferred パラメーター (指定されている場合) または WSAGetOverlappedResultの lpcbTransfer パラメーター 使用して示されます。

重複するソケットを使用して呼び出された場合、lpOverlapped パラメーター は、重複する操作の間有効である必要があります。 lpOverlapped パラメーターには、WSAOVERLAPPED 構造体のアドレスが含まれています。

lpCompletionRoutine パラメーターが NULL場合、重複した操作が完了したときに、lpOverlapped の hEvent パラメーターが通知されます (有効なイベント オブジェクト ハンドルが含まれている場合)。 アプリケーションは、WSAWaitForMultipleEvents 使用することも、WSAGetOverlappedResult を してイベント オブジェクトを待機またはポーリングすることもできます。

void CALLBACK CompletionRoutine(
  IN DWORD dwError, 
  IN DWORD cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD dwFlags 
);