LPWSPJOINLEAF コールバック関数 (ws2spi.h)

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

構文

LPWSPJOINLEAF Lpwspjoinleaf;

SOCKET Lpwspjoinleaf(
  [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,
  [out] LPINT lpErrno
)
{...}

パラメーター

[in] s

マルチポイント ソケットを識別する記述子。

[in] name

sockaddr 構造体のソケットが結合されるピアの名前。

[in] namelen

名前の長さ (バイト単位)。

[in] lpCallerData

マルチポイント セッションの確立中にピアに転送されるユーザー データへのポインター。

[out] lpCalleeData

マルチポイント セッションの確立中にピアから転送されるユーザー データへのポインター。

[in] lpSQOS

ソケット s のフロー仕様へのポインター。各方向に対して 1 つ。

[in] lpGQOS

予約済み。

[in] dwFlags

ソケットが送信者、受信側、またはその両方として機能していることを示すフラグ。

[out] lpErrno

エラー コードへのポインター。

戻り値

エラーが発生しない場合、 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 は LPWSPConnect と同じパラメーターとセマンティクスを持ちますが、( LPWSPAccept のように) ソケット記述子を返し、 追加の dwFlags パラメーターを持つ点が除きます。 この関数の入力パラメーター s には、適切なマルチポイント フラグが設定された LPWSPSocket を使用して作成されたマルチポイント ソケットのみを使用できます。 ソケットが非ブロッキング モードの場合、元のソケット の 対応するFD_CONNECT表示を受信するまで、返されたソケット記述子は使用できません。ただし、この新しいソケット記述子で closesocket を呼び出して保留中の結合操作を取り消すことができる点が異なります。 マルチポイント セッションのルート ノードは、複数のリーフ ノードを追加するために WSPJoinLeaf を 1 回以上呼び出すことができますが、一度に最大 1 つのマルチポイント接続要求を未処理にすることができます。 詳細については、 SPI のプロトコルに依存しないマルチキャストとマルチポイント に関するページを参照してください。

非ブロッキング ソケットの場合、多くの場合、接続をすぐに完了することはできません。 このような場合、この関数は、まだ使用できないソケット記述子を返し、操作を続行します。 この場合、 WSAEWOULDBLOCK などのエラー コードはありません。これは、関数が実質的に "正常な開始" の兆候を返しているためです。 最終的な結果の成功または失敗が判明すると、クライアントが元のソケットに通知するために登録する方法に応じて、LPWSPAsyncSelect または LPWSPEventSelect を介して報告される場合があります。 どちらの場合も、通知はFD_CONNECTと共に通知され、FD_CONNECTに関連付けられているエラー コードは成功または失敗の特定の理由を示します。 LPWSPSelect を使用して WSPJoinLeaf の完了通知を検出できないことに注意してください。

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

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

Windows ソケット SPI クライアントは、指定したパラメーターによって直接または間接的に指されるメモリ領域を割り当てる役割を担います。

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

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

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

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

要件

関連項目

LPWSPAccept

LPWSPAsyncSelect

LPWSPBind

LPWSPEventSelect

LPWSPSelect

LPWSPSocket