WSAConnect 関数 (winsock2.h)

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
);

Parameters

[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 の QOS 構造体へのポインター。

[in] lpGQOS

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

戻り値

エラーが発生しない場合、 WSAConnect はゼロを返します。それ以外の場合は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	ソケット 1.1 呼び出しWindows (ブロック) は、WSACancelBlockingCall によって取り消されました。
WSAEINPROGRESS	ブロックしている Windows ソケット 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 型など) の場合、アクティブな接続は 、名前 (ソケットの名前空間内のアドレス) を使用して外部ホストに対して開始されます。詳細な説明については、バインドを参照してください。この呼び出しが正常に完了すると、ソケットはデータを送受信する準備が整います。名前構造体のアドレスパラメーターがすべてゼロの場合、WSAConnect はエラー WSAEADDRNOTAVAIL を返します。アクティブな接続を再接続しようとすると、エラーコード WSAEISCONN で失敗します。

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

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

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

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

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

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

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

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

lpCallerData が NULL の場合、ユーザーデータはピアに渡されません。 lpCalleeData は、WSABUF 構造体の接続確立の一部として他のソケットから返されるユーザーデータを格納する結果パラメーターです。 lpCalleeData パラメーターが指す WSABUF 構造体の len メンバーには、最初に、WSABUF 構造体の buf メンバーに対してアプリケーションによって割り当てられたバッファーの長さが含まれています。 lpCalleeData パラメーターが指す WSABUF 構造体の len メンバーは、ユーザー・データが戻されていない場合はゼロに設定されます。 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 呼び出しを中断した別のブロック Winsock 呼び出しを APC 内で発行すると、未定義の動作が発生し、Winsock クライアントが試行してはなりません。

Windows Phone 8: この関数は、Windows Phone 8 以降の Windows Phone ストアアプリでサポートされています。

Windows 8.1 および Windows Server 2012 R2: この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストアアプリでサポートされています。

Requirements

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