WSAConnect

WSAConnect 関数は、別のソケットアプリケーションへの接続を確立し、接続データを交換し、指定された FLOWSPEC 構造体に基づいて必要な QoS を指定する。

WSAConnect s, name, namelen, lpCallerData, lpCalleeData, lpSQOS, lpGQOS

s : [int] 未接続のソケットを識別するディスクリプタ。
name : [var] 接続先アドレスを指定する sockaddr 構造体へのポインタ。IPv4 では、sockaddr にアドレスファミリとして AF_INET、接続先の IPv4 アドレス、接続先のポートが含まれる。IPv6 では、sockaddr 構造体にアドレスファミリとして AF_INET6、接続先の IPv6 アドレス、接続先のポートが含まれ、追加のフロー情報やスコープ ID 情報を含むこともある。
namelen : [int] name パラメータが指す sockaddr 構造体の長さ (バイト単位)。
lpCallerData : [var] 接続確立中に相手側ソケットに転送されるユーザーデータへのポインタ。備考を参照。
lpCalleeData : [var] 接続確立中に相手側ソケットから返されるユーザーデータへのポインタ。備考を参照。
lpSQOS : [var] ソケット s 用の FLOWSPEC 構造体への、各方向に 1 つずつのポインタ。
lpGQOS : [var] 将来ソケットグループで使用するために予約されている。該当する場合、ソケットグループ用の FLOWSPEC 構造体へのポインタ。このパラメータは NULL にすべきである。

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

解説

WSAConnect 関数は、別のソケットアプリケーションへの接続を確立し、接続データを交換し、指定された FLOWSPEC
構造体に基づいて必要な QoS を指定する。

[戻り値]
エラーがない場合、WSAConnect はゼロを返す。そうでない場合は SOCKET_ERROR を返し、WSAGetLastError
を呼び出すことで特定のエラーコードを取得できる。ブロッキングソケットでは、戻り値は接続試行の成否を示す。ノンブロッキングソケットでは、接続試行を即座に完了できない。この場合、WSAConnect
は SOCKET_ERROR を返し、WSAGetLastError は WSAEWOULDBLOCK
を返す。そのため、アプリケーションは次のようにできる。
（以下省略）

[備考]
WSAConnect 関数は、指定された接続先への接続を作成し、接続時に発生するその他多数の付随的操作を行うために使用される。ソケット s
がバインドされていない場合、ローカルな結合にシステムが一意な値を割り当て、ソケットはバインド済みとしてマークされる。Windows
Vista 以降を対象とするアプリケーションでは、クライアントアプリケーションの設計を大幅に簡素化する WSAConnectByList
や WSAConnectByName 関数の使用を検討するべきである。接続指向ソケット (たとえば SOCK_STREAM 型)
の場合、name (ソケットの名前空間上のアドレス。詳しくは bind を参照)
を使って外部ホストへのアクティブな接続が開始される。この呼び出しが成功して戻った時点で、ソケットはデータの送受信準備ができている。name
構造体のアドレスパラメータがすべてゼロの場合、WSAConnect はエラー WSAEADDRNOTAVAIL
を返す。既にアクティブな接続を再接続しようとするとエラーコード WSAEISCONN で失敗する。注 ソケットをオープンして
setsockopt を呼び出し、その後 sendto を呼び出すと、Windows Sockets は暗黙の bind
関数呼び出しを行う。接続指向のノンブロッキングソケットでは、接続を即時に完了できないことが多い。そのような場合、この関数はエラー
WSAEWOULDBLOCK
を返す。しかし操作は継続する。成功または失敗の結果が判明したら、クライアントが通知を登録した方法に応じていくつかの形で報告される。クライアントが
select を使っていれば、成功は writefds 集合で、失敗は exceptfds 集合で報告される。クライアントが
WSAAsyncSelect や WSAEventSelect を使っていれば、FD_CONNECT で通知され、FD_CONNECT
に付随するエラーコードが成功か特定の失敗理由かを示す。コネクションレスソケット (たとえば SOCK_DGRAM 型)
の場合、WSAConnect の操作は単に既定の接続先アドレスを設定するだけで、ソケットはその後の接続指向の送受信操作
(send、WSASend、recv、WSARecv)
で利用できるようになる。指定した接続先アドレス以外から受信したデータグラムは破棄される。name 構造体全体がすべてゼロ
(アドレスパラメータだけでなく)
の場合、ソケットは切断される。以後、既定のリモートアドレスは不定になるため、send、WSASend、recv、WSARecv
呼び出しはエラーコード WSAENOTCONN を返すようになる。ただし
sendto、WSASendTo、recvfrom、WSARecvFrom
は引き続き使用できる。ソケットが既に接続済みでも、WSAConnect をもう一度呼び出すだけで既定の接続先を変更できる。name
が前回の WSAConnect と異なる場合、受信待ちキューに入っているデータグラムは破棄される。コネクションレスソケットでは、name
はブロードキャストアドレスを含む任意の有効なアドレスを指定できる。ただし、ブロードキャストアドレスに接続するには、ソケットで
setsockopt SO_BROADCAST を有効にする必要がある。そうでなければ WSAConnect はエラーコード
WSAEACCES
で失敗する。コネクションレスソケットでは、ユーザー間データの交換はできず、該当するパラメータは黙って無視される。アプリケーションは、自身が指定するパラメータが直接的または間接的に指すメモリ領域の確保に責任を持つ。lpCallerData
パラメータには、接続要求とともに送信される任意のユーザーデータ (接続データと呼ばれる)
へのポインタを格納する。これは通常のネットワークデータストリームには含まれない追加データで、接続確立のためのネットワーク要求とともに送信される。このオプションは
DECNet、OSI TP4 などのレガシープロトコルで使用される。注 Windows の TCP/IP
プロトコルでは接続データはサポートされない。接続データは、生のソケット上の ATM (RAWWAN) でのみサポートされる。
lpCallerData が NULL の場合、相手側にユーザーデータは渡されない。lpCalleeData
は結果パラメータであり、接続確立の一環として相手側ソケットから渡されたユーザーデータを WSABUF
構造体の中に格納する。lpCalleeData パラメータが指す WSABUF 構造体の len
メンバには、初期値としてアプリケーションが buf
メンバ用に確保したバッファの長さを設定しておく。ユーザーデータが返されなかった場合、WSABUF 構造体の len
メンバにはゼロが設定される。lpCalleeData 情報は接続操作が完了した時点で有効になる。ブロッキングソケットでは接続操作は
WSAConnect 関数が戻った時点で完了する。ノンブロッキングソケットでは、FD_CONNECT
通知が発生した後に完了する。lpCalleeData が NULL
の場合、ユーザーデータは返されない。ユーザーデータの正確な形式は、ソケットが属するアドレスファミリに固有である。接続時、アプリケーションは
lpSQOS と lpGQOS パラメータを使って、WSAIoctl を SIO_SET_QOS または
SIO_SET_GROUP_QOS オペコードで呼び出して以前に指定した QoS 仕様をオーバーライドできる。lpSQOS
パラメータはソケット s 用の FLOWSPEC 構造体 (各方向に 1 つずつ)
と、それに続くプロバイダ固有のパラメータを指定する。関連するトランスポートプロバイダ全般もしくは特定のソケット種別が QoS
要求を満たせない場合、以下に示すようにエラーが返される。一方向ソケットに対しては、該当しない方向の送受信フロー仕様値はそれぞれ無視される。プロバイダ固有パラメータを指定しない場合、lpCalleeData
パラメータが指す WSABUF 構造体の buf と len メンバはそれぞれ NULL とゼロに設定すべきである。lpSQOS
パラメータが NULL の場合、アプリケーションが指定する QoS がないことを示す。将来ソケットグループで使用するために予約されている
lpGQOS は、該当する場合ソケットグループ用の FLOWSPEC 構造体 (各方向に 1 つずつ)
と、それに続くプロバイダ固有のパラメータを指定する。プロバイダ固有パラメータを指定しない場合、lpCalleeData パラメータが指す
WSABUF 構造体の buf と len メンバはそれぞれ NULL とゼロに設定すべきである。lpGQOS が NULL
の場合、アプリケーションが指定するグループ QoS がないことを示す。このパラメータは、s
がソケットグループの作成元でない場合は無視される。接続済みソケットが何らかの理由でクローズされた場合、それらを破棄して再生成すべきである。接続済みソケットで何かがおかしくなった場合、安定した状態に戻るためにアプリケーションは必要なソケットを破棄して再生成しなければならないと想定するのが最も安全である。注
WSAConnect のようなブロッキング Winsock 呼び出しを発行する際、呼び出しが完了する前に Winsock
がネットワークイベントを待つ必要がある場合がある。この状況では Winsock は警告待機を行い、同一スレッドにスケジュールされた APC
(非同期プロシージャコール) によって中断されることがある。同一スレッド上で進行中のブロッキング Winsock 呼び出しを中断した
APC の内部でさらに別のブロッキング Winsock 呼び出しを発行すると動作は未定義となり、Winsock
クライアントは決してそれを試みてはならない。Windows Phone 8: この関数は Windows Phone 8 以降の
Windows Phone ストアアプリでサポートされる。Windows 8.1 および Windows Server 2012 R2:
この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストアアプリでサポートされる。

情報