DWC_ConnectToFriendsAsync

構文

#include <dwc.h>
BOOL DWC_ConnectToFriendsAsync(DWCTopologyType topology,
                               const u8 friendIdxList[],
                               int friendIdxListLen,
                               u8 maxEntry,
                               DWCMatchedSCCallback matchedCallback,
                               void *matchedParam,
                               DWCNewClientCallback newClientCallback,
                               void *newClientParam,
                               DWCEvalPlayerCallback evalCallback,
                               void *evalParam,
                               DWCConnectAttemptCallback attemptCallback,
                               u8 *connectionUserData,
                               void *attemptParam);

引数

topology 接続形態。DWCTopologyTypeの中から一つ指定します。
friendIdxList 接続要求友達インデックスリストへのポインタ。NULLなら友達リスト全てを接続要求対象とする。
friendIdxListLen 接続要求友達インデックスリスト長。最大値は友達リスト長と同じく64。
maxEntry 要求するネットワーク構成人数(自分を含む)。2〜32の値が設定できる。
matchedCallback 接続完了コールバック関数へのポインタ。1人接続するごとに呼ばれる。
matchedParam 接続完了コールバック用パラメータ。
newClientCallback 新規接続クライアント通知コールバック関数へのポインタ。
newClientParam 新規接続クライアント通知コールバック用パラメータ。
evalCallback プレイヤー評価コールバック関数へのポインタ。
evalParam プレイヤー評価コールバック用パラメータ。
attemptCallback 接続受付判定コールバック関数へのポインタ。
connectionUserData 自分の接続受付判定用パラメータバッファへのポインタ。u8[DWC_CONNECTION_USERDATA_LEN]分のバッファであること。このバッファの内容は、ライブラリにコピーされるので、本関数呼出し後は開放されていても構わない。NULLを指定した場合、自分の接続受付判定用バッファの内容はすべて0に設定される。
attemptParam 接続受付判定コールバック用パラメータ

返り値

TRUE 処理開始。コールバック関数で結果が通知される。
FALSE 本関数を呼んで良い状態ではない

説明

友達を指定して接続し、グループを作成します。これを友達指定ピアマッチメイクと呼びます。

引数friendIdxListには、マッチメイク対象としたい友達の、友達リスト内でのインデックスを集めた配列へのポインタを指定します。インデックスリストにNULLを指定すれば、友達リスト中の全ての友達をマッチメイクの候補とします。友達指定ピアマッチメイク時に参照される友達リストは、DWC_InitFriendsMatch関数で指定されたものになります。

また、引数evalCallbackを指定すれば、マッチメイクの候補プレイヤーを見つける度に指定された評価コールバック関数が呼び出されます。評価コールバック関数内では、DWC_GetMatchIntValue関数、DWC_GetMatchStringValue関数を用いてマッチメイク指標キーを参照することができます。その値を元にプレイヤーを評価し、評価値を戻り値として返してください。評価値が0以下のプレイヤーはマッチメイクの対象から外されます。

友達指定ピアマッチメイクでは、一度に見つかる候補プレイヤーは必ず1人で、評価値が0より大きければマッチメイク開始、評価値が0以下ならマッチメイクを行わないという判定を行っています。

本関数呼出し後、DWC_ProcessFriendsMatch関数を呼び続ければマッチメイク処理が進行します。最初のサーバホストとのマッチメイクが成功、エラー、キャンセルのいずれかの状態になれば、マッチメイク完了コールバックが呼び出されます。サーバホストへの接続後は、サーバホストへ新たに接続に来たクライアントホストがあれば、新規接続クライアントホスト通知コールバックが呼び出されます。また、その新規接続クライアントホストの接続処理が完了すれば、再びマッチメイク完了コールバックが呼び出されます。友達指定ピアマッチメイクでは、自分がサーバホスト・クライアントホストのどちらになるかは自動で決定されます。

ネットワーク接続状況により、関数からしばらく処理が戻らずブロックすることがあります。

接続形態が違う相手とはマッチメイクされることはありませんが、次の注意点があります。DWC_ConnectToAnybodyAsync/DWC_ConnectToFriendsAsyncでは、接続形態が違う相手であっても、これらの関数にDWCEvalPlayerCallback引数が設定されている場合評価コールバックが呼び出されます。評価コールバック内で相手の接続形態を知る手段が無いため、評価コールバックでその相手を除外する方法がありません。

評価コールバックでフィルタされた結果接続することになった相手と接続形態が違う場合、その相手とはマッチメイクが行われません。この挙動は、マッチメイクできる相手が見つかるまで繰り返されます。DWC_ConnectToAnybodyAsync/DWC_ConnectToFriendsAsyncを使用する場合は、接続形態以外の条件でグループ化されるような条件を設け、その中では接続形態が同一になるようにしてください。

接続形態がフルメッシュ型もしくはハイブリッド型のときは、サーバホストが切断したときにサーバ交代が発生します。スター型では発生しません。ハイブリッド型の場合、新しいサーバホストに接続できるのは新しいサーバホストと直接接続されていたホストのみで、それ以外のホストは切断されます。一度でもサーバ交代が起こった後は、そのグループに新規クライアントホストは参加できなくなります。ただしこの友達指定ピアマッチメイクでは、サーバ交代後にそのグループのメンバーが自分一人になった場合は新規クライアントホストの受付を再開します。

履歴

5.1pr2より前の変更履歴はこちら