Presence Interface

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

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

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

回调函数将接收用户提供的 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 结构进行以下初始化：

如成功，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：

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

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

如在线状态接口成功在缓存中提取出此信息的副本，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 结构进行以下初始化：

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

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

• EOS_PresenceModification_SetStatus
• EOS_PresenceModification_SetRawRichText
• EOS_PresenceModification_SetData
• EOS_PresenceModification_DeleteData
• EOS_PresenceModification_SetJoinInfo

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

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

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

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

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

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

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

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

使用下列设置初始化 EOS_Presence_DataRecord：

如成功，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 结构体进行以下初始化：

使用下列信息初始化 EOS_PresenceModification_DataRecordId：

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

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

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

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

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

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

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

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

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