DWC_UpdateServersAsync

構文

#include <dwc.h>
BOOL DWC_UpdateServersAsync(const char *playerName,
                            DWCUpdateServersCallback updateCallback,
                            void *updateParam,
                            DWCFriendStatusCallback statusCallback,
                            void *statusParam,
                            DWCDeleteFriendListCallback deleteCallback,
                            void *deleteParam);

引数

playerName NULLを指定してください。過去との互換性のために残されています。
updateCallback 友達リスト同期処理完了コールバック関数へのポインタ
updateParam 友達リスト同期処理完了コールバック用パラメータ
statusCallback 友達状態変化通知コールバック関数へのポインタ。このコールバック関数は、友達リスト同期処理が完了した後でも、友達の通信状態が変化する度に呼び出されます。
このコールバック関数は、DWC_SetFriendStatusCallback関数でもセット可能で、互いに上書きし合いますので注意して下さい。
statusParam 友達状態変化通知コールバック用パラメータ
deleteCallback 友達リスト削除コールバック関数へのポインタ。このコールバック関数は、友達リスト同期処理が完了した後でも、友達関係が成立した時に呼び出される可能性があります。
deleteParam 友達リスト削除コールバック用パラメータ

返り値

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

説明

GameSpyサーバとローカルの友達リストの同期処理を行います。この同期処理を行うためには、まずDWC_LoginAsync関数によるログインまでを完了させておく必要があります。

友達リストは、前もってDWC_InitFriendsMatch関数で設定してください。

友達リストの同期処理の主な内容は、

の、3つになります。

友達関係構築要求を送った相手がその時オフライン状態だったとしても、この要求はGameSpyサーバ上に保存され、相手が次回DWC_LoginAsync関数によるログインが完了した直後に届けられます。そして、相手もこちらの情報をローカル友達リストに持っていた場合のみ、友達関係が成立します。ただしこれは、こちらが相手を友達として登録できただけです。友達関係構築要求を受信した相手は、自動的に同様の手順を踏んで、こちらを友達として登録します。友達関係構築要求の送信は、1回のログインにつき1人の相手に対して1回だけ行われます。

友達リストの同期処理はGameSpyサーバとの通信が必要なため、各クライアントが定期的に呼び出すような実装を行うと、GameSpyサーバに高い負荷を与えることになります。目安としては、ログイン後に最初に呼び出した後では、アプリケーションから友達リストの変更を行ったときや、相手が友達関係を維持しているかどうかを確認する必要があるときに絞って呼び出すようにしてください。

注意しなければならないのは、友達リスト同期処理完了コールバックが呼び出されるのは、ローカル/GameSpyサーバ両友達リストを全てチェックし、必要な友達関係構築要求の送信と、不要な友達情報の削除を全て終えた時であるということです。コールバックが返ってきたからといって、全ての友達関係が成立したというわけではありません。

友達リスト同期処理完了コールバックの引数isChangedがTRUEの場合は、ローカル友達リスト中のいずれかの友達情報が更新されたことを示しており、ローカル友達リストをセーブする必要があります。友達リスト同期処理中以外に友達関係が成立した場合は、DWC_SetBuddyFriendCallback関数で設定した友達関係成立コールバックが呼び出されます。

また、友達リストの同期処理の過程では、リスト内に同じ友達の友達情報を複数発見した場合には、1つを残して自動的に削除します。ただし、友達情報がWi-Fiコネクションに接続したことがないもの(DWC_FRIENDDATA_LOGIN_ID)と接続したことがあるもの(DWC_FRIENDDATA_FRIEND_KEY/DWC_FRIENDDATA_GS_PROFILE_ID)は同一確認が取れないため、実際は同じ友達の友達情報でも削除されません。そして削除した友達情報の友達リスト内でのインデックスと、同じ情報と判定された友達のインデックスを引数として、削除するごとにコールバックが呼び出されます。
基本的にはインデックスの小さい方が残りますが、友達関係が成立しているものと成立していないものだった場合は、友達関係が成立している方が残ります。また、友達関係が成立した際にも重複確認が行われ、こちらもインデックスが小さい方が残ります(さらに、重複した友達情報のデータのタイプが友達登録鍵とGSプロファイルIDの場合は、GSプロファイルIDに変更されます)。

友達リストの同期処理開始から友達リスト同期処理完了コールバックが呼ばれるまで、DWC_CloseAllConnectionsHard関数やDWC_ShutdownFriendsMatch関数を呼ぶことができません。特に、DWC_ShutdownFriendsMatchを呼ぶとメモリリークしてしまいます。

履歴

5.2
友達リストの同期処理中にDWC_CloseAllConnectionsHard関数やDWC_ShutdownFriendsMatch関数を呼べない旨を追記
5.1pr2
DWC_SetFriendStatusCallback関数によって、statusCallbackに指定したコールバック関数が上書きされる旨を追記

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