SIO_ADDRESS_LIST_QUERY コントロール コード
説明
SIO_ADDRESS_LIST_QUERY制御コードは、アプリケーションがバインドできるソケットのプロトコル ファミリのローカル トランスポート アドレスの一覧を取得します。 住所の一覧はアドレス ファミリによって異なり、一部の住所はリストから除外されます。
この操作を実行するには、次のパラメーターを使用して WSAIoctl または WSPIoctl 関数を呼び出します。
int WSAIoctl(
(socket) s, // descriptor identifying a socket
SIO_ADDRESS_LIST_QUERY, // dwIoControlCode
NULL, // lpvInBuffer
0, // cbInBuffer
(LPVOID) lpvOutBuffer, // output buffer
(DWORD) cbOutBuffer, // size of output buffer
(LPDWORD) lpcbBytesReturned, // number of bytes returned
(LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
(LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine, // completion routine
);
int WSPIoctl(
(socket) s, // descriptor identifying a socket
SIO_ADDRESS_LIST_QUERY, // dwIoControlCode
NULL, // lpvInBuffer
0, // cbInBuffer
(LPVOID) lpvOutBuffer, // output buffer
(DWORD) cbOutBuffer, // size of output buffer
(LPDWORD) lpcbBytesReturned, // number of bytes returned
(LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
(LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine, // completion routine
(LPWSATHREADID) lpThreadId, // a WSATHREADID structure
(LPINT) lpErrno // a pointer to the error code.
);
パラメーター
s
ソケットを識別する記述子。
dwIoControlCode
操作の制御コード。 この操作 にはSIO_ADDRESS_LIST_QUERY を使用します。
lpvInBuffer
入力バッファーへのポインター。 このパラメーターは、この操作では使用されません。
cbInBuffer
入力バッファーのサイズ (バイト単位)。 このパラメーターは、この操作では使用されません。
lpvOutBuffer
出力バッファーへのポインター。
cbOutBuffer
出力バッファーのサイズ (バイト単位)。
lpcbBytesReturned
出力バッファーに格納されているデータのサイズをバイト単位で受け取る変数へのポインター。
lpvOverlapped
WSAOVERLAPPED 構造体へのポインター。
重複する属性なしでソケット s が作成された場合、 lpOverlapped パラメーターは無視されます。
重複した属性を使用して s を開き、 lpOverlapped パラメーターが NULL でない場合、操作は重複 (非同期) 操作として実行されます。 この場合、 lpOverlapped パラメーターは有効な WSAOVERLAPPED 構造体を指している必要があります。
重複する操作の場合、 WSAIoctl または WSPIoctl 関数は直ちにを返し、操作が完了すると適切な完了メソッドが通知されます。 それ以外の場合、操作が完了するかエラーが発生するまで、関数は を返しません。
lpCompletionRoutine
種類: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
操作が完了したときに呼び出される完了ルーチンへのポインター (重複していないソケットの場合は無視されます)。
lpThreadId
WPUQueueApc への後続の呼び出しでプロバイダーによって使用される WSATHREADID 構造体へのポインター。 プロバイダーは、WPUQueueApc 関数が返されるまで、参照先の WSATHREADID 構造体 (同じへのポインターではない) を格納する必要があります。
メモ このパラメーターは 、WSPIoctl 関数にのみ適用されます。
lpErrno
エラー コードへのポインター。
メモ このパラメーターは 、WSPIoctl 関数にのみ適用されます。
戻り値
操作が正常に完了すると、 WSAIoctl または WSPIoctl 関数は 0 を返します。
操作が失敗した場合、または保留中の場合、 WSAIoctl または WSPIoctl 関数は SOCKET_ERRORを返します。 拡張エラー情報を取得するには、 WSAGetLastError を呼び出します。
| エラー コード | 意味 |
|---|---|
| WSA_IO_PENDING | 重複した操作が正常に開始され、完了は後で示されます。 |
| WSA_OPERATION_ABORTED | ソケットのクローズまたは SIO_FLUSH IOCTL コマンドの実行により、重複した操作が取り消されました。 |
| WSAEFAULT | lpOverlapped パラメーターまたは lpCompletionRoutine パラメーターは、ユーザー・アドレス・スペースの有効な部分に完全には含まれていません。 |
| WSAEINPROGRESS | 関数は、コールバックが進行中のときに呼び出されます。 |
| WSAEINTR | ブロック操作が中断されました。 |
| WSAEINVAL | dwIoControlCode パラメーターが有効なコマンドではないか、指定された入力パラメーターが受け入れられないか、指定されたソケットの種類にコマンドが適用されません。 cbInBuffer パラメーターが NULL に設定されていない場合、このエラーが返されます。 |
| WSAENETDOWN | ネットワーク サブシステムが失敗しました。 |
| WSAENOBUFS | 使用できるバッファー領域がありません。 |
| WSAENOPROTOOPT | ソケット オプションは、指定されたプロトコルではサポートされていません。 |
| WSAENOTSOCK | 記述子 s はソケットではありません。 |
| WSAEOPNOTSUPP | 指定された IOCTL コマンドはサポートされていません。 このエラーは、 SIO_ADDRESS_LIST_QUERY IOCTL がトランスポート プロバイダーでサポートされていない場合に返されます。 |
解説
SIO_ADDRESS_LIST_QUERY IOCTL は、Windows 2000 以降のバージョンのオペレーティング システムでサポートされています。
SIO_ADDRESS_LIST_QUERY制御コードは、アプリケーションがバインドできるソケットのプロトコル ファミリのローカル トランスポート アドレスの一覧を取得します。 住所の一覧は、アドレス ファミリによって異なります。
AF_INET6 アドレス ファミリの場合、次を除くすべてのアドレスが返されます。
- 重複アドレス検出 (DAD) 状態が IpDadStatePreferred ではない IP アドレス。
- インターフェイスの種類が IF_TYPE_SOFTWARE_LOOPBACKインターフェイスのスコープ レベルが ScopeLevelSubnet より低い IP アドレス。 つまり、 IF_TYPE_SOFTWARE_LOOPBACK型の インターフェイスのリンク ローカル (fe80:*) アドレスとループバック (::1) アドレスは除外されますが、これらのアドレスが異なる型のインターフェイス上にある場合は除外されません。
AF_INET アドレス ファミリの場合、次を除くすべてのアドレスが返されます。
- 重複アドレス検出 (DAD) 状態が IpDadStatePreferred ではない IP アドレス。
- インターフェイスの種類が IF_TYPE_SOFTWARE_LOOPBACK され、リンクがローカルであるインターフェイス上の任意の IP アドレス。 つまり、IF_TYPE_SOFTWARE_LOOPBACK タイプのインターフェイス上のリンク ローカル (169.254.) アドレスとループバック (127.) アドレスは除外されますが、これらのアドレスが別の型のインターフェイスにある場合は除外されません。
DAD 状態の詳細については、IP_DAD_STATE列挙とIP_ADAPTER_UNICAST_ADDRESS構造に関する IP ヘルパーのドキュメントと、MIB_UNICASTIPADDRESS_ROW構造に関する MIB ドキュメントを参照してください。 インターフェイスの種類の詳細については、 IP_ADAPTER_ADDRESSES 構造に関する IP ヘルパーのドキュメントと GetAdaptersAddresses 関数と 、MIB_IF_ROW2 構造に関する MIB ドキュメントを参照してください。 スコープ レベルの詳細については、IP_ADAPTER_ADDRESSES構造とSCOPE_LEVEL列挙に関する IP ヘルパーのドキュメントを参照してください。
lpvOutBuffer パラメーターが指す出力バッファーで返されるリストは、SOCKET_ADDRESS_LIST構造体の形式です。
lpvOutBuffer パラメーターで指定された出力バッファーがアドレス一覧を格納するのに十分な大きさでない場合は、この IOCTL の結果としてSOCKET_ERRORが返され、WSAGetLastError はWSAEFAULT を返します。 この場合、出力バッファーに必要なサイズ (バイト単位) が lpcbBytesReturned パラメーターで返されます。 lpvInBuffer、lpvOutBuffer、または lpcbBytesReturned パラメーターがユーザー アドレス空間の有効な部分に完全に含まれていない場合は、WSAEFAULT エラー コードも返されることに注意してください。
SIO_ADDRESS_LIST_QUERY IOCTL は通常、lpvOverlapped パラメーターを NULL に設定して同期的に呼び出されます。これは、アドレスの一覧が直ちに返されるためです。
メモ Windows プラグ アンド プレイ環境では、アドレスを動的に追加および削除できます。 したがって、アプリケーションは、 SIO_ADDRESS_LIST_QUERY によって返される情報に依存して永続的にすることはできません。 アプリケーションは、重複した I/O または FD_ADDRESS_LIST_CHANGE イベントを介して通知を提供する、SIO_ADDRESS_LIST_CHANGE IOCTL を介してアドレス変更通知に登録できます。 次の一連のアクションを使用して、アプリケーションが常に現在のアドレス一覧情報を持っていることを保証できます。
- SIO_ADDRESS_LIST_CHANGE IOCTL を発行する
- SIO_ADDRESS_LIST_QUERY IOCTL を発行する
- SIO_ADDRESS_LIST_CHANGE IOCTL 呼び出しがアドレス一覧の変更 (重複した I/O またはFD_ADDRESS_LIST_CHANGE イベントの通知) をアプリケーションに通知するたびに、アクションのシーケンス全体を繰り返す必要があります。
Windows Vista 以降用にリリースされた Microsoft Windows Software Development Kit (SDK) では、ヘッダー ファイルのorganizationが変更され、SIO_ADDRESS_LIST_QUERYコントロール コードは Ws2def.h ヘッダー ファイルで定義されています。 Ws2def.h ヘッダー ファイルは Winsock2.h に自動的に含まれるので、直接使用しないでください。