Presence Interface

通过该接口,用户可以告知好友自己的当前活动状态。

阅读时间13分钟

利用 在线状态接口,应用程序可以播报其本地玩家的状态(称为在线状态),并查询其他玩家的在线状态。应用程序还可以向他人播报临时数据,以共享本地玩家状态更详细的信息。用户只能接收与自己是好友关系的其他用户在线状态信息。

要使用在线状态接口,您的产品必须激活 Epic帐户服务 (EAS),且必须获得用户的同意来访问 在线状态 数据。您可以在开发者门户上启动EAS、在Epic的文档中了解更多详情。如果没有EAS和用户的同意,您仍然可以启动EOS SDK和在线状态接口,但对后端服务的所有在线状态接口函数调用都将失败。

管理在线状态信息

要使用 在线状态接口,须获取 平台接口 函数 EOS_Platform_GetPresenceInterface 中类型为 EOS_HPresence 的柄。利用此柄,便能下载和缓存好友列表上其他用户的在线状态信息,或者更新自己的在线状态。

获取和缓存在线状态信息

要获取用户的在线状态信息,使用一个 EOS_Presence_QueryPresenceOptions 结构、一个可选 ClientData 参数和一个回调函数并调用 EOS_Presence_QueryPresence。使用下列字段值来初始化 EOS_Presence_QueryPresenceOptions

属性
ApiVersionEOS_FRIENDS_QUERYPRESENCE_API_LATEST
LocalUserId发出请求的已登录用户的 EOS_EpicAccountId
TargetUserId要获取其在线状态数据的用户 EOS_AccountId。此值必须与 LocalUserId 匹配,或是该用户的好友。

回调函数将接收用户提供的 ClientData 参数,无论操作是否成功,都将在操作完成后运行。唯一的例外是由于 EOS_Presence_QueryPresenceOptions 结构缺少必需信息而调用在本地失败之时。如果是由于缺少查看目标用户在线状态的权限而失败,则回调函数的 ResultCode 字段将为 EOS_NotFound。除 EOS_Success 之外的其他值都表明输入或状态失败,例如参数无效、LocalUserId 与本地已登录用户不匹配,或本地用户已离线。

更新在线状态信息

有两种方法来更新本地缓存中的在线状态信息。第一:定期或者在访问缓存前调用 EOS_Presence_QueryPresence。第二:发生变更时从在线状态接口处接收通知。要启用此功能,调用 EOS_Presence_AddNotifyOnPresenceChanged。此函数需要 EOS_Presence_AddNotifyOnPresenceChangedOptions 结构体、一个用户定义的 ClientData 参数,以及一个类型为 EOS_Presence_OnPresenceChangedCallback 的回调函数。回调函数将接收 ClientData 参数和在线状态发生变更的用户 EOS_AccountId。对 EOS_Presence_OnPresenceChangedCallback 结构进行以下初始化:

属性
ApiVersionEOS_FRIENDS_ADDNOTIFYONPRESENCECHANGED_API_LATEST

如成功,EOS_Presence_AddNotifyOnPresenceChanged 将返回有效 EOS_NotifcationId。如出现错误,其将返回 EOS_INVALID_NOTIFICATIONID

要停用此功能,调用 EOS_Presence_RemoveNotifyOnPresenceChanged,将在线状态柄和通知ID作为参数进行传递。此函数将停止通知之前使用 EOS_Presence_AddNotifyOnPresenceChanged 进行注册的柄。

一次可以注册多个回调。在此情况下,事件发生时所有回调都将被调用。

检查在线状态信息

EOS_Presence_QueryPresence 使用用户在线状态信息填充缓存后,便可开始检查。要确定缓存是否包含给定用户的在线状态信息,使用一个 EOS_HPresence 柄和一个初始化如下的 EOS_Presence_HasPresenceOptions 结构来调用 EOS_Presence_HasPresence

属性
ApiVersionEOS_FRIENDS_HASPRESENCE_API_LATEST
LocalUserId发出请求的已登录用户的 EOS_EpicAccountId
TargetUserId要寻找在线状态缓存数据的用户 EOS_EpicAccountId

EOS_Presence_HasPresence 在成功并找到数据时会返回 EOS_TRUE,而在收到错误输入或缓存未包含目标用户数据时返回 EOS_FALSE

EOS_Presence_CopyPresence 提供缓存中的在线状态信息副本。在线状态接口会将数据返回为新的 EOS_Presence_Info 对象。此函数需要在线状态接口柄、一个 EOS_Presence_CopyPresenceOptions 结构和一个输出参数来保存新的 EOS_Presence_Info 对象。将 EOS_Presence_CopyPresenceOptions 结构进行以下初始化:

属性
ApiVersionEOS_FRIENDS_COPYPRESENCE_API_LATEST
LocalUserId发出请求的已登录用户的 EOS_EpicAccountId
TargetUserId要复制在线状态缓存数据的用户 EOS_EpicAccountId

如在线状态接口成功在缓存中提取出此信息的副本,EOS_Presence_CopyPresence 将返回 EOS_Success,并用目标用户数据副本来填充用户提供的 EOS_Presence_Info 指针。调用程序拥有此指针,因此EOS SDK不会修改其内容或释放与其关联的内存。不再需要此数据时,使用指针调用 EOS_Presence_Info_Release 释放内存。否则将导致内存泄漏。

EOS_Presence_GetJoinInfo 提供了一种简单的方式,从远程用户的在线状态数据获取之前设置的“Join Info”字符串。要使此函数成功,用户的在线状态数据必须已处于在线状态缓存中。此函数需要您的在线状态接口柄、一个 EOS_Presence_GetJoinInfoOptions 结构、设为指向字符缓冲指针的 OutBuffer,以及设为字符缓冲最大长度的 InOutBufferLength。将 EOS_Presence_GetJoinInfoOptions 结构进行以下初始化:

参数说明
ApiVersion将此设为 EOS_PRESENCE_GETJOININFO_API_LATEST
LocalUserId发出请求的已登录用户的EOS_EpicAccountId。
TargetUserId要获取其Join Info的用户的 EOS_EpicAccountId。此值必须为登录的本地用户、或好友的LocalUserId。

OutBuffer 字符缓冲的长度建议为 EOS_PRESENCEMODIFICATION_JOININFO_MAX_LENGTH,否则其可能太短而无法保存一些值,从而导致请求失败。

注意: 即使使用 EOS_Presence_AddNotifyOnPresenceChanged 时,在线状态信息的更新也不会反映在现有 EOS_Presence_Info 对象中。这是因为此类对象是缓存数据的副本,而非指向缓存的指针,同时在线状态接口未拥有此类对象,因此在初次复制后不会对其修改。

修改本地在线状态

要修改本地用户的在线状态,必须创建一个 EOS_HPresenceModification 柄,并调用下列一个或多个函数来进行设置:

  • EOS_PresenceModification_SetStatus
  • EOS_PresenceModification_SetRawRichText
  • EOS_PresenceModification_SetData
  • EOS_PresenceModification_DeleteData
  • EOS_PresenceModification_SetJoinInfo

注意: 成功调用 EOS_Presence_SetPresence 后,变更将反映出来。

创建PresenceModification柄

要修改本地用户的在线状态,首先创建 PresenceModification 柄,方法如下:使用一个有效 EOS_HPresence 柄、一个初始化的 EOS_Presence_CreatePresenceModificationOptions 结构体和一个指向无效 EOS_HPresenceModification 柄的指针并调用 EOS_Presence_CreatePresenceModification。将 EOS_Presence_CreatePresenceModificationOptions 结构体进行以下初始化:

属性
ApiVersionEOS_PRESENCE_CREATEPRESENCEMODIFICATION_API_LATEST
LocalUserId处于已登录状态的有效本地用户。

如成功,EOS_Presence_CreatePresenceModification 函数会返回 EOS_EResult::EOS_Success,并初始化 OutPresenceModificationHandle 以结合 EOS_PresenceModification 命名空间中的函数使用。不再需要生成的柄时,须调用 EOS_PresenceModification_Release 将其释放。

变更PresenceModification

利用有效EOS_HPresenceModification,可在 EOS_PresenceModification 函数命名空间中调用函数,以构建用户在线状态的更新。

修改在线状态

要设置新状态,使用有效 EOS_HPresenceModification 柄调用 EOS_PresenceModification_SetStatus,同时对 EOS_PresenceModification_SetStatusOptions 结构体进行以下初始化:

属性
ApiVersionEOS_PRESENCE_SETSTATUS_API_LATEST
Status有效 EOS_Presence_EStatus 值。

如成功,EOS_PresenceModification_SetStatus 将返回 EOS_EResult::EOS_Success。否则其会返回描述请求相关问题的错误代码。EOS_Presence_SetPresence 的调用以 EOS_EResult::EOS_Success 结束后,用户的在线状态的变更才会反映出来。

修改多格式文本字符串

要设置新的多格式文本字符串,使用有效 EOS_HPresenceModification 柄并调用 EOS_PresenceModification_SetRawRichText,同时对 EOS_PresenceModification_SetRawRichText 结构体进行以下初始化:

属性
ApiVersionEOS_PRESENCE_SETRAWRICHTEXT_API_LATEST
RichText小于 EOS_PRESENCE_RICH_TEXT_MAX_VALUE_LENGTH 字节大小的非空字符串。

如成功,EOS_PresenceModification_SetRawRichText 将返回 EOS_EResult::EOS_Success。否则其会返回描述请求相关问题的错误代码。EOS_Presence_SetPresence 的调用以 EOS_EResult::EOS_Success 结束后,用户的在线状态的变更才会反映出来。

添加或替换在线状态数据

要添加或替换用户在线状态的现有数据,用有效 EOS_HPresenceModification 柄调用 EOS_PresenceModification_SetData,同时对 EOS_PresenceModification_SetDataOptions 结构体进行如下初始化:

属性
ApiVersionEOS_PRESENCE_SETDATA_API_LATEST
RecordsCountRecords 中存在的 EOS_Presence_DataRecord 数量。Records 必须是指向 EOS_Presence_DataRecord 数组的指针,其长度必须至少为 RecordsCount

使用下列设置初始化 EOS_Presence_DataRecord

属性
ApiVersionEOS_PRESENCE_DATARECORD_API_LATEST
Key小于 EOS_PRESENCE_DATA_MAX_KEY_LENGTH 字节大小的非空字符串。
Value小于 EOS_PRESENCE_DATA_MAX_VALUE_LENGTH 字节大小的非空字符串。

注意: 若出现冲突值(如相同键拥有多个 DataRecords),则使用 Records 数组中最后一个冲突值。

如成功,EOS_PresenceModification_SetData 将返回 EOS_EResult::EOS_Success。否则其会返回描述请求相关问题的错误代码。EOS_Presence_SetPresence 的调用以 EOS_EResult::EOS_Success 结束后,用户的在线状态的变更才会反映出来。

删除在线状态数据

EOS_PresenceModification_SetData 相似,EOS_PresenceModification_DeleteData 也将删除与之前设置数据的键相匹配的在线状态数据。要删除在线状态数据,用一个有效 EOS_HPresenceModification 柄调用 EOS_PresenceModification_DeleteData,然后对 EOS_PresenceModification_DeleteDataOptions 结构体进行以下初始化:

属性
ApiVersionEOS_PRESENCE_DELETEDATA_API_LATEST
RecordsCountRecords 中存在的 EOS_PresenceModification_DataRecordId 数量,Records 必须是指向 EOS_PresenceModification_DataRecordId 数组的指针。

使用下列信息初始化 EOS_PresenceModification_DataRecordId

属性
ApiVersionEOS_PRESENCE_DELETEDATA_API_LATEST
Key小于 EOS_PRESENCE_DATA_MAX_KEY_LENGTH 字节大小的非空字符串。

如被标记要删除的键不存在,待定在线状态修改进程的这个部分将被忽略且无提示。此外,如果多个键被设为删除同一个键,则额外的键也将被忽略且无提示。

如成功,EOS_PresenceModification_DeleteData 将返回 EOS_EResult::EOS_Success。否则其会返回描述请求相关问题的错误代码。EOS_Presence_SetPresence 的调用以 EOS_EResult::EOS_Success 结束后,用户的在线状态的变更才会反映出来。

设置在线状态JoinInfo数据

助手函数 EOS_PresenceModification_SetJoinInfo 将以特定的Join Info字符串来设置 EOS_JoinInfo 在线状态数据键。也可以通过 EOS_Presence_GetJoinInfo 函数的使用来获取此数据。在EOS社交覆层上启用加入游戏(Join Game)功能时,此数据将被发送到游戏。此数据应包含游戏寻找并加入玩家的游戏或派对时的必要信息,具体取决于游戏本身。

要成功调用 EOS_PresenceModification_SetJoinInfo函数,其必须以一个有效EOS_HPresenceModification柄、以及初始化如下的一个有效EOS_PresenceModifcation_SetJoinInfoOptions` 结构体:

参数说明
ApiVersion设为 EOS_PRESENCEMODIFICATION_SETJOININFO_API_LATEST
JoinInfo一个非空结尾的字符串,长度最高为 EOS_PRESENCEMODIFICATION_JOININFO_MAX_LENGTH 字节,不包括空结束符。

应用PresenceModification更改

对一个 EOS_HPresenceHandle 进行的所有修改完成后,必须将其应用到用户,方法如下:以一个有效 EOS_HPresence 柄、一个可选 ClientData 字段和一个 EOS_Presence_SetPresenceCompleteCallback 回调函数来调用 EOS_Presence_SetPresence。回调函数将包含 ClientData 参数的值。您还需要提供一个初始化如下的 EOS_Presence_SetPresenceOptions 结构体:

属性
ApiVersionEOS_PRESENCE_SETPRESENCE_API_LATEST
LocalUserId创建在线状态修改的本地用户。
PresenceModificationHandle拥有待定更改的 EOS_HPresenceModification 柄。

在调用 EOS_Presence_SetPresence 之后可以立即安全释放 EOS_HPresenceModification 柄。但如果出错,这些更改可能丢失。建议保留此柄,直到回调函数返回成功结果代码、或是您希望放弃修改。此外,单个用户拥有超过 EOS_PRESENCE_DATA_MAX_KEYS 个独特在线状态数据将视为无效,尝试设置独特在线状态数据键的数量超过此数也会失败。

完成时,将使用包含下列信息的 EOS_Presence_SetPresenceCompleteInfo 结构体来调用回调函数:

属性说明
ResultCode这是调用的结果代码。
ClientData这是 ClientData 参数中的客户端数据。
AccountId这是发起调用的本地用户帐户身份值。

如在一帧内多次调用 EOS_Presence_SetPresence ,将对其自动合并。所有调用的回调函数仍将被单独调用,但其可共享 ResultCode。若存在在一次(或多次)修改中设置两次状态之类的修改冲突,最后设置的字段将覆盖上个更改。

注册到社交覆层通知

其也能注册到 社交覆层 相关的通知,例如通过 EOS_Presence_AddNotifyJoinGameAccepted/EOS_Presence_RemoveNotifyJoinGameAccepted 对注册 JoinGameAccepted 事件。欲知详情,请参见社交覆层页面。