DWC_AddMatchKeyString

構文

#include <dwc.h>
u8 DWC_AddMatchKeyString(u8 keyID,
                         const char *keyString,
                         const char *valueSrc);

引数

keyID 新規にkeyIDを取得する場合は0を指定します。
既に使用中の追加キーIDを指定した場合は、使用中のものと同じkeyStringを渡せばvalueSrcをセットし直すが、違うkeyStringを渡した場合は何もしない。アプリケーションでセットできるキーは最大154個までです。
keyString キー識別のための文字列へのポインタ。
文字列はコピーしてライブラリ内で保持します。
異なるキーIDで同じキー名を使用しないでください。
valueSrc キーに対応する文字列へのポインタで、マスターサーバからのポーリングがあると、このポインタから文字列を参照してマスターサーバに文字列をアップする。

返り値

追加したキーのキーID。パラメータエラー、もしくはキーの設定上限を越えたため追加できなかった場合は0を返す。
DWC_InitFriendsMatch()が呼ばれるより前に呼び出しても0を返す。

説明

マッチメイクの指標となるキー(char*型)を追加します。

追加されたキーはDWC_ConnectToAnybodyAsync関数のマッチメイク条件文字列やDWC_ConnectToAnybodyAsync関数/DWC_ConnectToFriendsAsync関数のプレイヤー評価コールバック(DWCEvalPlayerCallback)内で使用することができます。

ただし、キーに対応した値は、最短でも10秒毎にしかマッチメイキングサーバに通知されないため、上記の条件判定の段階では、実際に相手が設定している値より古い値を参照する可能性があります。このため、動的に値を変更すると意図しない相手とマッチメイクしてしまう可能性があることに留意してください。また、非常に稀ですが動的に値を変更しない場合でも、正常にマッチメイクが終わらなかった直後に、再度マッチメイクを開始するなどで、相手に古い値を参照されてしまう可能性があります。
これが許容できない場合は、マッチメイク後に条件を確認するしかありません。

追加されたキーに関する全てのデータは、マッチメイクが完了した時点でクリアされるため、次にマッチメイクを行う場合は再びキーを登録し直す必要があります。

一回の呼び出しでのkeyString/valueSrcの値に長さの制限はありませんが、アプリケーション全体でセットした値を文字列としたときに、合計2048バイト以下に抑える必要があります。

keyString/valueSrcには、数バイト〜十数バイト程度の文字列の範囲の値なら問題ありませんが、バイナリデータをエンコードしたテキストなど比較的大きなデータはセットしないようにしてください。

キーに対応する文字列に空文字("")は指定できません。空文字を指定した場合は、DWC_GetMatchStringValue関数ではデフォルト値が返されます。

※キー名には使用できないものがあります。以下のキー名は使用しないでください。

country region hostname gamename gamever hostport mapname gametype gamevariant
numplayers numteams maxplayers gamemode teamplay fraglimit teamfraglimit timeelapsed timelimit
roundtime roundelapsed password groupid player_ score_ skill_ ping_ team_
deaths_ pid_ team_t score_t dwc_pid dwc_mtype dwc_mresv dwc_mver dwc_eval

参照

DWC_AddMatchKeyInt

履歴

5.1pr2
返り値の説明を修正
キーに対応した値の更新についての注意を追加

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