Friends インターフェース

フレンドリストの取得、他のユーザーの追加や削除を行うためのインターフェースです。

このページ中

フレンドリストを取得してキャッシュする
フレンドリストを調べる
フレンドステータスの更新をサブスクライブする
フレンドリストを管理する

友達とゲームをしたり、オンラインで新しいプレイヤーに会ったりすることは、多くのオンラインサービスの重要な部分です。Epic Online Services (EOS) SDK では、「Friends (フレンド) インターフェース」 を使用してログインユーザーのフレンドリストを取得します。

フレンドリストはオンラインサービスのサーバーによって格納され、フレンドが追加または削除されたり、フレンドがゲームで自分の情報が使用されることを許可したり、その許可を取り消したりすると、セッション中に変更されます。

フレンドリストのクエリが正常に完了すると、フレンドインターフェースではローカルキャッシュを作成します。このローカルキャッシュは他のすべてのフレンドインターフェース関数で使用されます。さらに、この SDK では、フレンドの削除、招待の受け入れ、ゲームで自分の情報が使用されることに対する許可をフレンドが取り消すなど、フレンドリストに変更が生じるイベントに関する通知をバックエンドから受信します。

フレンドインターフェースを使用するには、お使いの製品で Epic アカウントサービス (EAS) が有効になっており、フレンドリスト のデータにアクセスするためのユーザーからの許可を得る必要があります。EAS は Developer Portal 上で有効にすることができます。詳細は「Epic のドキュメント」を参照してください。EAS が有効になっておらず、ユーザーの許可を得ていない場合でも、EOS SDK とフレンドインターフェースを初期化することはできます。ただし、バックエンドサービスへのすべてのフレンドインターフェースの関数呼び出しが失敗します。

フレンドリストを取得してキャッシュする

ユーザーのフレンドリストを取得するには、EOS_HFriends ハンドルが必要です。このハンドルは、Platform (プラットフォーム) インターフェースの関数である EOS_Platform_GetFriendsInterface を使用して取得することができます。このハンドルは、フレンドインターフェースの関数がログインユーザーのフレンドリストにアクセスするために必要です。

ユーザーのフレンドリストを処理する最初のステップは、EOS_Friends_QueryFriendsOptions データ構造体を指定して EOS_Friends_QueryFriends を呼び出すことです。この呼び出しにより、最新バージョンのユーザーのフレンドリストをローカルキャッシュにダウンロードされます。完了時には、EOS_Friends_QueryFriends コールバック関数を呼び出します。

EOS_Friends_QueryFriends 呼び出しを実行するには、次のように EOS_Friends_QueryFriendsOptions 構造体を作成して初期化します。


プロパティ	値
`ApiVersion`	`EOS_FRIENDS_QUERYFRIENDS_API_LATEST`
`LocalUserId`	フレンドリストを取得する対象のログインユーザーの `EOS_EpicAccountId`。

フレンドインターフェースハンドル、EOS_Friends_QueryFriendsOptions 構造体、およびコールバック情報を関数に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。

コールバックが実行されたら、EOS_Friends_QueryFriendsCallbackInfo 構造体の ResultCode フィールドを確認すると、操作が成功したか、失敗したかを判断できます。成功コードは、SDK によってサーバーから最新のデータがキャッシュされ、いつでもデータを調査できることを示します。

フレンドリストを調べる

EOS_Friends_QueryFriends の呼び出しに成功したら、デベロッパーはローカルキャッシュを使用して次の便利な関数を実行できます。

EOS_Friends_GetFriendsCount を呼び出してリストのフレンドの人数を特定する。
EOS_Friends_GetFriendAtIndex を呼び出して各フレンドの EOS_EpicAccountId を取得する。

この関数によって返された EOS_EpicAccountId を User Info Interface に渡すことで、ユーザーに関する追加情報を取得できます。

EOS_Friends_GetStatus を呼び出してソーシャルリレーションシップの現在のステータスを特定する。この関数は次の 4 ついずれかの値を返します。


値	説明
`EOS_FS_NotFriends`	ユーザーがフレンドではない。
`EOS_FS_InviteSent`	ローカルユーザーが他のユーザーにフレンド招待を送信した。
`EOS_FS_InviteReceived`	他のユーザーがローカルユーザーにフレンド招待を送信した。
`EOS_FS_Friends`	ユーザーがフレンドである。

フレンドリストは、新しいプレイヤーとの出会いなどのゲーム内イベント、およびユーザーが別のシステムからアカウントを変更するなどのゲーム外イベントの両方から、いつでも変更が可能です。ゲームでは、プレイヤーがログインするたびに何度も EOS_Friends_QueryFriends を呼び出す必要はありません。ただし、プレイヤーがログアウトしてから再ログインした場合は、そのフレンドリストをもう一度クエリする必要があります。フレンドリストのゲームのローカルコピーを最新の状態に維持するには、フレンドステータスの更新通知をサブスクライブします。

フレンドステータスの更新をサブスクライブする

フレンドのステータスが変更されたときに通知を受け取るには、次のパラメータを指定して EOS_Friends_AddNotifyFriendsUpdate を呼び出します。


パラメータ	説明
`Options`	`EOS_Friends_AddNotifyFriendsUpdateOptions` 構造体。唯一のパラメータとして `ApiVersion` を含みます。
`Callback`	`EOS_Friends_OnFriendsUpdateCallback` に一致する有効なコールバック関数。

このコールバック関数はフレンドが更新を取得すると呼び出されます。このコールバックは次のパラメータを含む EOS_Friends_OnFriendsUpdateInfo 構造体を受け取ります。


パラメータ	説明
`LocalUserId`	フレンドに関する更新を受け取るローカルユーザーの `EOS_EpicAccountId`。
`TargetUserId`	ステータスが更新されるユーザーの `EOS_EpicAccountId`。
`PreviousStatus`	ターゲットユーザーのステータスの更新前の値。
`CurrentStatus`	ターゲットユーザーのステータスの更新後の値。

EOS_Friends_AddNotifyFriendsUpdate は EOS_NotificationId を返します。これは、通知が不要になったら、通知のサブスクライブの解除に使用する必要のある専用のハンドルです。失敗した場合、この関数は、結果コード EOS_INVALID_NOTIFICATIONID を返します。

フレンドステータスの更新のサブスクライブを解除するには、関数 EOS_Friends_RemoveNotifyFriendsUpdate を使用します。この関数では、サブスクリプション中に受け取った通知 ID を受け入れます。