友達とのゲームや、オンライン上での新しいプレイヤーとの出会いは、多くのオンライン サービスにおいて重要な部分となっています。 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
型のデリゲートを通じて返されます。