WSAConnect 関数 (winsock2.h)

[アーティクル]
08/27/2023

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

構文

int WSAAPI WSAConnect(
  [in]  SOCKET         s,
  [in]  const sockaddr *name,
  [in]  int            namelen,
  [in]  LPWSABUF       lpCallerData,
  [out] LPWSABUF       lpCalleeData,
  [in]  LPQOS          lpSQOS,
  [in]  LPQOS          lpGQOS
);

パラメーター

[in] s

接続されていないソケットを識別する記述子。

[in] name

接続先のアドレスを指定する sockaddr 構造体へのポインター。 IPv4 の場合、 sockaddr には、アドレスファミリ、宛先 IPv4 アドレス、および宛先ポートの AF_INET が含まれます。 IPv6 の場合、 sockaddr 構造体には、アドレスファミリの AF_INET6 、宛先 IPv6 アドレス、宛先ポート、および追加のフローとスコープ ID 情報が含まれる場合があります。

[in] namelen

name パラメーターが指す sockaddr 構造体の長さ (バイト単位)。

[in] lpCallerData

接続の確立中に他のソケットに転送されるユーザーデータへのポインター。「解説」を参照してください。

[out] lpCalleeData

接続の確立中に他のソケットから転送されるユーザーデータへのポインター。「解説」を参照してください。

[in] lpSQOS

ソケット s の FLOWSPEC 構造体へのポインター。方向ごとに 1 つ。

[in] lpGQOS

ソケットグループで今後使用するために予約されています。ソケットグループの FLOWSPEC 構造体へのポインター (該当する場合)。このパラメーターは NULL にする必要があります。

戻り値

エラーが発生しない場合、 WSAConnect は 0 を返します。それ以外の場合はSOCKET_ERRORを返し、 WSAGetLastError を呼び出すことで特定のエラーコードを取得できます。ブロッキングソケットでは、戻り値は接続試行の成功または失敗を示します。

非ブロッキングソケットでは、接続の試行をすぐに完了することはできません。この場合、 WSAConnect はSOCKET_ERRORを返し、 WSAGetLastError は WSAEWOULDBLOCK を返します。そのため、アプリケーションは次の可能性があります。

select を使用して、ソケットが書き込み可能かどうかを確認して、接続要求の完了を確認します。
アプリケーションで WSAAsyncSelect を使用して接続イベントへの関心を示している場合、接続操作が完了した (成功したかどうか) と、アプリケーションはFD_CONNECT通知を受け取ります。
アプリケーションが WSAEventSelect を使用して接続イベントに関心があることを示している場合、接続操作が完了すると (成功した場合は、そうでない場合)、関連付けられたイベントオブジェクトが通知されます。

非ブロッキングソケットの場合、接続試行が完了するまで、同じソケット上の WSAConnect への後続のすべての呼び出しは、エラーコード WSAEALREADY で失敗します。

戻りエラーコードが接続試行に失敗したことを示す場合 (つまり、 WSAECONNREFUSED、 WSAENETUNREACH、 WSAETIMEDOUT) アプリケーションは、同じソケットに対して WSAConnect を再度呼び出すことができます。

エラーコード	意味
WSANOTINITIALIZED	この関数を使用する前に、 WSAStartup 呼び出しが正常に行われる必要があります。
WSAENETDOWN	ネットワークサブシステムが失敗しました。
WSAEADDRINUSE	ソケットのローカルアドレスは既に使用されており、SO_REUSEADDRでアドレスを再利用できるようにソケットがマークされていません。このエラーは通常、バインドの実行中に発生しますが、バインド関数が部分的なワイルドカードアドレス (ADDR_ANYを含む) で動作し、この関数の時点で特定のアドレスを "コミット" する必要がある場合は、この関数まで遅延する可能性があります。
WSAEINTR	(ブロッキング) Windows Socket 1.1 呼び出しは、WSACancelBlockingCall を介して取り消されました。
WSAEINPROGRESS	ブロックしている Windows Sockets 1.1 呼び出しが進行中であるか、サービスプロバイダーがコールバック関数を処理しています。
WSAEALREADY	指定したソケットで非ブロッキング接続または WSAConnect 呼び出しが進行中です。
WSAEADDRNOTAVAIL	リモートアドレスが有効なアドレス (ADDR_ANY など) ではありません。
WSAEAFNOSUPPORT	指定されたファミリーのアドレスをこのソケットと共に使用することはできません。
WSAECONNREFUSED	接続の試行が拒否されました。
WSAEFAULT	name または namelen パラメーターがユーザーアドレス空間の有効な部分ではない、namelen パラメーターが小さすぎる、lpCalleeData、lpSQOS、lpGQOS のバッファー長が小さすぎる、または lpCallerData のバッファー長が大きすぎる。
WSAEINVAL	パラメーター s がリッスンソケットであるか、指定された宛先アドレスが、ソケットが属する制約付きグループのアドレスと一致しないか、 lpGQOS パラメーターが NULL ではありません。
WSAEISCONN	ソケットは既に接続されています (接続指向ソケットのみ)。
WSAENETUNREACH	現在このホストからネットワークには到達できません。
WSAEHOSTUNREACH	到達できないホストに対してソケット操作を実行しようとしました。
WSAENOBUFS	バッファーに空き領域がありません。ソケットを接続できません。
WSAENOTSOCK	記述子はソケットではありません。
WSAEOPNOTSUPP	lpSQOS および lpGQOS で指定された FLOWSPEC 構造体を満たすことはできません。
WSAEPROTONOSUPPORT	lpCallerData パラメーターは、サービスプロバイダーではサポートされていません。
WSAETIMEDOUT	接続を確立せずに、接続がタイムアウトしました。
WSAEWOULDBLOCK	ソケットは非ブロッキングとしてマークされ、接続をすぐに完了することはできません。
WSAEACCES	setsockopt SO_BROADCASTが有効になっていないため、データグラムソケットをブロードキャストアドレスに接続できませんでした。

注釈

WSAConnect 関数は、指定した宛先への接続を作成し、接続時に発生する他の多くの補助操作を実行するために使用されます。ソケット s が非連結の場合、一意の値はシステムによってローカル関連付けに割り当てられ、ソケットはバインド済みとしてマークされます。

Windows Vista 以降を対象とするアプリケーションの場合は、クライアントアプリケーションの設計を大幅に簡略化する WSAConnectByList または WSAConnectByName 関数の使用を検討してください。

接続指向ソケット (例: SOCK_STREAM) の場合、アクティブな接続は 、名前 を使用して外部ホストに対して開始されます (ソケットの名前空間内のアドレス。詳細な説明については、「 bind」を参照してください)。この呼び出しが正常に完了すると、ソケットはデータを送受信する準備が整います。名前構造体の address パラメーターがすべてゼロの場合、WSAConnect はエラー WSAEADDRNOTAVAIL を返します。アクティブな接続を再接続しようとすると、エラーコード WSAEISCONN で失敗します。

メモソケットが開かれた場合、 setsockopt 呼び出しが行われ、 sendto 呼び出しが行われると、Windows ソケットは暗黙的なバインド関数呼び出しを実行します。

接続指向の非ブロッキングソケットの場合、多くの場合、接続をすぐに完了することはできません。このような場合、この関数はエラー WSAEWOULDBLOCK を返します。ただし、操作は続行されます。成功または失敗の結果が判明すると、クライアントが通知に登録する方法に応じて、いくつかの方法のいずれかで報告される場合があります。クライアントが select を使用する場合、 writefds セットで成功が報告され、 exceptfds セットで失敗が報告されます。クライアントが WSAAsyncSelect または WSAEventSelect を使用している場合、通知はFD_CONNECTと共に通知され、FD_CONNECTに関連付けられているエラーコードは成功または特定の失敗の理由を示します。

コネクションレスソケット (例: SOCK_DGRAM) の場合、 WSAConnect によって実行される操作は、後続の接続指向の送受信操作 (送信、 WSASend、 recv、 WSARecv) でソケットを使用できるように、既定の宛先アドレスを確立することだけです。指定された宛先アドレス以外のアドレスから受信したデータグラムはすべて破棄されます。名前構造全体が (名前構造体のアドレスパラメーターだけでなく) すべて 0 の場合、ソケットは切断されます。その後、既定のリモートアドレスは不確定になるため、 send、 WSASend、 recv、 および WSARecv 呼び出しはエラーコード WSAENOTCONN を返します。ただし、 sendto、 WSASendTo、 recvfrom、および WSARecvFrom は引き続き使用できます。ソケットが既に接続されている場合でも、 WSAConnect をもう一度呼び出すだけで、既定の宛先を変更できます。前の WSAConnect と名前が異なる場合、受信待ち行列に入っているデータグラムはすべて破棄されます。

コネクションレスソケットの場合、名前はブロードキャストアドレスを含む任意の有効なアドレスを示すことができます。ただし、ブロードキャストアドレスに接続するには、ソケットで setsockopt SO_BROADCASTが有効になっている必要があります。それ以外の場合、 WSAConnect はエラーコード WSAEACCES で失敗します。

コネクションレスソケットでは、ユーザー間データの交換は不可能であり、対応するパラメーターは暗黙的に無視されます。

アプリケーションは、指定されたパラメーターのいずれかによって直接または間接的に指されるメモリ領域を割り当てる役割を担います。

lpCallerData パラメーターには、接続要求 (接続データと呼ばれる) と共に送信されるユーザーデータへのポインターが含まれています。これは、通常のネットワークデータストリーム内ではなく、接続を確立するためのネットワーク要求と共に送信される追加データです。このオプションは、DECNet、OSI TP4 などのレガシプロトコルで使用されます。

メモ接続データは、Windows の TCP/IP プロトコルではサポートされていません。接続データは、生ソケット経由の ATM (RAWWAN) でのみサポートされます。

lpCallerData が NULL の場合、ユーザーデータはピアに渡されません。 lpCalleeData は、WSABUF 構造体の接続確立の一部として他のソケットから返されるユーザーデータを格納する結果パラメーターです。 lpCalleeData パラメーターが指す WSABUF 構造体の len メンバーには、WSABUF 構造体の buf メンバーに対してアプリケーションによって割り当てられたバッファーの長さが最初に含まれています。 lpCalleeData パラメーターが指す WSABUF 構造体の len メンバーは、ユーザーデータが返されない場合は 0 に設定されます。 lpCalleeData 情報は、接続操作が完了したときに有効になります。ソケットをブロックする場合、 WSAConnect 関数が戻ったときに接続操作が完了します。非ブロッキングソケットの場合、完了は、FD_CONNECT通知が発生した後になります。 lpCalleeData が NULL の場合、ユーザーデータは返されません。ユーザーデータの正確な形式は、ソケットが属するアドレスファミリに固有です。

接続時に、アプリケーションは lpSQOS パラメーターと lpGQOS パラメーターを使用して、 WSAIoctl を介してソケットに対して行われた以前のサービス品質仕様を、SIO_SET_QOSまたはSIO_SET_GROUP_QOSオペコードでオーバーライドできます。

lpSQOS パラメーターは、ソケット s の FLOWSPEC 構造体を、各方向に 1 つずつ指定し、その後にプロバイダー固有の追加パラメーターを指定します。関連付けられているトランスポートプロバイダーが一般的であるか、特に特定の種類のソケットがサービスの品質要求を受け入れることができない場合は、次に示すようにエラーが返されます。送信側または受信側のフロー仕様値は、一方向ソケットの場合は、それぞれ無視されます。プロバイダー固有のパラメーターが指定されていない場合は、lpCalleeData パラメーターが指す WSABUF 構造体の buf メンバーと len メンバーをそれぞれ NULL と 0 に設定する必要があります。 lpSQOS パラメーターの NULL 値は、アプリケーションが提供するサービス品質がないことを示します。

ソケットグループ lpGQOS で将来使用するために予約されています。ソケットグループの FLOWSPEC 構造体 (該当する場合)、各方向に 1 つ、その後にプロバイダー固有の追加パラメーターを指定します。プロバイダー固有のパラメーターが指定されていない場合は、lpCalleeData パラメーターが指す WSABUF 構造体の buf メンバーと len メンバーをそれぞれ NULL と 0 に設定する必要があります。 lpGQOS の NULL 値は、アプリケーションが提供するグループのサービス品質がないことを示します。 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 ストアアプリでサポートされています。

要件

要件	値
サポートされている最小のクライアント	Windows 8.1、 Windows Vista [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリのみ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	winsock2.h
Library	Ws2_32.lib
[DLL]	Ws2_32.dll