LPWSPCONNECT

LPWSPConnect 関数は、ピアへの接続を確立し、接続データを交換し、指定されたフロー仕様に基づいて必要なサービス品質を指定します。

エラーが発生しなかった場合、LPWSPConnect は 0 を返します。それ以外の場合は SOCKET_ERROR を返し、具体的なエラーコードは lpErrno で取得できます。

ブロッキングソケットでは、戻り値は接続試行の成否を示します。返されたエラーコードが接続試行の失敗を示している場合(すなわち WSAECONNREFUSED、WSAENETUNREACH、WSAETIMEDOUT)、Winsock SPI クライアントは同じソケットに対して再度 LPWSPConnect を呼び出すことができます。

この関数は、指定された宛先への接続を作成するとともに、接続時に行われるその他のいくつかの付随的な処理も実行します。ソケット s がバインドされていない場合、システムによってローカルの関連付けに一意の値が割り当てられ、ソケットはバインド済みとしてマークされます。

コネクション指向のソケット(たとえば SOCK_STREAM 型)では、name(ソケットの名前空間におけるアドレス)を使用して、指定されたホストへのアクティブな接続が開始されます。詳細な説明については、LPWSPBind を参照してください。この呼び出しが正常に完了すると、ソケットはデータの送受信が可能な状態になります。name 構造体のアドレスメンバーがすべて 0 の場合、LPWSPConnect はエラー WSAEADDRNOTAVAIL を返します。アクティブな接続に対して再接続を試みた場合は、エラーコード WSAEISCONN で失敗します。

コネクション指向のノンブロッキングソケットでは、接続を直ちに完了できないことがよくあります。その場合、この関数はエラー WSAEWOULDBLOCK を伴って戻りますが、処理は継続されます。成功または失敗の結果が判明したときの報告方法は、クライアントが通知をどのように登録したかによっていくつかの形があります。クライアントが LPWSPSelect を使用している場合、成功は writefds セットで、失敗は exceptfds セットで報告されます。クライアントが LPWSPAsyncSelect または LPWSPEventSelect を使用している場合、通知は FD_CONNECT で知らされ、FD_CONNECT に関連付けられたエラーコードが成功、または失敗の具体的な理由を示します。

コネクションレスソケット(たとえば SOCK_DGRAM 型)の場合、LPWSPConnect が行う処理は既定の宛先アドレスを設定することであり、これによりソケットは以降のコネクション指向の送受信処理(LPWSPSend、LPWSPRecv)で使用できるようになります。指定した宛先アドレス以外から受信したデータグラムはすべて破棄されます。name 構造体のアドレスメンバーがすべて 0 の場合、ソケットは切断されます。既定のリモートアドレスが不定になるため、LPWSPSend と LPWSPRecv の呼び出しはエラーコード WSAENOTCONN を返します。ただし、LPWSPSendTo と LPWSPRecvFrom は引き続き使用できます。既定の宛先は、ソケットが既に接続されている場合でも、単に LPWSPConnect を再度呼び出すことで変更できます。name が前回の LPWSPConnect と異なる場合、受信用にキューイングされていたデータグラムはすべて破棄されます。

コネクションレスソケットでは、name にブロードキャストアドレスを含む任意の有効なアドレスを指定できます。ただし、ブロードキャストアドレスに接続するには、ソケットで WSPSetSockOpt の SO_BROADCAST が有効になっている必要があります。そうでない場合、LPWSPConnect はエラーコード WSAEACCES で失敗します。

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

Winsock SPI クライアントは、自身が指定するパラメーターが直接または間接的に指すメモリ領域の割り当てに責任を持ちます。

lpCallerData は値パラメーターで、接続要求とともに送信するユーザーデータを格納します。lpCallerData が null の場合、ユーザーデータはピアに渡されません。lpCalleeData は結果パラメーターで、接続確立の一環としてピアから返されたユーザーデータを参照します。lpCalleeData->len には、最初に Winsock SPI クライアントが割り当てて lpCalleeData->buf が指すバッファーの長さが格納されます。ユーザーデータが返されなかった場合、lpCalleeData->len は 0 に設定されます。lpCalleeData の情報は、接続処理が完了した時点で有効になります。ブロッキングソケットの場合は LPWSPConnect 関数が戻った時点、ノンブロッキングソケットの場合は FD_CONNECT 通知が発生した後になります。lpCalleeData が null の場合、ユーザーデータは返されません。ユーザーデータの正確な形式は、ソケットが属するアドレスファミリ、または関係するアプリケーションに固有です。

接続時に、Winsock SPI クライアントは lpSQOS パラメーターを使用して、LPWSPIoctl に SIO_SET_QOS オペコードを指定してそのソケットに対して以前に行った QoS の指定を上書きできます。

lpSQOS は、ソケット s のフロー仕様を各方向に 1 つずつ指定し、その後にプロバイダー固有の追加パラメーターが続きます。関連付けられたトランスポートプロバイダー全般、または特定の種類のソケットが QoS 要求に応じられない場合は、以下に示すエラーが返されます。単方向のソケットでは、送信側または受信側のフロー仕様の値はそれぞれ無視されます。プロバイダー固有のパラメーターを指定しない場合、lpSQOS->ProviderSpecific の buf メンバーと len メンバーは、それぞれ null と 0 に設定してください。lpSQOS が null の場合は、アプリケーションがサービス品質を指定していないことを示します。