WSAJoinLeaf 関数 (winsock2.h)
WSAJoinLeaf 関数は、リーフ ノードをマルチポイント セッションに結合し、接続データを交換し、指定された FLOWSPEC 構造体に基づいて必要なサービス品質を指定します。
構文
SOCKET WSAAPI WSAJoinLeaf(
[in] SOCKET s,
[in] const sockaddr *name,
[in] int namelen,
[in] LPWSABUF lpCallerData,
[out] LPWSABUF lpCalleeData,
[in] LPQOS lpSQOS,
[in] LPQOS lpGQOS,
[in] DWORD dwFlags
);
パラメーター
[in] s
マルチポイント ソケットを識別する記述子。
[in] name
ソケットが結合されるピアの名前。
[in] namelen
名前の長さ (バイト単位)。
[in] lpCallerData
マルチポイント セッションの確立中にピアに転送されるユーザー データへのポインター。
[out] lpCalleeData
マルチポイント セッションの確立中にピアから転送されるユーザー データへのポインター。
[in] lpSQOS
ソケット s の FLOWSPEC 構造体へのポインター。方向ごとに 1 つ。
[in] lpGQOS
ソケット グループで将来使用するために予約されています。 ソケット グループの FLOWSPEC 構造体へのポインター (該当する場合)。
[in] dwFlags
ソケットが送信側 (JL_SENDER_ONLY)、受信側 (JL_RECEIVER_ONLY)、または両方 (JL_BOTH) として機能していることを示すフラグ。
戻り値
エラーが発生しない場合、 WSAJoinLeaf は、新しく作成されたマルチポイント ソケットの記述子である SOCKET 型の値を返します。 それ以外の場合は、INVALID_SOCKETの値が返され、 WSAGetLastError を呼び出すことによって特定のエラー コードを取得できます。
ブロッキング ソケットでは、戻り値は結合操作の成功または失敗を示します。
非ブロッキング ソケットの場合、結合操作の正常な開始は、有効なソケット記述子の戻り値によって示されます。 その後、結合操作が正常に完了するか、それ以外の場合に、元 のソケットで FD_CONNECTが示されます。 結合操作がいつ完了したかを判断し、関連するエラー コードを確認して操作の成功または失敗を判断するには、アプリケーションで、FD_CONNECT イベントに対して登録された関心のある WSAAsyncSelect または WSAEventSelect を使用する必要があります。 select 関数を使用して、結合操作がいつ完了するかを判断することはできません。
また、マルチポイント セッション参加の試行が完了するまで、同じソケット上の WSAJoinLeaf に対する後続のすべての呼び出しは、エラー コード WSAEALREADY で失敗します。 WSAJoinLeaf 操作が正常に完了すると、通常、後続の試行はエラー コード WSAEISCONN で失敗します。 WSAEISCONN 規則の例外は、ルート開始結合を許可するc_root ソケットに対して発生します。 このような場合は、以前の WSAJoinLeaf 操作が完了した後に、別の結合が開始される可能性があります。
戻りエラー・コードが、マルチポイント・セッション結合の試行が失敗したことを示している場合 (つまり、 WSAECONNREFUSED、 WSAENETUNREACH、 WSAETIMEDOUT) は、同じソケットに対して WSAJoinLeaf を再度呼び出すことができます。
| エラー コード | 意味 |
|---|---|
| この関数を使用する前に 、WSAStartup 呼び出しが正常に行われる必要があります。 | |
| ソケットのローカル アドレスは既に使用されており、SO_REUSEADDRでアドレスを再利用できるようにソケットがマークされていません。 このエラーは通常、バインド時に発生しますが、バインドが部分的なワイルドカード アドレス (ADDR_ANYを含む) に対する場合、およびこの関数の時点で特定のアドレスをコミットする必要がある場合は、この関数まで遅延する可能性があります。 | |
| リモート アドレスが有効なアドレス (ADDR_ANY など) ではありません。 | |
| 指定されたファミリーのアドレスをこのソケットと共に使用することはできません。 | |
| 指定したソケットで、非ブロッキング WSAJoinLeaf 呼び出しが進行中です。 | |
| 結合の試行は強制的に拒否されました。 | |
| name または namelen パラメーターがユーザー アドレス空間の有効な部分ではない、namelen パラメーターが小さすぎる、lpCalleeData、lpSQOS、lpGQOS のバッファー長が小さすぎる、または lpCallerData のバッファー長が大きすぎる。 | |
| WSAJoinLeaf 関数呼び出しは、WSA_FLAG_MULTIPOINT_C_LEAFまたはマルチポイント フラグを設定せずに開かれた UDP ソケットWSA_FLAG_MULTIPOINT_D_LEAF実行されました。 | |
| ソケットは既にマルチポイント セッションのメンバーです。 | |
| ブロックしている Windows ソケット 1.1 呼び出しが WSACancelBlockingCall によって取り消されました。 | |
| ブロックしている Windows ソケット 1.1 呼び出しが進行中であるか、サービス プロバイダーがコールバック関数を処理しています。 | |
| ネットワーク サブシステムが失敗しました。 | |
| 現在このホストからネットワークには到達できません。 | |
| バッファーに空き領域がありません。 ソケットを結合できません。 | |
| 記述子はソケットではありません。 | |
| lpSQOS および lpGQOS で指定された FLOWSPEC 構造体を満たすことはできません。 | |
| lpCallerData 拡張は、サービス プロバイダーではサポートされていません。 | |
| マルチポイント セッションを確立せずに参加しようとするとタイムアウトしました。 |
注釈
WSAJoinLeaf 関数は、リーフ ノードをマルチポイント セッションに参加させ、セッション参加時にも発生するその他の多くの補助操作を実行するために使用されます。 ソケット s がバインドされていない場合、システムによってローカルの関連付けに一意の値が割り当てられ、ソケットはバインド済みとしてマークされます。
WSAJoinLeaf 関数のパラメーターとセマンティクスは WSAConnect と同じですが、ソケット記述子 (WSAAccept の場合と同様) が返され、dwFlags パラメーターが追加されています。 この関数の入力パラメーター s には、適切なマルチポイント フラグが設定された WSASocket を使用して作成されたマルチポイント ソケットのみを使用できます。 返されたソケット記述子は、結合操作が完了するまで使用できません。 たとえば、元のソケットのWSAAsyncSelect または WSAEventSelect から対応するFD_CONNECT表示を受信した後にソケットが非ブロッキング モードの場合、この新しいソケット記述子で closesocket を呼び出して保留中の結合操作を取り消すことができます。 マルチポイント セッションのルート アプリケーションでは、多数のリーフ ノードを追加するために WSAJoinLeaf を 1 回以上呼び出すことができますが、一度に最大 1 つのマルチポイント接続要求が未処理である可能性があります。 詳細については、「 マルチポイントとマルチキャストのセマンティクス 」を参照してください。
非ブロッキング ソケットの場合、多くの場合、接続をすぐに完了することはできません。 このような場合、この関数は、まだ使用できないソケット記述子を返し、操作を続行します。 この場合、 WSAEWOULDBLOCK などのエラー コードはありません。これは、関数が正常な開始指示を効果的に返しているためです。 最終的な結果の成功または失敗が判明すると、クライアントが元のソケットに通知を登録する方法に応じて、WSAAsyncSelect または WSAEventSelect を介して報告される場合があります。 いずれの場合も、通知は FD_CONNECT と共に通知され、FD_CONNECTに関連付けられているエラー コードは成功または失敗の特定の理由を示します。 select 関数を使用して、WSAJoinLeaf の完了通知を検出することはできません。
WSAJoinLeaf によって返されるソケット記述子は、入力ソケット記述子 s がc_rootであるか、c_leafであるかによって異なります。 c_root ソケットで使用する場合、 name パラメーターは追加する特定のリーフ ノードを指定し、返されるソケット記述子は、新しく追加されたリーフ ノードに対応するc_leaf ソケットです。 新しく作成されたソケット には、 と同じプロパティがあります。これには、 WSAAsyncSelect または WSAEventSelect に登録された非同期イベントが含 まれます。 これは、マルチポイント データの交換に使用されるものではなく、特定のc_leafに存在する接続のネットワーク イベント表示 (たとえば、FD_CLOSE) を受信するために使用されます。 一部のマルチポイント実装では、このソケットをルートと個々のリーフ ノード間のサイド チャットに使用することもできます。 対応するリーフ ノードが closesocket を呼び出してマルチポイント セッションからドロップアウトした場合、このソケットに対してFD_CLOSE通知が受信されます。 対称的に、WSAJoinLeaf から返されたc_leaf ソケットで closesocket を呼び出すと、対応するリーフ ノード内のソケットがFD_CLOSE通知を受け取ります。
WSAJoinLeaf が c_leaf ソケットで呼び出されると、name パラメーターにはルート アプリケーションのアドレス (ルート制御スキームの場合) または既存のマルチポイント セッション (非ルート制御スキーム) が含まれており、返されるソケット記述子は入力ソケット記述子と同じです。 言い換えると、新しいソケット記述子は割り当てません。 ルート化された制御スキームでは、ルート アプリケーションは listen を呼び出してc_root ソケットをリッスン モードにします。 標準のFD_ACCEPT通知は、リーフ ノードがマルチポイント セッションへの参加を要求したときに配信されます。 ルート アプリケーションは、通常の accept 関数または WSAAccept 関数を使用して、新しいリーフ ノードを許可します。 accept または WSAAccept から返される値は、WSAJoinLeaf から返されるものと同様に、c_leafソケット記述子でもあります。 ルート開始結合とリーフ開始結合の両方を許可するマルチポイント スキームに対応するために、既にリッスン モードのc_root ソケットを WSAJoinLeaf への入力として使用できます。
アプリケーションは、指定されたパラメーターのいずれかによって直接または間接的に指されるメモリ領域を割り当てる役割を担います。
lpCallerData は、マルチポイント セッション参加要求と共に送信されるユーザー データを含む値パラメーターです。 lpCallerData が NULL の場合、ユーザー データはピアに渡されません。 lpCalleeData は、マルチポイント セッション確立の一部としてピアから返されたユーザー データを格納する結果パラメーターです。 lpCalleeData パラメーターが指す WSABUF 構造体の len メンバーには、最初に、アプリケーションによって割り当てられ、WSABUF 構造体の buf メンバーによって指されるバッファーの長さが含まれています。 lpCalleeData パラメーターが指す WSABUF 構造体の len メンバーは、ユーザー データが返されていない場合は 0 に設定されます。 lpCalleeData 情報は、マルチポイント結合操作が完了すると有効になります。
ブロッキング ソケットの場合、 これは WSAJoinLeaf 関数から戻るときに発生します。 非ブロッキング ソケットの場合、これは結合操作が完了した後になります。 たとえば、これは、元のソケット の 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 がソケット グループの作成者でない場合、このパラメーターは無視されます。
接続されたソケットが切断された場合 (つまり、何らかの理由で閉じられる)、それらは破棄して再作成する必要があります。 接続されたソケットで何らかの理由で問題が発生した場合、アプリケーションは、安定したポイントに戻るために必要なソケットを破棄して再作成する必要があると仮定するのが最も安全です。
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 |