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:
Property | Value |
---|---|
ApiVersion | EOS_FRIENDS_QUERYPRESENCE_API_LATEST |
LocalUserId | The EOS_EpicAccountId of the logged-in user making the request. |
TargetUserId | The 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:
Property | Value |
---|---|
ApiVersion | EOS_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:
Property | Value |
---|---|
ApiVersion | EOS_FRIENDS_HASPRESENCE_API_LATEST |
LocalUserId | The EOS_EpicAccountId of the logged-in user making the request. |
TargetUserId | The 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:
Property | Value |
---|---|
ApiVersion | EOS_FRIENDS_COPYPRESENCE_API_LATEST |
LocalUserId | The EOS_EpicAccountId of the logged-in user making the request. |
TargetUserId | The 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:
Parameter | Description |
---|---|
ApiVersion | Set this to EOS_PRESENCE_GETJOININFO_API_LATEST |
LocalUserId | The EOS_EpicAccountId of the logged-in user making the request |
TargetUserId | The 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:
Property | Value |
---|---|
ApiVersion | EOS_PRESENCE_CREATEPRESENCEMODIFICATION_API_LATEST |
LocalUserId | Valid 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
sandbox. 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 sandbox.
Modifying Presence Status
To set a new status, invoke EOS_PresenceModification_SetStatus
with a valid EOS_HPresenceModification
handle, and initialize an EOS_PresenceModification_SetStatusOptions
struct as follows:
Property | Value |
---|---|
ApiVersion | EOS_PRESENCE_SETSTATUS_API_LATEST |
Status | Valid EOS_Presence_EStatus value. |
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
.
Modifying A Rich Text string
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:
Property | Value |
---|---|
ApiVersion | EOS_PRESENCE_SETRAWRICHTEXT_API_LATEST |
RichText | Non-null string that is smaller than byte size of EOS_PRESENCE_RICH_TEXT_MAX_VALUE_LENGTH . |
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
.
Adding or Replacing Presence Data
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:
Property | Value |
---|---|
ApiVersion | EOS_PRESENCE_SETDATA_API_LATEST |
RecordsCount | How many EOS_Presence_DataRecord are present in Records , and Records must be a pointer to an array of EOS_Presence_DataRecord that is at least RecordsCount long. |
Initialize EOS_Presence_DataRecord
with the following:
Property | Value |
---|---|
ApiVersion | EOS_PRESENCE_DATARECORD_API_LATEST |
Key | Non-null string that is smaller than the byte size of EOS_PRESENCE_DATA_MAX_KEY_LENGTH . |
Value | Non-null string that is smaller than the byte size of EOS_PRESENCE_DATA_MAX_VALUE_LENGTH . |
Note: In the case of conflicting values, such as having multiple DataRecords
with the same key, the last conflicting value in the Records
array will be used.
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
.
Deleting Presence Data
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:
Property | Value |
---|---|
ApiVersion | EOS_PRESENCE_DELETEDATA_API_LATEST |
RecordsCount | How many EOS_PresenceModification_DataRecordId are present in Records , and Records must be a pointer to an array of EOS_PresenceModification_DataRecordId . |
Initialize EOS_PresenceModification_DataRecordId
with the following:
Property | Value |
---|---|
ApiVersion | EOS_PRESENCE_DELETEDATA_API_LATEST |
Key | Non-null string that is smaller than the byte size of EOS_PRESENCE_DATA_MAX_KEY_LENGTH . |
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
.
Setting the Presence JoinInfo Data
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:
Parameter | Description |
---|---|
ApiVersion | Set to EOS_PRESENCEMODIFICATION_SETJOININFO_API_LATEST |
JoinInfo | A null-terminated string of up to EOS_PRESENCEMODIFICATION_JOININFO_MAX_LENGTH bytes in length, not including the null-terminator. |
Applying PresenceModification Changes
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:
Property | Value |
---|---|
ApiVersion | EOS_PRESENCE_SETPRESENCE_API_LATEST |
LocalUserId | Local user who created the presence modification. |
PresenceModificationHandle | The EOS_HPresenceModification handle that has pending changes. |
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:
Property | Description |
---|---|
ResultCode | This is the call's result code. |
ClientData | This is the client data from the ClientData parameter. |
AccountId | This is the account identity value of the local user who invoked the call. |
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.
Subscribing to Social Overlay Notifications
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.