友達とのゲームや、オンライン上での新しいプレイヤーとの出会いは、多くのオンライン サービスにおいて重要な部分となっています。 Friends インターフェース には、他のユーザーの追加、削除、ブロックなど、ユーザーのソーシャル コンタクトのリストを管理するための機能が含まれています。
友達を管理する
友達リストはオンライン サービスのサーバーに保存されており、セッション中に友達の追加や削除、ゲームやセッションへの参加と退会、またはサービスのログインとログアウトを行うと、それらの変更が反映されます。 そのため、これらのリストを管理するには、サーバーに最新の情報を照会してから、その情報をキャッシュに入れてゲームで使用する必要があります。
友達リストを取得する
ユーザーの友達リストを扱うための最初のステップは、一般的に ReadFriendsList を呼び出すことです。これにより、指定されたローカル ユーザーに属する名前付き友達リストの最新バージョンを取得できます。
有効なリスト名は EFriendsList 列挙型にあり、提供された ToString 関数によって文字列に変換できます。
これはリモート マシンを照会するので、ReadFriendsList は非同期であり、完了時に FOnReadFriendsListComplete 型のデリゲートを呼び出します。
成功すると、この呼び出しによってリストがキャッシュされます。こうすることで、リモートマシンに繰り返し照会したり、デベロッパーが自分のキャッシュコードを書くことなく、必要に応じて後で調べることができるようになります。
また、リスト上のユーザーの プレゼンス (presence) ステータス データもアップデートされます。
FOnReadFriendsListComplete によって返されるデータには、ReadFriendsList の操作における成否に関する情報のみが含まれています。
友達リストを調べる
リストの取得とキャッシュを行う ReadFriendsList の呼び出しが成功した後、GetFriendsList を使ってリスト自体のコピーを取得したり、GetFriend でリストから友達を個別に取得することができます。
さらに、既知のユーザーの FUniqueNetId を IsFriend 関数に渡して、そのユーザーの指定されたリストを確認できます。
友達リストは、新しいプレイヤーとの出会いといったゲーム内のイベントや、ユーザーが別のシステムからアカウントを変更するといったゲーム外のイベントの両方に基づいて変更されます。
ReadFriendsList を呼び出すことで、キャッシュされたリストを最新に保つことができます。
友達を招待する
SendInvite 関数は、 FUniqueNetId によって識別されたユーザーに招待状を送信します。
承認されると、ユーザーはオンライン サービスによって指定されたリストに追加されます。
この操作が終了すると FOnSendInviteComplete 型のデリゲートが呼び出されますが、これは招待状が送信された (または送信に失敗した) ことを意味するだけで、目的の受信者がそれを受信または返信したことは示していません。
一部のオンライン サービスには、招待状を送信するためのカスタム ユーザー インターフェースがあり、 SendInvite が呼び出されるとそれが自動的に開くことがあります。
SendInvite の呼び出しはすべて最終的に FOnSendInviteComplete のデリゲートをトリガーします。
これは、外部 UI が開かれて、ユーザーがそれを取り消した場合も同様です。
招待を承認または却下する
別のユーザーからの招待状が届くと、送信者と受信者の FUniqueNetId を含む FOnInviteReceivedDelegate 型のデリゲートが呼び出されます。
その際、招待されたユーザーは、新しい友達が表示されるリストの名前を指定し、AcceptInvite または RejectInvite を呼び出して対応できます。
この操作の結果を伝えるために、 RejectInvite は FOnRejectInviteComplete のデリゲートを使用する一方で、 AcceptInvite は FOnAcceptInviteComplete 型のデリゲートを使用します。
友達リストを削除する
非同期の DeleteFriendsList 関数を介して、オンライン サービスに友達リストを削除する指示を出すことができます。
完了すると、FOnDeleteFriendsListComplete 型のデリゲートが呼び出されます。
友達を削除する
ローカル ユーザーに属するリストから友達を削除するには、DeleteFriend 関数を呼び出します。
この操作が完了すると、FOnDeleteFriendComplete 型のデリゲートが呼び出されます。
一部のオンライン サービスでは、友達を複数のリストに登録することができます。このような場合、この関数は、指定されたリストのみから友達を削除します。
オンラインで出会ったプレイヤーの扱い
多くの場合、オンライン サービスでは、ユーザーがパブリック ゲーム セッションなどで最近出会ったが、まだ友達リストに追加していない、もしくはブロックしていないプレイヤーが含まれる個別のリストを維持しています。 最近出会ったプレイヤーのリストは、オンラインサービスへの照会とリストのキャッシュにより、友達リストと同様に処理されます。
最近出会ったプレイヤーのリストを取得する
QueryRecentPlayers はオンライン サービスに対して非同期呼び出しを行い、完了時に FOnQueryRecentPlayersComplete 型のデリゲートを呼び出します。
成功すると、Friends インターフェースはリストをローカルにキャッシュします。
最近出会ったプレイヤーを調べる
QueryRecentPlayers の呼び出しが成功して、最近出会ったプレイヤーのリストを取得すると、GetRecentPlayers 関数はキャッシュされた配列を返します。
配列の個々のエレメントには、ユーザーのデータと、プレイヤーが最後にオンラインだった日時を知らせる関数が含まれます。
ブロックリストを管理する
多くのオンライン サービスには、ユーザーが、そのサービスを介して特定の他のユーザーからの連絡や一緒にプレイすることを拒否できる機能が備わっています。 Friends インターフェースでは、ブロックされたユーザーのリストを取得してキャッシュしたり、オンライン サービスのブロック機能やブロック解除機能を利用したりできます。
現在ブロックされているユーザーを一覧表示する
ブロックされたユーザーのリストを取得するには、QueryBlockedPlayers 関数を呼び出します。
この関数は非同期で、完了時に FOnQueryBlockedPlayersComplete 型のデリゲートを呼び出します。
さらに、ブロックされたユーザーのリストに変更を加えると、FOnBlockListChange デリゲートを通じて通知されます。
ユーザーをブロックまたはブロック解除する
BlockPlayer および UnblockPlayer 関数はオンライン サービスへの非同期呼び出しを行って、 FUniqueNetId によって識別される特定のプレイヤーがローカル プレイヤーによってブロックまたはブロック解除されることをリクエストします。
これらの操作が完了すると、その成否に関する情報がそれぞれ FOnBlockedPlayerComplete 型と FOnUnblockedPlayerComplete 型のデリゲートを通じて返されます。