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 を呼び出すことによって特定のエラー コードを取得できます。
| エラー コード | 意味 |
|---|---|
| 重複した操作が正常に開始され、後で完了が示されます。 | |
| ネットワーク サブシステムが失敗しました。 | |
| lpvInBuffer、lpvOutBuffer、lpcbBytesReturned、lpOverlapped、または lpCompletionRoutine パラメーターが、ユーザー アドレス空間の有効な部分に完全に含まれていないか、cbInBuffer パラメーターまたは cbOutBuffer パラメーターが小さすぎます。 | |
| dwIoControlCode パラメーターが有効なコマンドではないか、指定した入力パラメーターが受け入れられないか、指定されたソケットの型にコマンドが適用されません。 | |
| 関数は、コールバックが進行中のときに呼び出されます。 | |
| 記述子 s はソケットではありません。 | |
| 指定された IOCTL コマンドを実現できません。 (たとえば、SIO_SET_QOS または SIO_SET_GROUP_QOS で指定された FLOWSPEC 構造体は満たされません。 | |
| ソケットは非ブロッキングとしてマークされ、要求された操作はブロックされます。 | |
| ソケット オプションは、指定されたプロトコルではサポートされていません。 たとえば、 IPv6 ソケットで SIO_GET_BROADCAST_ADDRESS IOCTL を使用しようとしたり、データグラム ソケットで TCP SIO_KEEPALIVE_VALS IOCTL を使用しようとしたりしたとします。 |
注釈
WSAIoctl 関数は、ソケット、トランスポート プロトコル、または通信サブシステムに関連付けられている操作パラメーターを設定または取得するために使用されます。
lpOverlapped と lpCompletionRoutine の両方が NULL の場合、この関数のソケットは重複していないソケットとして扱われます。 重複していないソケットの場合、 lpOverlapped パラメーターと lpCompletionRoutine パラメーターは無視されます。これにより、関数は標準 の ioctlsocket 関数と同様に動作します。ただし、ソケット s がブロック モードの場合、関数はブロックできます。 ソケット s が非ブロッキング・モードの場合、指定された操作をすぐに完了できない場合、この関数は WSAEWOULDBLOCK を戻すことができます。 この場合、アプリケーションはソケットをブロッキング モードに変更し、(WSAAsyncSelect を使用して) Windows メッセージまたはイベント (WSAEventSelect を使用) ベースの通知メカニズムを使用して、対応するネットワーク イベント (SIO_ROUTING_INTERFACE_CHANGEやSIO_ADDRESS_LIST_CHANGEの場合はFD_ROUTING_INTERFACE_CHANGEやFD_ADDRESS_LIST_CHANGEなど) を要求を再発行するか待つ場合があります。
重複するソケットの場合、すぐには完了できない操作が開始され、完了は後で示されます。 返される 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 ソケット 1.1 および Unix コントロール コードとの下位互換性を維持しながら、新しいコントロール コードを追加するときにプロトコルとベンダーの独立性を確保するために構築されています。 dwIoControlCode パラメーターの形式は次のとおりです。
| I | O | V | T | ベンダー/アドレス ファミリ | コード |
|---|---|---|---|---|---|
| 3 | 3 | 2 | 2 2 | 2 2 2 2 2 2 2 1 1 1 1 | 1 1 1 1 1 1 |
| 1 | 0 | 9 | 8 7 | 6 5 4 3 2 1 0 9 8 7 6 | 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 |
出力バッファーがコードに対して有効な場合は、IOC_OUTと同様に O が設定 されます。 入出力バッファーの両方を使用する制御コードは、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 の場合) またはコードが適用されるアドレス ファミリを含む 11 ビット数量 (T == 2 の場合)。 これが 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
);
この CompletionRoutine は、アプリケーション定義関数またはライブラリ定義関数のプレースホルダーです。 完了ルーチンは、スレッドがアラート可能な状態にある場合にのみ呼び出されます。 スレッドをアラート可能な状態にするには、fAlertable パラメーターまたは bAlertable パラメーターを TRUE に設定して、WSAWaitForMultipleEvents、WaitForSingleObjectEx、または WaitForMultipleObjectsEx 関数を使用します。
CompletionRoutine の dwError パラメーターは、lpOverlapped で示されているように、重複する操作の完了状態を指定します。 cbTransferred パラメーターは、返されるバイト数を指定します。 現在、フラグ値は定義されておらず、 dwFlags は 0 になります。 CompletionRoutine 関数は値を返しません。
この関数から戻って、このソケットに対して別の保留中の完了ルーチンを呼び出すことができます。 完了ルーチンは任意の順序で呼び出すことができます。重複する操作が完了した順序は必ずしも同じではありません。
互換性
T == 0 の IOCTL コードは、Berkeley ソケットで使用される IOCTL コードのサブセットです。 特に、 FIOASYNC と同等のコマンドはありません。Windows 8.1とWindows Server 2012 R2: この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストア アプリでサポートされています。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8.1、Windows Vista [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winsock2.h |
| Library | Ws2_32.lib |
| [DLL] | Ws2_32.dll |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示