WSAConnectByList

接続先アドレスの集合 (ホスト名とポート) で表される複数の候補エンドポイントのいずれか 1 つへの接続を確立する。

WSAConnectByList s, SocketAddress, LocalAddressLength, LocalAddress, RemoteAddressLength, RemoteAddress, timeout, Reserved

s : [int] バインドされておらず、未接続のソケットを識別するディスクリプタ。WSAConnect のような接続確立のための他の Winsock 呼び出しと異なり、WSAConnectByList 関数はバインドされていないソケットを必要とする点に注意。
SocketAddress : [var] ピアに接続するための、考えられる接続先アドレスとポートの組を表す SOCKET_ADDRESS_LIST 構造体へのポインタ。SOCKET_ADDRESS_LIST 内の各 SOCKET_ADDRESS 構造体にポート番号を設定するのはアプリケーションの責任である。
LocalAddressLength : [var] 入力時、呼び出し元が用意した LocalAddress バッファのサイズ (バイト単位) へのポインタ。出力時、呼び出しが成功した際にシステムが LocalAddress バッファに格納したローカルアドレス用 SOCKADDR のサイズ (バイト単位) へのポインタ。
LocalAddress : [var] 接続のローカルアドレスを受け取る SOCKADDR 構造体へのポインタ。パラメータのサイズは LocalAddressLength で返されるサイズと完全に一致する。これは getsockname 関数が返すのと同じ情報である。このパラメータは NULL でもよく、その場合 LocalAddressLength パラメータは無視される。
RemoteAddressLength : [var] 入力時、呼び出し元が用意した RemoteAddress バッファのサイズ (バイト単位) へのポインタ。出力時、呼び出しが成功した際にシステムが RemoteAddress バッファに格納したリモートアドレス用 SOCKADDR のサイズ (バイト単位) へのポインタ。
RemoteAddress : [var] 接続のリモートアドレスを受け取る SOCKADDR 構造体へのポインタ。これは getpeername 関数が返すのと同じ情報である。このパラメータは NULL でもよく、その場合 RemoteAddressLength は無視される。
timeout : [var] リモートアプリケーションからの応答を待ってから呼び出しを中止するまでの時間 (ミリ秒)。このパラメータは NULL にすることもでき、その場合 WSAConnectByList は、接続が正常に確立されるか、考えられるすべてのローカル・リモートアドレスペアで接続試行が行われ失敗した後に完了する。
Reserved : [var] 将来の実装のために予約されている。このパラメータは NULL に設定しなければならない。

(プラグイン / モジュール : ws2_32.dll)

解説

接続先アドレスの集合 (ホスト名とポート) で表される複数の候補エンドポイントのいずれか 1 つへの接続を確立する。

[戻り値]
接続が確立された場合、WSAConnectByList は TRUE を返し、呼び出し元がバッファを提供していれば
LocalAddress および RemoteAddress パラメータに値が設定される。呼び出しが失敗した場合は FALSE
を返す。その後、WSAGetLastError を呼び出して拡張エラー情報を取得できる。
（以下省略）

[備考]
WSAConnectByList は WSAConnectByName 関数と似ている。単一のホスト名とサービス名 (ポート)
を取る代わりに、WSAConnectByList はアドレスのリスト (ホストアドレスとポート) を取り、そのうちの 1
つに接続する。WSAConnectByList
関数は、アプリケーションが候補ノードのリストから接続可能な任意のノードに接続する必要があるピアツーピアコラボレーションシナリオをサポートするよう設計されている。WSAConnectByList
は IPv6 と IPv4
の両バージョンに対応する。考えられる接続先の集合は、アドレスのリストとして呼び出し元が提供する。WSAConnectByList
は、単に考えられる複数の接続先アドレスのいずれかへの接続を試みるだけではない。具体的には、呼び出し元から渡されたすべてのリモートアドレスとすべてのローカルアドレスを取り、成功の可能性が最も高いアドレスペアから順に接続を試みる。これにより、WSAConnectByList
は接続が可能な場合は必ず接続を確立するだけでなく、接続確立までの時間も最小化する。呼び出し元は LocalAddress および
RemoteAddress のバッファと長さを指定して、接続が正常に確立されたローカル・リモートアドレスを受け取れる。timeout
パラメータにより、接続確立に費やす時間を制限できる。内部的には WSAConnectByList は複数の操作 (接続試行)
を実行する。各操作の合間にタイムアウトを超過していないかを確認し、超過していれば呼び出しを中止する。個別の操作 (connect)
がタイムアウト超過時点で中断されるわけではないため、WSAConnectByList 呼び出しは timeout
パラメータで指定した値より長くかかってタイムアウトすることがある点に注意。WSAConnectByList には制約がある:
SOCK_STREAM のような接続指向ソケットでのみ動作する。オーバーラップ I/O
やノンブロッキング動作はサポートしない。ソケットがノンブロッキングモードであっても WSAConnectByList
はブロックする。WSAConnectByList は、呼び出し元から渡された各種アドレスに対して 1
つずつ接続を試みる。これらの接続試行はそれぞれ異なるエラーコードで失敗する可能性がある。返せるエラーコードは 1
つだけなので、返される値は最後の接続試行のエラーコードとなる。IPv6 と IPv4
の両方のアドレスを関数が受け付ける単一のアドレスリストで渡せるようにするには、関数呼び出し前に次の手順を踏む必要がある。
（以下省略）

情報