Class EOSSessionsManager

Namespace

PlayEveryWare.EpicOnlineServices.Samples

Class EOSSessionsManager is a simplified wrapper for EOS Sessions Interface.

public class EOSSessionsManager : IEOSSubManager

Inheritance

object

EOSSessionsManager

Constructors

EOSSessionsManager()

public EOSSessionsManager()

Fields

INVALID_NOTIFICATIONID

public const ulong INVALID_NOTIFICATIONID = 0

Field Value

ulong

OnPresenceChange

Event to inform UI that it should refresh displayed Friends and Joining/Inviting buttons.

public UnityEvent OnPresenceChange

Field Value

UnityEvent

SessionInviteAcceptedNotificationHandle

public ulong SessionInviteAcceptedNotificationHandle

Field Value

ulong

SessionInviteNotificationHandle

public ulong SessionInviteNotificationHandle

Field Value

ulong

SessionJoinGameNotificationHandle

public ulong SessionJoinGameNotificationHandle

Field Value

ulong

Properties

IsUserLoggedIn

Indicates if OnLoggedIn() has been called since last not being logged in.

public bool IsUserLoggedIn { get; }

Property Value

bool

UIOnSessionRefresh

After a successful RefreshSession(string) and PlayEveryWare.EpicOnlineServices.Samples.EOSSessionsManager.OnRefreshSessionFindSessionsCompleteCallback(SessionSearchFindCallbackInfo@) callback call, this is run to inform UI of the updated Session information. This should be subscribed to by the program's UI.

public Action<Session, SessionDetails> UIOnSessionRefresh { get; set; }

Property Value

Action<Session, SessionDetails>

Methods

AcceptLobbyInvite(bool)

Accepts the CurrentInvite and attempts to JoinSession(SessionDetails, bool, Action<Result>).

TODO: This should use the invitation to respond to as an argument.

public void AcceptLobbyInvite(bool invitePresenceToggled)

Parameters

invitePresenceToggled bool

If true, the Session will be joined as the Presence Session for this user.

CreateSession(Session, SessionsManagerCreateSessionCallback, bool)

public bool CreateSession(Session session, SessionsManagerCreateSessionCallback createSessionCallback = null, bool presence = false)

Parameters

session Session

createSessionCallback SessionsManagerCreateSessionCallback

presence bool

Returns

bool

DeclineLobbyInvite()

Declines the most recent invitation.

TODO: This should use the invitation to respond to as an argument. If the user invited to two things, this will only pop the most recent one, which might not be the thing to decline.

public void DeclineLobbyInvite()

DestroySession(string, SessionsManagerDestroySessionCallback)

Indicates that a Session should be "destroyed". This informs Epic Game Services that this local user is leaving a Session. PlayEveryWare.EpicOnlineServices.Samples.EOSSessionsManager.OnDestroySessionCompleteCallback(DestroySessionCallbackInfo@) runs with results, which should then locally remove all of the Session's information. If this user is the Owner of the Session, the Session is destroyed with EOS Game Services, and every member should leave it.

public void DestroySession(string name, SessionsManagerDestroySessionCallback destroySessionCallback = null)

Parameters

name string

The local name of the Session to destroy.

destroySessionCallback SessionsManagerDestroySessionCallback

EndSession(string)

Ends an existing Session with EOS Game Services. This is not used to leave or destroy Sessions. A Session does not need to "End" in order to be left or destroyed. This is mostly used for standardizing a state across clients, but if AllowJoinInProgress is set to false, then users can only join it if it hasn't been started. This will set the SessionState to OnlineSessionState.Ending, and then soon after OnlineSessionState.Ended. Update() will notice the change in State and inform the UI to update. Calls to SessionsInterface.EndSession(ref EndSessionOptions, object, OnEndSessionCallback), with the ClientData param containing the local name of the Session to end. PlayEveryWare.EpicOnlineServices.Samples.EOSSessionsManager.OnEndSessionCompleteCallback(EndSessionCallbackInfo@) handles the callback.

TODO: Answer - can users see this if it has been ended and AllowJoinInProgress is false?

public void EndSession(string name)

Parameters

name string

The local name of the Session to end.

GetCurrentInvite()

Accessor for retriving the Session that is currently being operated on in regards to invitation.

public Session GetCurrentInvite()

Returns

Session

Currently acted upon Session, in regards to invitation.

GetCurrentSearch()

Accessor for the most recent search executed by the UI. This is separate from P2PSessionRefreshSessionSearch.

public SessionSearch GetCurrentSearch()

Returns

SessionSearch

The most recent search.

GetCurrentSessions()

Accessor for all Current Session. These are all Sessions that are locally joined.

public Dictionary<string, Session> GetCurrentSessions()

Returns

Dictionary<string, Session>

A dictionary lookup of "local Session name" to Session object.

GetInvites()

Accessor for retrieving Invites, which are invites sent to the user.

public Dictionary<Session, SessionDetails> GetInvites()

Returns

Dictionary<Session, SessionDetails>

All Invites sent to the user.

HasActiveLocalSessions()

Determines if any Sessions are joined.

TODO: This is unused, only detects Sessions that aren't locally owned. This should likely be removed. Ironically it does not determine if there are any ActiveSessions.

public bool HasActiveLocalSessions()

Returns

bool

True if a local Session has been joined.

HasPresenceSession()

Determines if any local Sessions are Presence enabled. If KnownPresenceSessionId is set and the Session is still available, returns true. Otherwise uses the SessionsInterface.CopySessionHandleForPresence(ref CopySessionHandleForPresenceOptions, out SessionDetails) to attempt to find a local Presence enabled Session. If found, caches the Session's Id in KnownPresenceSessionId.

TODO: This does not actually function properly in the KnownPresenceSessionId scenario. The returned value is an Id, not the local name of the Session. The cache look up will never succeed, rework.

public bool HasPresenceSession()

Returns

bool

Returns true if there is a local Session with Presence enabled.

InviteToSession(string, ProductUserId)

Sends an invitation to a user with EOS Game Services to join a Session.

public void InviteToSession(string sessionName, ProductUserId friendId)

Parameters

sessionName string

The local Session name to invite the user to.

friendId ProductUserId

The ProductUserId of the user to invite. TODO: Not necessarily a friend.

IsPresenceSession(string)

Determines if a local Session with the provided id is a Presence Session.

public bool IsPresenceSession(string id)

Parameters

id string

The Session Id to check.

Returns

bool

True if a local Session is found with the id, and it is a Presence Session.

JoinSession(SessionDetails, bool, Action<Result>)

Attempts to join an online Session. The results are handled by PlayEveryWare.EpicOnlineServices.Samples.EOSSessionsManager.OnJoinSessionListener(JoinSessionCallbackInfo@,SessionDetails,System.Action{Result}).

public void JoinSession(SessionDetails sessionHandle, bool presenceSession, Action<Result> callback = null)

Parameters

sessionHandle SessionDetails

A handle to the Session to join.

presenceSession bool

If true, then when the Session is joined it'll be set to Presence enabled. There can only be one Presence enabled Session at a time.

callback Action<Result>

Additional callback to run with the results of the operation. Invoked in PlayEveryWare.EpicOnlineServices.Samples.EOSSessionsManager.OnJoinSessionListener(JoinSessionCallbackInfo@,SessionDetails,System.Action{Result})

LeaveAllSessions()

Leaves all Sessions currently joined by using DestroySession(string).

public void LeaveAllSessions()

MakeSessionHandleByEventId(ulong)

Uses a provided uiEventId to get a SessionDetails object. This will only return a value if the provided Id has not yet been called with AcknowledgeEventId(Result). After making the Session handle, AcknowledgeEventId(Result) should be called with this id.

public SessionDetails MakeSessionHandleByEventId(ulong uiEventId)

Parameters

uiEventId ulong

The id to create off of.

Returns

SessionDetails

If an event is available with the provided id, returns SessionDetails for the Session. Otherwise returns null.

MakeSessionHandleByInviteId(string)

Creates a SessionDetails handle based on an invitation Id. This can be used to translate the provided information from an invitation to a more detailed form. After the returned object is no longer useful, call SessionDetails.Release to free the memory.

public SessionDetails MakeSessionHandleByInviteId(string inviteId)

Parameters

inviteId string

The invitation id to create a Session handle from.

Returns

SessionDetails

If an invitation Id that hasn't been released yet is found, then return that. Otherwise returns null.

ModifySession(Session, Action)

Saturates an attempt to modify a Session that this user is the Owner of. Assumes there is a local Session present in CurrentSessions, which is a different object than the session. By looking up the Session in the EOS SDK with a matching local Session name, and comparing it to the changes in session, this calls to SessionsInterface.UpdateSession(ref UpdateSessionOptions, object, OnUpdateSessionCallback).

TODO: The session argument should be replaced with another type of object to indicate its purpose. It is unclear and easily problematic that it looks like the same object can be used to modify the Session.

public bool ModifySession(Session session, Action callback = null)

Parameters

session Session

A new Session object that can be used to compare to the local Session to determine changes. Should be a different object than the existing local Session.

callback Action

Optional callback to run after an update.

Returns

bool

True if successfully attempting to change the Session. Does not indicate that the modification was successful, just that the attempt to create a modification was successful.

OnJoinSessionAcceptedListener(ref JoinSessionAcceptedCallbackInfo)

Listener notification method for when a Session is joined. UPon firing, this calls OnJoinGameAcceptedByEventId(ulong) to join the Session.

TODO: When is this called versus OnJoinGameAcceptedListener(ref JoinGameAcceptedCallbackInfo)? TODO: At what point does this get called in a joining life cycle?

public void OnJoinSessionAcceptedListener(ref JoinSessionAcceptedCallbackInfo data)

Parameters

data JoinSessionAcceptedCallbackInfo

Callback information from the attempted join.

OnLoggedIn()

Subscribes to invitations and Peer2Peer message requests and prepares internal states for this manager to be used. This should be called after a successful Connect login.

public void OnLoggedIn()

OnLoggedOut()

Unsubscribes from invitations and Peer2Peer message requests and clears internal states. This can be run before or after a successful logout, or preparing to shut down the application. This must be called in order to instruct the EOS SDK to stop notifying from the messages subscribed to in OnLoggedIn(). After calling this function, OnLoggedIn() must be called to resume full Sessions functionality.

public void OnLoggedOut()

OnSessionInviteAcceptedListener(ref SessionInviteAcceptedCallbackInfo)

Notification handler for a Session Invite being accepted by the local user.

public void OnSessionInviteAcceptedListener(ref SessionInviteAcceptedCallbackInfo data)

Parameters

data SessionInviteAcceptedCallbackInfo

Callback information about the most recent invitation.

OnSessionInviteReceivedListener(ref SessionInviteReceivedCallbackInfo)

Notification handler for a Session Invite being received by the local user.

public void OnSessionInviteReceivedListener(ref SessionInviteReceivedCallbackInfo data)

Parameters

data SessionInviteReceivedCallbackInfo

Callback information about the most recent invitation.

RefreshSession(string)

Identifies a local Session by its localSessionName, gets its EOS Game Services Id, and then attempts to use the Session search API to look for this Session on the Epic Online Services back end. If it is able to find it, then a UI refresh action is called to inform the UI to update the Session's displayed information. While similar to SearchById(string), this function uses P2PSessionRefreshSessionSearch instead of CurrentSearch, and uses PlayEveryWare.EpicOnlineServices.Samples.EOSSessionsManager.OnRefreshSessionFindSessionsCompleteCallback(SessionSearchFindCallbackInfo@) as the callback to handle the results.

TODO: This should be designed to work regardless of what the "public" status of the Session is. Currently only functions for Public and Join by Presence. Must also function for invites.

public void RefreshSession(string localSessionName)

Parameters

localSessionName string

RegisterPlayer(string, ProductUserId)

Registers a user to the Session. Users will be able to query the identities of Registered members in a Session, and Registering is required for EOS Game Services to manage Maximum Users configurations. When called by the Owner of a Session, the Registered user is reflected with EOS Game Services. Other users should be informed by the Owner to Register users, so they have their information. P2P messages can be used to inform the Owner and users when to run this method.

public void RegisterPlayer(string sessionName, ProductUserId userIdToRegister)

Parameters

sessionName string

The name of the local Session to register the user to.

userIdToRegister ProductUserId

The ProductUserId of the user to Register to the Session. Uses sessionName for ClientData to identify the Session to register the user to.

RegisterPlayers(string, ProductUserId[])

Registers possibly multiple users to the Session. Users will be able to query the identities of Registered members in a Session, and Registering is required for EOS Game Services to manage Maximum Users configurations. When called by the Owner of a Session, the Registered user is reflected with EOS Game Services. Other users should be informed by the Owner to Register users, so they have their information. P2P messages can be used to inform the Owner and users when to run this method.

public void RegisterPlayers(string sessionName, ProductUserId[] userIdsToRegister)

Parameters

sessionName string

The name of the local Session to register the user to.

userIdsToRegister ProductUserId[]

The ProductUserId of the users to Register to the Session. If this array is empty, the function exits without performing an operation. Uses sessionName for ClientData to identify the Session to register the user to.

Search(List<SessionAttribute>, string)

Performs an online Search to look up a Session, where all attributes provided are met. PlayEveryWare.EpicOnlineServices.Samples.EOSSessionsManager.OnFindSessionsCompleteCallback(SessionSearchFindCallbackInfo@) is called with the results. A handle for retriving results will be stored in CurrentSearch.

TODO: This should run a callback or return a Result in case of errors when trying to set up the search. TODO: Only finds up to 10 results. Should have some method for finding next sets of results.

public void Search(List<SessionAttribute> attributes, string bucketId = "SessionSample:Region")

Parameters

attributes List<SessionAttribute>

A list of Session Attributes to act as filters.

bucketId string

The BucketID to search for. Results will only include Sessions created with this as their exact BucketId.

SearchById(string, Action<SessionSearch>)

Searches online for a Session with the exact Id. This can only return zero or one results. Like other online searching methods, this can only find Sessions that are marked as either Public or JoinViaPresence. It won't be able to find private invite only Sessions. PlayEveryWare.EpicOnlineServices.Samples.EOSSessionsManager.OnFindSessionsCompleteCallback(SessionSearchFindCallbackInfo@) is called with the results. A handle for retriving results will be stored in CurrentSearch. This is the EOS Game Services id, shared for all users.

public void SearchById(string sessionId, Action<SessionSearch> onSearchCompleted = null)

Parameters

sessionId string

The Session Id to search for.

onSearchCompleted Action<SessionSearch>

Optional action to run when the search results are received.

SetInviteSession(Session, SessionDetails)

Sets a specific set of Session information as the currently acted upon Session. If there are any existing Session invites, bring the most recent one up by calling PopLobbyInvite(). Otherwise sets the current invitation to the one passed in to this function. The CurrentInvite is used to automatically join if a joined Session has this id.

TODO: This assumes a user is only invited once to a Session, which is not necessarily true. TODO: This has awkward management of the most recent invitation object.

public void SetInviteSession(Session session, SessionDetails sessionDetails)

Parameters

session Session

Session information to join. Mostly used for its name and id.

sessionDetails SessionDetails

Handle to additional details.

TODO: This (sessionDetails) should be readily available for any Session the user has been invited to, and probably shouldn't be passed as an argument.

SetJoinInfo(string, bool)

Sets the current user's Social Presence.

TODO: This is not called by this manager. It either should be utilized, or moved to another manager, perhaps some sort of EOSPresenceManager.

public static void SetJoinInfo(string joinInfo, bool onLoggingOut = false)

Parameters

joinInfo string

If provided, this string will be displayed to users in the Social Overlay as the local user's current presence. This can be used to indicate things like current level, looking for party status, etc.

onLoggingOut bool

Indicates if the user is currently attempting or has already logged out. If true, then if there's an error while trying to change the local user's presence, the error will be ignored.

TODO: The error handling in both scenarios is almost identical. Perhaps an error state should be returned in the situation where this is false and an error is encountered.

StartSession(string)

Starts an existing Session with EOS Game Services. This is not used to create new Sessions. This is mostly used for standardizing a state across clients, but if AllowJoinInProgress is set to false, then users can only join it if it hasn't been started. This will set the SessionState to OnlineSessionState.Starting, and then soon after OnlineSessionState.InProgress. Update() will notice the change in State and inform the UI to update. Calls to SessionsInterface.StartSession(ref StartSessionOptions, object, OnStartSessionCallback), with the ClientData param containing the local name of the Session to start. PlayEveryWare.EpicOnlineServices.Samples.EOSSessionsManager.OnStartSessionCompleteCallBack(StartSessionCallbackInfo@) handles the callback.

TODO: Answer - can users see this if it has been ended and AllowJoinInProgress is false?

public void StartSession(string name)

Parameters

name string

The local name of the Session to start.

SubscribeToGameInvites()

Subscribes to notifications for Game/Session invitations. This must be called for the EOS Game Services to know to send messages to the local user regarding being invited. The application should call UnsubscribeFromGameInvites() before the application finishes shutting down, or when it is no longer desired to listen to and respond to game invites.

public void SubscribeToGameInvites()

TryGetPresenceSession(out Session)

Attempts to get a locally joined Presence enabled Session. Users can only be in one Presence enabled Session at a time. The current Id is stored in KnownPresenceSessionId.

public bool TryGetPresenceSession(out Session foundSession)

Parameters

foundSession Session

Out parameter with the Session, if found.

Returns

bool

True if a Presence Session is found. False otherwise.

TryGetSession(string, out Session)

Tries to get a local Session that is joined with the provided name.

public bool TryGetSession(string name, out Session session)

Parameters

name string

The local name of the Session to try to get. This name is unique to the user.

session Session

Out parameter with the Session, if found.

Returns

bool

True if a Session with the provided name is found.

TryGetSessionById(string, out Session)

Tries to get a local Session that is joined with the provided id.

public bool TryGetSessionById(string id, out Session session)

Parameters

id string

The id of the Session to try to get. This is the EOS Game Services id, shared for all users.

session Session

Out parameter with the Session, if found.

Returns

bool

True if a Session with the provided name is found.

UnregisterPlayer(string, ProductUserId)

Unregisters a user from a Session. This will then inform the user to leave the room with P2P messages. An unregistered user will no longer be part of the Session with EOS Game Services. Uses sessionName as the ClientData to identify the local Session name to unregister the user from. When called by the Owner of a Session, the user is unregistered from the Session in EOS Game Services. Other users should call this to keep members of the Session current. P2P messages can be used to inform the Owner and users when to run this method.

public void UnregisterPlayer(string sessionName, ProductUserId userIdToUnRegister)

Parameters

sessionName string

Local Session name to unregister the user from.

userIdToUnRegister ProductUserId

The ProductUserId of the user to unregister.

UnregisterPlayers(string, ProductUserId[])

Unregisters a user from a Session. This will then inform the user to leave the room with P2P messages. An unregistered user will no longer be part of the Session with EOS Game Services. Uses sessionName as the ClientData to identify the local Session name to unregister the user from. When called by the Owner of a Session, the user is unregistered from the Session in EOS Game Services. Other users should call this to keep members of the Session current. P2P messages can be used to inform the Owner and users when to run this method.

public void UnregisterPlayers(string sessionName, ProductUserId[] userIdsToUnRegister)

Parameters

sessionName string

Local Session name to unregister the user from.

userIdsToUnRegister ProductUserId[]

The ProductUserId of the users to unregister. If this array is empty, the function exits without performing an operation.

UnsubscribeFromGameInvites()

Removes all notification handles relating to Game/Session Invites.

public void UnsubscribeFromGameInvites()

Update()

Checks for new Peer2Peer messages for Session management, as well as updating the OnlineSessionState of ActiveSessions. This Manager is not a MonoBehaviour, so this function should be run by the program every update.

public bool Update()

Returns

bool

Returns true if there are any detected changes to the Active Sessions. This can inform the UI to update.