利用 在线状态接口,应用程序可以播报其本地玩家的状态(称为在线状态),并查询其他玩家的在线状态。应用程序还可以向他人播报临时数据,以共享本地玩家状态更详细的信息。用户只能接收与自己是好友关系的其他用户在线状态信息。
要使用在线状态接口,您的产品必须激活 Epic帐户服务 (EAS),且必须获得用户的同意来访问 在线状态 数据。您可以在开发者门户上启动EAS、在Epic的文档中了解更多详情。如果没有EAS和用户的同意,您仍然可以启动EOS SDK和在线状态接口,但对后端服务的所有在线状态接口函数调用都将失败。
管理在线状态信息
要使用 在线状态接口,须获取 平台接口 函数 EOS_Platform_GetPresenceInterface
中类型为 EOS_HPresence
的柄。利用此柄,便能下载和缓存好友列表上其他用户的在线状态信息,或者更新自己的在线状态。
获取和缓存在线状态信息
要获取用户的在线状态信息,使用一个 EOS_Presence_QueryPresenceOptions
结构、一个可选 ClientData
参数和一个回调函数并调用 EOS_Presence_QueryPresence
。使用下列字段值来初始化 EOS_Presence_QueryPresenceOptions
:
属性 | 值 |
---|---|
ApiVersion | EOS_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
结构进行以下初始化:
属性 | 值 |
---|---|
ApiVersion | EOS_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
:
属性 | 值 |
---|---|
ApiVersion | EOS_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
结构进行以下初始化:
属性 | 值 |
---|---|
ApiVersion | EOS_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
结构体进行以下初始化:
属性 | 值 |
---|---|
ApiVersion | EOS_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
结构体进行以下初始化:
属性 | 值 |
---|---|
ApiVersion | EOS_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
结构体进行以下初始化:
属性 | 值 |
---|---|
ApiVersion | EOS_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
结构体进行如下初始化:
属性 | 值 |
---|---|
ApiVersion | EOS_PRESENCE_SETDATA_API_LATEST |
RecordsCount | Records 中存在的 EOS_Presence_DataRecord 数量。Records 必须是指向 EOS_Presence_DataRecord 数组的指针,其长度必须至少为 RecordsCount 。 |
使用下列设置初始化 EOS_Presence_DataRecord
:
属性 | 值 |
---|---|
ApiVersion | EOS_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
结构体进行以下初始化:
属性 | 值 |
---|---|
ApiVersion | EOS_PRESENCE_DELETEDATA_API_LATEST |
RecordsCount | Records 中存在的 EOS_PresenceModification_DataRecordId 数量,Records 必须是指向 EOS_PresenceModification_DataRecordId 数组的指针。 |
使用下列信息初始化 EOS_PresenceModification_DataRecordId
:
属性 | 值 |
---|---|
ApiVersion | EOS_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
结构体:
属性 | 值 |
---|---|
ApiVersion | EOS_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
事件。欲知详情,请参见社交覆层页面。