LPWSPJOINLEAF

WSPJoinLeaf 関数は、リーフノードをマルチポイントセッションに参加させ、接続データを交換し、指定されたフロー仕様に基づいて必要なサービス品質を指定します。

エラーが発生しなかった場合、 WSPJoinLeaf は、新しく作成されたマルチポイントソケットの記述子である SOCKET 型の値を返します。それ以外の場合は INVALID_SOCKET が返され、固有のエラーコードが lpErrno に格納されます。

ブロッキングソケットでは、戻り値は参加操作の成功または失敗を示します。

非ブロッキングソケットでは、有効なソケット記述子が返されることにより、参加操作が正常に開始されたことが示されます。その後、参加操作が成功または失敗のいずれで完了した場合でも、FD_CONNECT 通知が行われます。FD_CONNECT に関連付けられたエラーコードが、 WSPJoinLeaf の成功または失敗を示します。

また、マルチポイントセッションへの参加試行が完了するまで、同じソケットに対する以降の WSPJoinLeaf の呼び出しはすべてエラーコード WSAEALREADY で失敗します。 WSPJoinLeaf が正常に完了した後は、以降の試行は通常エラーコード WSAEISCONN で失敗します。WSAEISCONN の規則の例外は、ルート起動の参加を許可する c_root ソケットで発生します。その場合、先行する WSPJoinLeaf の完了後に別の参加を開始できます。

返されたエラーコードがマルチポイントセッションへの参加試行の失敗 (つまり WSAECONNREFUSED、WSAENETUNREACH、WSAETIMEDOUT) を示している場合、Windows Sockets SPI クライアントは同じソケットに対して WSPJoinLeaf を再度呼び出すことができます。

この関数は、リーフノードをマルチポイントセッションに参加させるとともに、セッションへの参加時に発生するその他の付随的な処理を行うために使用します。ソケット s がバインドされていない場合は、システムによってローカルの関連付けに一意の値が割り当てられ、そのソケットはバインド済みとしてマークされます。

WSPJoinLeaf は、(LPWSPAccept と同様に) ソケット記述子を返す点と、追加の dwFlags パラメーターを持つ点を除き、 LPWSPConnect と同じパラメーターおよびセマンティクスを持ちます。この関数の入力パラメーター s に使用できるのは、適切なマルチポイントフラグを設定して LPWSPSocket で作成されたマルチポイントソケットだけです。ソケットが非ブロッキングモードの場合、返されたソケット記述子は、元のソケット s で対応する FD_CONNECT 通知を受け取るまで使用できません。ただし、保留中の参加操作をキャンセルするために、この新しいソケット記述子に対して closesocket を呼び出すことはできます。マルチポイントセッションのルートノードは、複数のリーフノードを追加するために WSPJoinLeaf を 1 回以上呼び出すことができますが、同時に未処理にできるマルチポイント接続要求は最大 1 つです。詳細については Protocol-Independent Multicast and Multipoint in the SPI を参照してください。

非ブロッキングソケットでは、接続を直ちに完了できないことがよくあります。その場合、この関数はまだ使用できないソケット記述子を返し、処理はそのまま続行されます。この場合、関数は実質的に「開始に成功した」ことを示しているため、WSAEWOULDBLOCK のようなエラーコードは返されません。最終的な成功または失敗が判明すると、クライアントが元のソケット s に対して通知をどのように登録したかに応じて、 LPWSPAsyncSelect または LPWSPEventSelect を通じて報告されます。いずれの場合も通知は FD_CONNECT で伝えられ、FD_CONNECT に関連付けられたエラーコードが、成功または失敗の具体的な理由を示します。なお、 LPWSPSelect を使用して WSPJoinLeaf の完了通知を検出することはできません。

WSPJoinLeaf が返すソケット記述子は、入力のソケット記述子 s が c_root と c_leaf のどちらであるかによって異なります。c_root ソケットとともに使用した場合、name パラメーターは追加する特定のリーフノードを指定し、返されるソケット記述子は新しく追加されたリーフノードに対応する c_leaf ソケットになります。( Descriptor Allocation のセクションで説明されているとおり、新しいソケット記述子を割り当てる際、IFS プロバイダーは WPUModifyIFSHandle を、非 IFS プロバイダーは WPUCreateSocketHandle を呼び出す必要があります。) 新しく作成されたソケットは、 LPWSPAsyncSelect または LPWSPEventSelect で登録された非同期イベントを含め、s と同じプロパティを持ちます。このソケットはマルチポイントデータの交換に使用することを意図したものではなく、特定の c_leaf との間に存在する接続についてのネットワークイベント通知 (FD_CLOSE など) を受け取るために使用します。マルチポイントの実装によっては、このソケットをルートと個々のリーフノードとの間の「サイドチャット」に使用できるようにしているものもあります。対応するリーフノードが LPWSPCloseSocket を呼び出してマルチポイントセッションから離脱すると、このソケットで FD_CLOSE 通知を受け取ります。対称的に、 WSPJoinLeaf から返された c_leaf ソケットに対して WSPCloseSocket を呼び出すと、対応するリーフノードのソケットが FD_CLOSE 通知を受け取ります。

c_leaf ソケットを指定して WSPJoinLeaf を呼び出した場合、name パラメーターにはルートノードのアドレス (ルート付き制御方式の場合)、または既存のマルチポイントセッションのアドレス (ルートなし制御方式の場合) を格納し、返されるソケット記述子は入力のソケット記述子と同じものになります。つまり、新しいソケット記述子は割り当てられません。ルート付き制御方式では、ルートアプリケーションは LPWSPListen を呼び出して c_root ソケットをリッスンモードにします。リーフノードがマルチポイントセッションへの参加を要求すると、標準の FD_ACCEPT 通知が配信されます。ルートアプリケーションは、通常どおり LPWSPAccept 関数を使用して新しいリーフノードを受け入れます。 WSPAccept から返される値も、 WSPJoinLeaf から返されるものと同じく c_leaf ソケット記述子です。ルート起動とリーフ起動の両方の参加を許可するマルチポイント方式に対応するため、既にリッスンモードになっている c_root ソケットを WSPJoinLeaf の入力として使用することも認められています。

Windows Sockets SPI クライアントは、指定するパラメーターが直接的または間接的に指すメモリ領域を割り当てる責任を負います。

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

マルチポイントセッションの確立時に、Windows Sockets SPI クライアントは lpSQOS パラメーターを使用して、SIO_SET_QOS オペコードを指定した LPWSPIoctl によってそのソケットに対して以前に行われた QoS の指定を上書きできます。

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

dwFlags パラメーターは、ソケットが送信側としてのみ動作するか (JL_SENDER_ONLY)、受信側としてのみ動作するか (JL_RECEIVER_ONLY)、またはその両方として動作するか (JL_BOTH) を示すために使用します。