Sessions Interface

Epic Online Services (EOS) gives players the ability to host, find, and interact with online gaming sessions through the Sessions Interface. A session can be short, like filling a certain number of player slots before starting a game, then disbanding after the game ends, or it could be longer, like keeping track of a game that cycles through matches on multiple maps or levels. The Sessions Interface also manages game-specific data that supports the back-end service searching and matchmaking functionality.

To use the Sessions Interface, acquire an EOS_HSessions handle through the Platform Interface function, EOS_Platform_GetSessionsInterface. All Sessions Interface functions require this handle as their first parameter. You must ensure that the EOS_HPlatform handle is ticking for appropriate callbacks to trigger when requests are completed.

Active Sessions

Active sessions are at the core of everything the Sessions Interface does. An application can have multiple active sessions at the same time, each identified by a unique, local name. For example, there might be a session called "Party" with the local player's friends, keeping them together as they play matches against other teams, and another called "Game" that includes some or all of those friends as well as other players in the match currently in progress. Each session has its own EOS_HActiveSession handle on each participating player's system. An active session forms on a player's machine whenever that player creates a session, or joins a session found in an online search or through an invitation. Since active sessions exist locally, the local application must destroy them when they are no longer needed. If a host fails to do this, the back-end service server will delay destruction of the session, which can lead to other players falsely discovering sessions in their online searches.

To get a copy of the high-level information (type EOS_ActiveSession_Info), for an active session, including its name, the ID of the local user who created or joined it, its current state, a reference to the session details (a const pointer to EOS_SessionDetails_Info), and any user-defined data attributes, you must first get its active session handle (type EOS_HActiveSession) by calling the local function EOS_Sessions_CopyActiveSessionHandle with an EOS_Sessions_CopyActiveSessionHandleOptions initialized as follows:

With this handle, you can call EOS_ActiveSession_CopyInfo. You will also need to initialize and pass in an EOS_ActiveSession_CopyInfoOptions as follows:

This function also runs locally and, on success, makes a copy of the session's EOS_ActiveSession_Info data. You are responsible for releasing the copy with EOS_ActiveSession_Info_Release when you no longer need it.

Session Details

Active sessions that you create locally or discover through searches, invitations, or other users' presence data store an internal data structure called EOS_SessionDetails_Info, which contains basic details about the session:

• Session ID

• Host address

• Number of open slots in the session

The structure also contains a pointer to another structure, EOS_SessionDetails_Settings, which provides more detail about the state of a session, including:

• Top-level filtering criteria, called the Bucket ID, which is specific to your game; often formatted like "GameMode:Region:MapName"

• Total number of connections allowed on the session

• Join-in-progress settings

• Privacy setting

Accessing Session Details

If you have an EOS_ActiveSession_Info data structure, its SessionDetails variable gives you access to the EOS_SessionDetails_Info for that session. If not, you can use an EOS_HSessionDetails handle to call EOS_SessionDetails_CopyInfo to acquire a copy of the EOS_SessionDetails_Info data. Call EOS_SessionDetails_CopyInfo with an EOS_SessionDetails_CopyInfoOptions structure containing the following information:

On success, this will return a copy of the session's EOS_SessionDetails_Info, which contains the session's ID, the address of the host, and the number of open slots in the session. When you no longer need this information, call EOS_SessionDetails_Info_Release to free it.

Creating a Session

Creating a session is a two-step process.

First, establish the initial state and settings for the session locally with the EOS_Sessions_CreateSessionModification function. You'll need to pass in an EOS_Sessions_CreateSessionModificationOptions structure with the following information:

If the EOS_Sessions_CreateSessionModification call succeeds, it will return EOS_Success and the default EOS_HSessionModification you provided will contain a valid handle.

Second, continue to modify the session's initial setup (see the section on modifying a session) until you have made all the modifications you need. You can then complete the creation process by calling EOS_Sessions_UpdateSession with an EOS_Sessions_UpdateSessionOptions structure initialized as follows:

EOS_Sessions_UpdateSession is asynchronous, and will call your delegate (of type EOS_Sessions_OnUpdateSessionCallback) upon completion with an EOS_Sessions_UpdateSessionCallbackInfo data structure. On success, the local name that you provided will be paired with a searchable, unique ID string from the server.

Modifying a Session

To modify an existing session, first call EOS_Sessions_UpdateSessionModification with a pointer to a default EOS_HSessionModification object and an EOS_Sessions_UpdateSessionModificationOptions structure initialized as follows:

If this call succeeds, it will return EOS_Success, the modification will be applied to the local session, and the EOS_HSessionModification object you provided will now be a valid handle. If you are the session owner, you can use that handle to apply the local changes you've made to the back-end service's version of the session, by calling EOS_Sessions_UpdateSession. This function works for both new sessions (those that have not yet been created on the server) and pre-existing ones. The following functions modify different aspects of the session:

After modifying the session locally, you can update the session on the back-end service if you are the session owner. To do this, call EOS_Sessions_UpdateSession with an EOS_Sessions_UpdateSessionOptions containing the following information:

This operation will call your callback function, of type EOS_Sessions_OnUpdateSessionCallback, with an EOS_Sessions_UpdateSessionCallbackInfo data structure upon completion.

Custom Attributes

Sessions can contain user-defined data, called ttributes. Each attribute has a name, which acts as a string key, a value, an enumerated variable identifying the value's type, and a visibility setting. The following variable types are currently supported:

The following visibility types are available:

Accessing an Attribute

You can find out how many attributes a session has by calling EOS_SessionDetails_GetSessionAttributeCount with a valid EOS_HSessionDetails handle and an EOS_SessionDetails_CopySessionAttributeByIndexOptions containing the following information:

To get a copy of an attribute, call EOS_SessionDetails_CopySessionAttributeByIndex with a valid EOS_HSessionDetails handle and an EOS_SessionDetails_CopySessionAttributeByIndexOptions initialized as follows:

On success, this will return EOS_Success and your output parameter will contain a copy of the EOS_SessionDetails_Attribute structure corresponding to the attribute index you requested. This structure contains the Attribute's value and type in an EOS_Sessions_AttributeData data structure, and its visibility in an EOS_ESessionAttributeAdvertisementType enumerated value. When you no longer need this data, release it with EOS_SessionDetails_Attribute_Release.

Adding an Attribute

You can set up an attribute that you would like to add or modify by filling an EOS_Sessions_AttributeData data structure with the following information:

Once you have this data ready, call EOS_SessionModification_AddAttribute to add the attribute. You must provide your EOS_HSessionModification handle and an EOS_SessionModification_AddAttributeOptions, intialized as follows:

You can store up to EOS_SESSIONMODIFICATION_MAX_SESSION_ATTRIBUTES (currently 64) in a session, and each attribute's name can be up to EOS_SESSIONMODIFICATION_MAX_SESSION_ATTRIBUTE_LENGTH (currently 32) characters long.

Removing an Attribute

To remove an attribute, call EOS_SessionModification_RemoveAttribute with the EOS_HSessionModification handle for your session, and an EOS_SessionModification_RemoveAttributeOptions structure containing the following information:

Inviting Players to a Session

To invite another player to join an active session, a registered member of the session can call EOS_Sessions_SendInvite with an EOS_Sessions_SendInviteOptions structure containing the following data:

Once the server has processed the invitation request, your callback, of type EOS_Sessions_OnSendInviteCallback, will run with an EOS_Sessions_SendInviteCallbackInfo structure containing a result code. This result indicates success if there was no error in the process of sending the invitation; success does not mean that the remote user has accepted, or even seen, the invitation.

The remote user will receive notification of the invitation when it arrives, and the payload will provide the user ID that has been invited as well as the ID of the invitation itself. Upon receipt, use EOS_Sessions_CopySessionHandleByInviteId to retrieve the EOS_HSessionDetails handle from the invitation. You can use this handle to gain access to the session details data for the associated session, or to accept or reject the invitation. Once you are finished with the handle, call EOS_SessionDetails_Release to release it.

In order to receive this notification, you must register a callback with EOS_Sessions_AddNotifySessionInviteReceived. You only need to do this once, typically at startup, after which your callback will run as each invitation is received. When you no longer need notification, call EOS_Sessions_RemoveNotifySessionInviteReceived to remove your callback.

Accepting an Invitation

The Sessions Interface does not feature a dedicated function for accepting an invitation. You can join the session using the standard method with the EOS_HSessionDetails handle that you retrieved from the invitation. To request a list of all pending invitations, call EOS_Sessions_QueryInvites with an EOS_Sessions_QueryInvitesOptions data structure initialized as follows:

This operation is asynchronous. When it finishes, it will call your callback function, of type EOS_Sessions_OnQueryInvitesCallback, with an EOS_Sessions_QueryInvitesCallbackInfo data structure. On success, EOS will have all of the user's pending invitations cached locally. You can use EOS_Sessions_GetInviteCount to determine the number of invitations in the cache. Pass in an EOS_Sessions_GetInviteCountOptions structure with the following information:

This function runs locally and will return a uint32_t that represents the number of invitations currently in the cache. To get the ID of any cached invitation, call EOS_Sessions_GetInviteIdByIndex with an EOS_Sessions_GetInviteIdByIndexOptions containing the following information:

If EOS_Sessions_GetInviteIdByIndex returns EOS_Success, the output parameters you passed to it contain the invitation's ID as a null-terminated character string and the length of that string.

As desribed above, the EOS_Sessions_CopySessionHandleByInviteId function will provide an EOS_HSession handle which gives you access to the session details data for the associated session. You can then choose to accept the invitation by joining the session, ignore the invitation, or reject it. Once you are finished with the EOS_HSession handle, call EOS_SessionDetails_Release to release it.

Rejecting an Invitation

To reject an invitation, call EOS_Sessions_RejectInvite with an EOS_Sessions_RejectInviteOptions initialized as follows:

Upon completion, you will receive a call to your EOS_Sessions_OnRejectInviteCallback callback function with an EOS_Sessions_RejectInviteCallbackInfo data structure indicating success or failure. Successfully rejecting an invitation permanently deletes it from the system.

Discovering a Remote Session

To find a remote session, you need to configure a search, execute that search, then examine the results.

Configuring a Search

To begin a search, first call EOS_Sessions_CreateSessionSearch to create a search handle. Pass in an EOS_Sessions_CreateSessionSearchOptions structure, initialized as follows:

This function runs locally and will fill out the default search handle (of type EOS_HSessionSearch) on success. The next step is to configure the handle to perform a specific search with the criteria you require. EOS provides three methods to search for sessions:

• Session ID: Finds a single session with a known ID

• User ID: Finds all sessions involving a known user — presently limited to local users

• Attribute Data: Finds all sessions that match some user-defined filtering criteria

Configuring for Session ID

If you want a specific session and know its server-side ID, call EOS_SessionSearch_SetSessionId with your search handle and an EOS_SessionSearch_SetSessionIdOptions initialized as follows:

This is the only step required to configure a session ID search. Unlike the other search methods, this will never return more than one result.

Configuring for User ID

To find all sessions that involve a known user, call EOS_SessionSearch_SetTargetUserId with your search handle and an EOS_SessionSearch_SetTargetUserIdOptions containing the following information:

This is the only step required to configure a user ID search. Must be a local, logged-in user.

Configuring for Attribute Data

The most robust way to find sessions is to search based on a set of search parameters, which act as filters. Some parameters could be exposed to the user, such as enabling the user to select a certain game type or map, while others might be hidden, such as using the player's estimated skill level to find matches with appropriate opponents. This search method can take multiple parameters, and will only find sessions that pass through all of them. To set up a search parameter, call EOS_SessionSearch_SetParameter with your search handle and an EOS_SessionSearch_SetParameterOptions containing the following information:

This function can be called multiple times to set up multiple filters, all of which must be satisfied for a session to show up in the search results. The following table lists the types of comparisons you can use, what value types they work on, and what condition must be met in order to pass:

Executing a Search

To execute the search, call EOS_SessionSearch_Find with your search handle and an EOS_SessionSearch_FindOptions structure initialized as follows:

This is an asynchronous operation. When it finishes, your callback function, of type EOS_SessionSearch_OnFindCallback, will receive an EOS_SessionSearch_FindCallbackInfo structure notifying you of the success or failure of the search. Following successful completion, you can get copies of the search results from the EOS cache.

Examining Search Results

EOS_SessionSearch_GetSearchResultCount for a given EOS_HSessionSearch handle and EOS_SessionSearch_CopySearchResultByIndex will return the session details one by one via individual EOS_HSessionDetails handles.

After completing a successful search, use EOS_SessionSearch_GetSearchResultCount with your search handle to get the number of results that the search returned. You can then call EOS_SessionSearch_CopySearchResultByIndex to get a copy of the EOS_HSessionDetails handle associated with the active session at that index. This handle provides access to session details data, which you can use to display information about the session to the local user or determine whether or not to join the session using your own game logic. You must release the EOS_HSessionDetails handle with EOS_SessionDetails_Release when you no longer need it.

Joining a Session

You can join an existing session if you have a valid EOS_HSessionDetails handle to it by calling EOS_Sessions_JoinSession and providing an EOS_Sessions_JoinSessionOptions structure with the following information:

When the operation finishes, your callback function, of type EOS_Sessions_OnJoinSessionCallback, will receive an EOS_Sessions_JoinSessionCallbackInfo indicating success or failure. If the operation succeeds, EOS will create an active session on the joining client's system. As this new session is locally-owned, the joining user is responsible for destroying it once it is no longer needed.

Registering a Player

When a player joins the session, the session owner is responsible for registering the player with the session. This keeps the back-end service aware of the number of players so that it may stop advertising the session publicly when it is full. EOS accepts registration of multiple players at once through the EOS_Sessions_RegisterPlayers function. Call this function from the owning client with an EOS_Sessions_RegisterPlayersOptions structure containing the following data:

On completion, your callback of type EOS_Sessions_OnRegisterPlayersCallback will run with an EOS_Sessions_RegisterPlayersCallbackInfo parameter that indicates success or failure. If the call succeeds, the newly-registered players will receive access to some session management functionality, such as the ability to invite other players to the session. EOS does not provide notification when a player joins a session, so you must notify the owner when you join, or provide the owner with a way to detect when a player has successfully joined the session.

Leaving a Session

The Sessions Interface does not feature a dedicated function for leaving a session. To leave a session, destroy your local session through the standard method, using its local name.

Unregistering a Player

When a player leaves the session, the session's owner is responsible for unregistering the player. This enables the server to free up player slots so that future players can join. EOS accepts unregistration of multiple players at once through the EOS_Sessions_UnregisterPlayers function. Call this function from the owning client with an EOS_Sessions_UnregisterPlayersOptions structure containing the following data:

On completion, your callback of type EOS_Sessions_OnUnregisterPlayersCallback will run with an EOS_Sessions_UnregisterPlayersCallbackInfo parameter that indicates success or failure. If the call succeeds, the back-end service will revoke the session management access that those players received when they were originally registered. For example, players who are not registered with the session cannot invite others to join it. EOS does not provide notification of a player leaving a session, so you must notify the owner when you leave a session, or provide the owner with a way to detect that a player has left the game or disconnected.

Starting and Ending Play

A player can declare that a match has started or ended for a local active session. If that session maps to a session on the back-end service that the local player owns, the back-end version will also start or end play. While playing, the back-end service will automatically reject attempts to join a session if that session has Join in Progress disabled (see the section on Modifying a Session for more information). Although starting a session typically implies that a match has begun, the specific usage of this functionality is up to the game's developers.

To start play, call EOS_Sessions_StartSession with an EOS_Sessions_StartSessionOptions initialized as follows:

When the operation completes, your callback, of type EOS_Sessions_OnStartSessionCallback, will run with an EOS_Sessions_StartSessionCallbackInfo data structure indicating success or failure. If the operation succeeds, the session is considered "in progress" until you end play by calling EOS_Sessions_EndSession with an EOS_Sessions_EndSessionOptions containing the following information:

Upon completion, your EOS_Sessions_OnEndSessionCallback function will receive a call with an EOS_Sessions_EndSessionCallbackInfo data structure indicating success or failure. On success, the session is no longer considered "in progress" and will once again permit players to join. Ending a session does not remove players or destroy the session; it effectively returns to its pre-start state and remains usable, including the ability to start play again. If you intend to destroy the session, you do not need to call EOS_Sessions_EndSession first.

Destroying a Session

When you no longer need a session, you must destroy it using EOS_Sessions_DestroySession. Call this function with an EOS_Sessions_DestroySessionOptions data structure containing the following information:

When the destruction operation completes, you will receive a callback of type EOS_Sessions_OnDestroySessionCallback with an EOS_Sessions_DestroySessionCallbackInfo data structure. Upon success, the session will cease to exist and its name will be available for reuse. However, due to the asynchronous nature of this system, it is possible for a player to make a request after you have called EOS_Sessions_DestroySession but before the back-end service has destroyed the session. In this case, you may receive requests to join the session after having started the destruction operation. It is important to reject these players, or shut down the network to prevent them from joining the defunct session.

Mirroring Session Management on Remote Clients

Through the Sessions Interface, the session owner (the user who created the session) can manage the session's state as it exists on the back-end service. The life cycle of a session starts with its creation and ends with its destruction. Between those two events, the Sessions Interface can modify the session, change its privacy settings, send invitations, register and unregister players as they join and leave, and start, play, and end matches. A session's life cycle is not rigid; for example, sessions can modify their data at any time, and can start and end multiple matches.

In general, only the owner of the session can make modifications to session data on the back-end service. However, remote clients who join a session will have their own local view of the session, and this view does not automatically receive data updates about the back-end version. It is not required, but can be beneficial for remote clients to keep their local view in sync with the back-end session by mirroring the following function calls:

• EOS_Sessions_StartSession

• EOS_Sessions_EndSession

• EOS_Sessions_RegisterPlayers

• EOS_Sessions_UnregisterPlayers

These functions will modify the local state of the session on remote (non-owner) clients without affecting the back-end service's version.

Usage Limitations

Please consult the Service Usage Limitations page for information about usage limits that you should observe to maintain performance and speed.