Presence Interface

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, 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.

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:

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.

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:

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.

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:

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:

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:

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.

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

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:

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.

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

To set a new status, invoke EOS_PresenceModification_SetStatus with a valid EOS_HPresenceModification handle, and initialize an EOS_PresenceModification_SetStatusOptions struct as follows:

If successful, EOS_PresenceModification_SetStatus returns EOS_EResult::EOS_Success. Otherwise, it returns an error code describing an issue with the request. Changes will not be reflected in a user's presence until a call to EOS_Presence_SetPresence completes with EOS_EResult::EOS_Success.

To set a new rich text string, invoke EOS_PresenceModification_SetRawRichText with a valid EOS_HPresenceModification handle, and initialize an EOS_PresenceModification_SetRawRichText struct as follows:

If successful, EOS_PresenceModification_SetRawRichText returns EOS_EResult::EOS_Success; otherwise, it returns an error code describing an issue with the request. Changes will not be reflected in a user's presence until a call to EOS_Presence_SetPresence completes with EOS_EResult::EOS_Success.

To add or replace existing presence data to a user's presence, invoke EOS_PresenceModification_SetData with a valid EOS_HPresenceModification handle, and initialize an EOS_PresenceModification_SetDataOptions struct as follows:

Initialize EOS_Presence_DataRecord with the following:

If successful, EOS_PresenceModification_SetData returns EOS_EResult::EOS_Success. Otherwise, it returns an error code describing an issue with the request. Changes will not be reflected in a user's presence until a call to EOS_Presence_SetPresence completes with EOS_EResult::EOS_Success.

Similar to EOS_PresenceModification_SetData, EOS_PresenceModification_DeleteData removes presence data that matches the key of previously set data. To delete presence data, invoke EOS_PresenceModification_DeleteData with a valid EOS_HPresenceModification handle, and initialize an EOS_PresenceModification_DeleteDataOptions struct as follows:

Initialize EOS_PresenceModification_DataRecordId with the following:

If a key is marked for delete but does not exist, this part of the pending presence modification process is silently ignored. Additionally, if multiple keys are set to delete the same key, the extra keys will be silently ignored.

If successful, EOS_PresenceModification_DeleteData returns EOS_EResult::EOS_Success; otherwise, it returns an error code describing an issue with the request. Changes will not be reflected in a user's presence until a call to EOS_Presence_SetPresence completes with an EOS_EResult::EOS_Success.

The helper function EOS_PresenceModification_SetJoinInfo sets the EOS_JoinInfo Presence data key with a specified Join Info string. This data may also be retrieved through usage of the EOS_Presence_GetJoinInfo function. This data will be sent to games when invoking the Join Game feature of the EOS Social Overlay, and should contain whatever information is necessary for a game to find and join a user's match or party, depending on what makes sense for the title.

To invoke the EOS_PresenceModification_SetJoinInfo function successfully, it must be called with a valid EOS_HPresenceModification handle, and a valid EOS_PresenceModifcation_SetJoinInfoOptions struct initialized as follows:

Once all changes to an EOS_HPresenceHandle have been made, they must be applied to a user by calling EOS_Presence_SetPresence with a valid EOS_HPresence handle, an optional ClientData field, and an EOS_Presence_SetPresenceCompleteCallback callback function. The Callback function will contain the value of the ClientData parameter. You will also need to provide an EOS_Presence_SetPresenceOptions struct, which you should initialize as follows:

It is safe to release the EOS_HPresenceModification handle immediately after the call to EOS_Presence_SetPresence, however, if there is an error, these changes could be lost. We recommend maintaining this handle until the callback function returns a successful result code or at a time when you want to abandon the changes. Additionally, it is invalid for a single user to have more than EOS_PRESENCE_DATA_MAX_KEYS of unique presence data, and attempting to set more than this many unique presence data keys will fail.

When complete, the callback function will be invoked with an EOS_Presence_SetPresenceCompleteInfo struct that contains the following:

If multiple calls to EOS_Presence_SetPresence happen during a single frame, they may be combined automatically. The callback function for all calls will still be invoked separately but they may share a ResultCode. If there are conflicting modifications, such as a status being set twice across one (or multiple) modifications, the last-set field will overwrite previous changes.

It is also possible to subscribe to notifications related to the Social Overlay, such as JoinGameAccepted event, via a EOS_Presence_AddNotifyJoinGameAccepted/EOS_Presence_RemoveNotifyJoinGameAccepted pair. For more information please refer to the Social Overlay page.