WSAJoinLeaf 関数 (winsock2.h)

[アーティクル]
03/08/2023

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 を再度呼び出すことができます。

エラーコード	意味
WSANOTINITIALIZED	この関数を使用する前に、WSAStartup 呼び出しが正常に行われる必要があります。
WSAEADDRINUSE	ソケットのローカルアドレスは既に使用されており、SO_REUSEADDRでアドレスを再利用できるようにソケットがマークされていません。このエラーは通常、バインド時に発生しますが、バインドが部分的なワイルドカードアドレス (ADDR_ANYを含む) に対する場合、およびこの関数の時点で特定のアドレスをコミットする必要がある場合は、この関数まで遅延する可能性があります。
WSAEADDRNOTAVAIL	リモートアドレスが有効なアドレス (ADDR_ANY など) ではありません。
WSAEAFNOSUPPORT	指定されたファミリーのアドレスをこのソケットと共に使用することはできません。
WSAEALREADY	指定したソケットで、非ブロッキング WSAJoinLeaf 呼び出しが進行中です。
WSAECONNREFUSED	結合の試行は強制的に拒否されました。
WSAEFAULT	name または namelen パラメーターがユーザーアドレス空間の有効な部分ではない、namelen パラメーターが小さすぎる、lpCalleeData、lpSQOS、lpGQOS のバッファー長が小さすぎる、または lpCallerData のバッファー長が大きすぎる。
WSAEINVAL	WSAJoinLeaf 関数呼び出しは、WSA_FLAG_MULTIPOINT_C_LEAFまたはマルチポイントフラグを設定せずに開かれた UDP ソケットWSA_FLAG_MULTIPOINT_D_LEAF実行されました。
WSAEISCONN	ソケットは既にマルチポイントセッションのメンバーです。
WSAEINTR	ブロックしている Windows ソケット 1.1 呼び出しが WSACancelBlockingCall によって取り消されました。
WSAEINPROGRESS	ブロックしている Windows ソケット 1.1 呼び出しが進行中であるか、サービスプロバイダーがコールバック関数を処理しています。
WSAENETDOWN	ネットワークサブシステムが失敗しました。
WSAENETUNREACH	現在このホストからネットワークには到達できません。
WSAENOBUFS	バッファーに空き領域がありません。ソケットを結合できません。
WSAENOTSOCK	記述子はソケットではありません。
WSAEOPNOTSUPP	lpSQOS および lpGQOS で指定された FLOWSPEC 構造体を満たすことはできません。
WSAEPROTONOSUPPORT	lpCallerData 拡張は、サービスプロバイダーではサポートされていません。
WSAETIMEDOUT	マルチポイントセッションを確立せずに参加しようとするとタイムアウトしました。

注釈

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 がソケットグループの作成者でない場合、このパラメーターは無視されます。

接続されたソケットが切断された場合 (つまり、何らかの理由で閉じられる)、それらは破棄して再作成する必要があります。接続されたソケットで何らかの理由で問題が発生した場合、アプリケーションは、安定したポイントに戻るために必要なソケットを破棄して再作成する必要があると仮定するのが最も安全です。

メモWSAJoinLeaf などのブロッキング Winsock 呼び出しを発行する場合、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 ストアアプリでサポートされています。

要件

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