Presence Interface

Interface that enables users to inform their friends of their current activities.

10 mins to read

With the Presence Interface, an application can advertise its local player's status, known as presence, and query the presence of other players online. An application may also advertise transient data to others, in order to share more detailed information about the state of the local player. Users can only receive presence information about other users with whom they are friends.

To use the Presence Interface, your product must have Epic Account Services (EAS) active, and must obtain user consent to access Online Presence data. You can activate EAS on the Developer Portal, or learn more in Epic's documentation. Without EAS and user consent, you will still be able to initialize the EOS SDK and the Presence Interface, but all Presence Interface function calls to the back-end service will fail.

Managing Presence Information

To use the Presence Interface, you must acquire a handle of type EOS_HPresence from the Platform Interface function, EOS_Platform_GetPresenceInterface. With this handle, you can download and cache presence information about other users on your friends list, or update your own presence.

Retrieving and Caching Presence Information

To retrieve presence information about a user, call EOS_Presence_QueryPresence with an EOS_Presence_QueryPresenceOptions structure, an optional ClientData parameter, and a callback function. Initialize the EOS_Presence_QueryPresenceOptions with the following field values:

PropertyValue
ApiVersionEOS_FRIENDS_QUERYPRESENCE_API_LATEST
LocalUserIdThe EOS_EpicAccountId of the logged-in user making the request.
TargetUserIdThe EOS_EpicAccountId of the user whose presence data you want to retrieve. This value must either match LocalUserId, or be a friend of that user.

The callback function will receive the ClientData parameter you provide here, and will run following completion of the operation regardless of success or failure. The only exception to this is if the call fails locally due to the EOS_Presence_QueryPresenceOptions structure lacking any of the required information. In the event of failure due to lack of permission to view the target user's presence, the callback function's ResultCode field will be EOS_NotFound. Any other value, aside from EOS_Success, indicates an input or state failure, such as invalid parameters, LocalUserId not matching a local, logged-in user, or the local user being offline.

Updating Presence Information

There are two ways to update presence information in your local cache. The first is to call EOS_Presence_QueryPresence periodically, or shortly before accessing the cache. The second is to receive notification from the Presence Interface when a change has occurred. To enable this feature, call EOS_Presence_AddNotifyOnPresenceChanged. This function requires an EOS_Presence_AddNotifyOnPresenceChangedOptions struct, a user-defined ClientData parameter, and a callback function of type EOS_Presence_OnPresenceChangedCallback. The callback function will receive the ClientData parameter and the EOS_EpicAccountId of the user whose presence changed. Initialize the EOS_Presence_OnPresenceChangedCallback structure as follows:

PropertyValue
ApiVersionEOS_FRIENDS_ADDNOTIFYONPRESENCECHANGED_API_LATEST

If successful, EOS_Presence_AddNotifyOnPresenceChanged will return a valid EOS_NotifcationId. In the case of an error, it will return EOS_INVALID_NOTIFICATIONID.

To deactivate this feature, call EOS_Presence_RemoveNotifyOnPresenceChanged, passing the presence handle and notification ID as parameters. This function stops notifications to a handle previously registered with EOS_Presence_AddNotifyOnPresenceChanged.

There can be multiple callbacks registered at a time. In this case all the callbacks will be called once the event occurs.

Examining Presence Information

Once EOS_Presence_QueryPresence has populated the cache with a user's presence information, you can begin examining it. To establish whether or not the cache contains a given user's presence information, call EOS_Presence_HasPresence with your EOS_HPresence handle, and an EOS_Presence_HasPresenceOptions structure initialized as follows:

PropertyValue
ApiVersionEOS_FRIENDS_HASPRESENCE_API_LATEST
LocalUserIdThe EOS_EpicAccountId of the logged-in user making the request.
TargetUserIdThe EOS_EpicAccountId of the user whose cached presence data you want to locate.

EOS_Presence_HasPresence will return EOS_TRUE if it succeeds and finds data, or EOS_FALSE if it receives bad input or if the cache does not contain data for the target user.

EOS_Presence_CopyPresence provides copies of presence information from the cache. The Presence Interface will return data as a new EOS_Presence_Info object. This function requires your Presence Interface handle, an EOS_Presence_CopyPresenceOptions structure, and an output parameter to hold your new EOS_Presence_Info object. Initialize the EOS_Presence_CopyPresenceOptions structure as follows:

PropertyValue
ApiVersionEOS_FRIENDS_COPYPRESENCE_API_LATEST
LocalUserIdThe EOS_EpicAccountId of the logged-in user making the request.
TargetUserIdThe EOS_EpicAccountId of the user whose cached presence data you want to copy.

If the Presence Interface successfully pulls a copy of the information from the cache, EOS_Presence_CopyPresence will return EOS_Success and fill out the EOS_Presence_Info pointer you provided with a copy of the target user's data. The caller owns this pointer, so the EOS SDK will never modify its contents or free the memory associated with it. Call EOS_Presence_Info_Release with the pointer when you no longer need this data to free it. Failure to do so will result in a memory leak.

EOS_Presence_GetJoinInfo provides an easy way to get the previously set Join Info string from a remote user's presence data. For this function to succeed, the user's presence data must already be in the presence cache. This function requires your Presence Interface handle, an EOS_Presence_GetJoinInfoOptions structure, OutBuffer set to a pointer to a char buffer, and InOutBufferLength set to the maximum length of the char buffer. Initialize the EOS_Presence_GetJoinInfoOptions structure as follows:

ParameterDescription
ApiVersionSet this to EOS_PRESENCE_GETJOININFO_API_LATEST
LocalUserIdThe EOS_EpicAccountId of the logged-in user making the request
TargetUserIdThe EOS_EpicAccountId of the user whose Join Info you want to retrieve. This value must either be a logged-in Local User, or a Friend of LocalUserId.

The length of the OutBuffer char buffer is recommended to be EOS_PRESENCEMODIFICATION_JOININFO_MAX_LENGTH, or it may be too short to store some values and will fail the request.

Note: Updates to presence information, even when using EOS_Presence_AddNotifyOnPresenceChanged, will not be reflected in existing EOS_Presence_Info objects. This is because these objects are copies of cache data, not pointers to the cache, and because the Presence Interface does not own them and will not modify them after the initial copy.

Modifying Local Presence

To modify a local user's presence, you must create an EOS_HPresenceModification handle, and set changes by calling one or more of the following functions:

  • EOS_PresenceModification_SetStatus
  • EOS_PresenceModification_SetRawRichText
  • EOS_PresenceModification_SetData
  • EOS_PresenceModification_DeleteData
  • EOS_PresenceModification_SetJoinInfo

Note: Changes are reflected after a call to EOS_Presence_SetPresence succeeds.

Creating a PresenceModification Handle

To modify a local user's presence, first create a PresenceModification handle by calling EOS_Presence_CreatePresenceModification with a valid EOS_HPresence handle, an initialized EOS_Presence_CreatePresenceModificationOptions struct, and a pointer to an invalid EOS_HPresenceModification handle. Initialize the EOS_Presence_CreatePresenceModificationOptions struct as follows:

PropertyValue
ApiVersionEOS_PRESENCE_CREATEPRESENCEMODIFICATION_API_LATEST
LocalUserIdValid local user in a logged-in state.

If successful, the EOS_Presence_CreatePresenceModification function returns EOS_EResult::EOS_Success, and the OutPresenceModificationHandle will be initialized for use with functions in the EOS_PresenceModification namespace. The resulting handle must also be released when it is no longer needed by calling the EOS_PresenceModification_Release method.

Making Changes to a PresenceModification

With a valid EOS_HPresenceModification, you can build the update for a user's presence by calling functions within the EOS_PresenceModification function namespace.

Modifying Presence Status