WSAJoinLeaf

WSAJoinLeaf 関数は、リーフノードをマルチポイントセッションに参加させ、接続データを交換し、指定された FLOWSPEC 構造体に基づいて必要な QoS を指定する。

WSAJoinLeaf s, name, namelen, lpCallerData, lpCalleeData, lpSQOS, lpGQOS, dwFlags

s : [int] マルチポイントソケットを識別する記述子。
name : [var] このソケットを参加させるピアの名前。
namelen : [int] name の長さ (バイト単位)。
lpCallerData : [var] マルチポイントセッション確立時にピアへ転送されるユーザーデータへのポインタ。
lpCalleeData : [var] マルチポイントセッション確立時にピアから返されるユーザーデータへのポインタ。
lpSQOS : [var] ソケット s 用の FLOWSPEC 構造体へのポインタ。方向ごとに 1 つずつ指定する。
lpGQOS : [var] 将来のソケットグループ用に予約されている。ソケットグループ用の FLOWSPEC 構造体へのポインタ (該当する場合)。
dwFlags : [int] ソケットが送信側 (JL_SENDER_ONLY)、受信側 (JL_RECEIVER_ONLY)、またはその両方 (JL_BOTH) として振る舞うことを示すフラグ。

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

解説

WSAJoinLeaf 関数は、リーフノードをマルチポイントセッションに参加させ、接続データを交換し、指定された FLOWSPEC
構造体に基づいて必要な QoS を指定する。

[戻り値]
エラーが発生しない場合、WSAJoinLeaf は新しく作成されたマルチポイントソケットの記述子となる SOCKET
型の値を返す。そうでない場合は INVALID_SOCKET が返され、WSAGetLastError
を呼び出して特定のエラーコードを取得できる。ブロッキングソケットでは戻り値は join
操作の成否を示す。非ブロッキングソケットでは、有効なソケット記述子が返された時点で join
操作が正常に開始されたことを示す。その後、join 操作が成功か失敗で完了したかを、元のソケット s に対する FD_CONNECT
通知で知ることができる。アプリケーションは WSAAsyncSelect または WSAEventSelect で FD_CONNECT
イベントに対する通知を登録し、関連するエラーコードを調べて join 操作の成否を判断しなければならない。join
操作の完了を検出するために select 関数を使うことはできない。また、マルチポイントセッションの join
試行が完了するまで、同じソケットに対する以降の WSAJoinLeaf 呼び出しはすべて WSAEALREADY
で失敗する。WSAJoinLeaf 操作が正常に完了した後の以降の呼び出しは通常 WSAEISCONN
で失敗する。ルート起動の参加を許容する c_root ソケットではこの例外があり、先行する WSAJoinLeaf が完了した後に別の
join を開始してもよい。戻り値がマルチポイントセッション参加の失敗を示している場合
(WSAECONNREFUSED、WSAENETUNREACH、WSAETIMEDOUT
など)、アプリケーションは同じソケットに対して再度 WSAJoinLeaf を呼び出せる。
このドキュメントは省略されている。

[備考]
WSAJoinLeaf
関数は、リーフノードをマルチポイントセッションに参加させるとともに、セッション参加時に発生するその他いくつかの補助的な処理を行う。ソケット
s
がバインドされていない場合、システムが一意な値をローカル関連付けに割り当て、ソケットはバインド済みとしてマークされる。WSAJoinLeaf
関数は、ソケット記述子を返す点 (WSAAccept と同様) と dwFlags 引数が追加されている点を除き、WSAConnect
と同じ引数およびセマンティクスを持つ。この関数の入力 s には、適切なマルチポイントフラグを立てて WSASocket
で作成したマルチポイントソケットのみを渡せる。返されるソケット記述子は、join
操作が完了するまでは利用できない。たとえばソケットが非ブロッキングモードにある場合、元のソケット s に対する
WSAAsyncSelect または WSAEventSelect で対応する FD_CONNECT
通知を受信した後に利用可能となる。ただし、この新しいソケット記述子に対して closesocket を呼び出して、保留中の join
操作をキャンセルすることはできる。マルチポイントセッションのルートアプリケーションは、複数のリーフノードを追加するために
WSAJoinLeaf を繰り返し呼び出してもよいが、保留中のマルチポイント接続要求は同時に最大 1 つまでである。詳しくは
Multipoint and Multicast Semantics
を参照。非ブロッキングソケットでは、接続を即座に完了できないことが多い。その場合、本関数はまだ使用不能なソケット記述子を返し、処理は続行される。このとき
WSAEWOULDBLOCK
のようなエラーコードは返されない。関数は正常に開始された旨を返したことになるからだ。最終的な成否は、クライアントが元のソケット s
に対して WSAAsyncSelect または WSAEventSelect のどちらで通知を登録したかによって通知される。いずれの場合も
FD_CONNECT で通知され、それに付随するエラーコードが成功か失敗の具体的理由を示す。WSAJoinLeaf
の完了通知を検出するために select 関数を使うことはできない。WSAJoinLeaf が返すソケット記述子は、入力ソケット s が
c_root か c_leaf かによって異なる。c_root ソケットに対して使用した場合、name
引数は追加するリーフノードを指定し、返されるソケット記述子は新規追加されたリーフノードに対応する c_leaf
ソケットとなる。新しく作られたソケットは、WSAAsyncSelect や WSAEventSelect で登録された非同期イベントを含め
s と同じプロパティを持つ。これはマルチポイントデータ交換ではなく、その特定の c_leaf に対するネットワークイベント通知
(FD_CLOSE など)
を受け取るために使う。マルチポイント実装によっては、ルートと個々のリーフノード間のサイドチャットにこのソケットを使うことを許可するものもある。対応するリーフノードが
closesocket を呼び出してマルチポイントセッションから離脱すると、このソケットに対して FD_CLOSE
通知が届く。対称的に、WSAJoinLeaf から返された c_leaf ソケットに対して closesocket
を呼ぶと、対応するリーフノード側のソケットは FD_CLOSE 通知を受け取る。c_leaf ソケットで WSAJoinLeaf
を呼び出した場合、name 引数はルートアプリケーション (ルート制御方式) または既存のマルチポイントセッション (非ルート制御方式)
のアドレスを含み、返されるソケット記述子は入力ソケット記述子と同じである。言い換えると、新しいソケット記述子は割り当てられない。ルート制御方式では、ルートアプリケーションは
listen 呼び出しで c_root ソケットをリスンモードに置く。リーフノードがセッションへの参加を要求すると、通常の
FD_ACCEPT 通知が配信される。ルートアプリケーションは通常の accept または WSAAccept
関数で新しいリーフノードを受け入れる。accept および WSAAccept の戻り値も、WSAJoinLeaf
から返されるものと同様の c_leaf
ソケット記述子である。ルート起動の参加とリーフ起動の参加の両方を許容するマルチポイント方式に対応するため、既にリスンモードの c_root
ソケットを WSAJoinLeaf
の入力として使用することも許される。引数によって直接または間接に指し示されるメモリ領域の確保は、呼び出し元の責任である。lpCallerData
は値引数で、マルチポイントセッション参加要求と一緒に送信されるユーザーデータを含む。lpCallerData が NULL
の場合、ユーザーデータはピアへ渡されない。lpCalleeData
は結果引数で、マルチポイントセッション確立の一部としてピアから返されるユーザーデータを格納する。lpCalleeData が指す
WSABUF 構造体の len メンバは、最初はアプリケーションが確保した buf
メンバ先のバッファ長を表す。ユーザーデータが返されなかった場合、len メンバはゼロに設定される。lpCalleeData
情報はマルチポイント join 操作の完了時点で有効になる。ブロッキングソケットでは WSAJoinLeaf
のリターン時、非ブロッキングソケットでは join 完了時 (元のソケット s に対する FD_CONNECT 通知後など)
である。lpCalleeData が NULL
の場合、ユーザーデータは返されない。ユーザーデータの正確な形式は、ソケットが属するアドレスファミリ固有のものである。マルチポイントセッション確立時、アプリケーションは
lpSQOS および lpGQOS 引数を使って、WSAIoctl の SIO_SET_QOS または SIO_SET_GROUP_QOS
オペコードで設定済みの QoS 仕様を上書きできる。lpSQOS 引数は、ソケット s 用の方向ごとの FLOWSPEC
構造体と、それに続く追加のプロバイダ固有引数を指定する。関連トランスポートプロバイダ全般または特定のソケット種別が QoS
要求に応えられない場合は、後述のエラーが返される。単方向ソケットでは、該当しない方向のフロー仕様値は無視される。プロバイダ固有引数を指定しない場合、lpCalleeData
が指す WSABUF 構造体の buf と len はそれぞれ NULL と 0 に設定すべきである。lpSQOS が NULL
のときは、アプリケーションが QoS を指定していないことを意味する。lpGQOS
は将来のソケットグループ用に予約されている。lpGQOS 引数はソケットグループ (該当する場合) 用の FLOWSPEC
構造体を方向ごとに指定し、続いてプロバイダ固有の追加引数を指定する。プロバイダ固有引数を指定しない場合、lpCalleeData が指す
WSABUF 構造体の buf と len はそれぞれ NULL と 0 に設定すべきである。lpGQOS が NULL
のときはアプリケーションがグループ QoS を指定していないことを意味する。s
がソケットグループの作成者でない場合、この引数は無視される。接続済みソケットが (何らかの理由で閉じられて)
壊れた場合、破棄して作り直すべきである。何か問題が発生したときは必要なソケットを破棄して作り直し、安定点に戻すのが最も安全である。注:
WSAJoinLeaf のようなブロッキング 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 ストアアプリでサポートされる。

情報