Friends Interface

用于获取好友列表、或添加/移除其他用户的接口。

阅读时间5分钟

与好友进行游戏和在网上结识新玩家是许多在线服务的重要组成部分。Epic在线服务 （EOS）SDK使用 好友接口 来获取登录用户的好友列表。

好友列表保存于在线服务的服务器上，可在会话期间随好友的添加或移除、好友同意或拒绝游戏使用其信息而发生变化。

好友列表查询成功完成时，好友接口将创建一个被所有其他好友接口函数使用的本地缓存。此外，SDK将从后端接收造成好友列表变化事件的相关通知，例如好友被移除、邀请被接受，或好友拒绝同意游戏使用其信息。

要使用好友接口，您的产品必须激活 Epic帐户服务 （EAS），且必须获得用户的同意来访问 好友列表 数据。您可以在开发者门户上启动EAS、在Epic的文档中了解更多详情。

获取并缓存好友列表

要获取用户的好友列表，需要一个 EOS_HFriends 柄。您可以通过平台接口函数 EOS_Platform_GetFriendsInterface 获取此柄。好友接口函数需要此柄来访问您登录用户的好友列表。

处理用户好友列表的第一步是用一个 EOS_Friends_QueryFriendsOptions 数据结构调用 EOS_Friends_QueryFriends。这会把用户好友列表的最新版本下载到本地缓存中，然后在完成时调用您的 EOS_Friends_QueryFriends 回调函数。

要执行 EOS_Friends_QueryFriends 调用，请按照以下方式创建并初始化一个 EOS_Friends_QueryFriendsOptions 结构：

属性值
ApiVersionEOS_FRIENDS_QUERYFRIENDS_API_LATEST
LocalUserId要获取其好友列表的已登录用户的 EOS_EpicAccountId。

将好友接口柄、EOS_Friends_QueryFriendsOptions 结构和回调信息传至函数。假设 EOS_HPlatform 柄正在tick，操作完成时将运行您提供的回调。

回调执行时，您可以检查 EOS_Friends_QueryFriendsCallbackInfo 结构的 ResultCode 字段，确定操作成功或失败。成功代码则说明SDK已从服务器缓存最新数据，可以供您随时进行检查。

检查好友列表

成功调用 EOS_Friends_QueryFriends 后，开发者可以使用本地缓存执行下列实用功能：

  • 调用 EOS_Friends_GetFriendsCount 来确定列表上的好友数量。
  • 调用 EOS_Friends_GetFriendAtIndex 来获取每个好友的 EOS_EpicAccountId。

可将此函数返回的 EOS_EpicAccountId 传递到 用户信息接口 来获取用户的其他相关信息。

  • 调用 EOS_Friends_GetStatus 来确定社交关系的当前状态。此函数将返回四个值中的一个：
数值描述
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。

管理好友列表

本节所述的好友列表管理API目前仅适用于Windows PC游戏。

对任天堂Switch、PlayStation和Xbox主机平台的支持正在规划中。 对macOS、Linux、Android和iOS的支持也在规划之中。

你可以通过调用 EOS_Friends_SendInvite SDK API，允许本地用户向游戏中的其他用户发送好友请求。如果想要实现接受/拒绝好友邀请时的相关游戏用户界面的功能，你可以分别使用 EOS_Friends_AcceptInvite 和 EOS_Friends_RejectInvite SDK API。

如果平台尚不允许该功能，这些API将返回 `EOS_NotImplemented'。