Photon C++ Client API: Client Class Reference

Constructor.

Parameters

listener	Reference to the application's implementation of the Listener callback interface. Has to be valid for at least the lifetime of the Client instance, which is created by this constructor.
applicationID	A unique ID of your application. Must match one of the appIDs in your dashboard for Photon Cloud. This parameter gets ignored by Photon Server.
appVersion	Only clients that use the exact same appVersion can see each other. You can use different values to separate clients with the same appID from each other that should not be able to be matched with each other or to even see each other, i.e. incompatible versions of your game or public, closed-beta, QA, staging and dev clients. This parameter gets ignored by Photon Server.
connectionProtocol	The protocol to use to connect to the Photon servers. Must match one of the constants specified in ConnectionProtocol.
autoLobbyStats	Pass true, if you want to automatically receive updates for the lobby stats, false otherwise. Call opLobbyStats() to explicitly request a lobby stats update.
regionSelectionMode	Determines how the Photon Cloud Region to which the Client connects should be selected. Must match one of the constants specified in RegionSelectionMode. This parameter gets ignored when connecting to Photon Server.
useAlternativePorts	Determines if the the standard or the alternative port range should be used. This parameter currently is only relevant when ConnectionProtocol::UDP is passed for parameter connectionProtocol and gets ignored otherwise. A router or firewall might block connections that use one port-range but don't block connections that use the other, so when connecting with one range fails, then you may want to try with the other one.

See also

Listener, ConnectionProtocol, RegionSelectionMode, NetworkPort

Destructor.

This function starts establishing a connection to a Photon server. The servers response will arrive in Listener::connectReturn().

The connection is successfully established when the Photon client received a valid response from the server. The connect-attempt fails when a network error occurs or when server is not responding. A call to this function starts an asynchronous operation. The result of this operation gets returned through the Listener::connectReturn() callback function. If this function returns false, then the connect-attempt has already failed locally. If it returns true, then either Listener::connectionErrorReturn() or Listener::connectReturn() will get called. The operation was successful, when Listener::connectReturn() got called with errorCode==0.

Parameters

authenticationValues	An instance of class AuthenticationValues
username	The users display name as shown to other users - not to be confused with the users unique ID for identification and authentication purposes, which is part of the AuthenticationValues
serverAddress	A null terminated string containing the IP address or domain name and optionally the port number to connect to. IP addresses can be in IPv4 or IPv6 format, examples: "192.168.0.1", "192.168.0.1:5055", "udp.gameserver.com", "udp.gameserver.com:5055", "[2002:C0A8:1::]", "[2002:C0A8:1::]:5055". Note that IPv6 addresses must include square brackets to indicate where the address itself ends and the port begins. If no port is given, then the default port for the chosen protocol and server type will be used.
serverType	One of the values in ServerType. Must match the type of the Photon server that is reachable at the given address and port. Should be ServerType::NAME_SERVER for Photon Cloud and ServerType::MASTER_SERVER for self-hosted Photon Server instances. You should NOT directly pass the address of a regions master server with Photon Cloud, but always connect to the name server.

Returns

true, if it could successfully start establishing a connection (the result will be passed in a callback function in this case) or false, if an error occurred and the connection could not be established (no callback function will be called then).

See also

disconnect(), NetworkPort

This function generates a disconnection request that will be sent to the Photon server. The servers response will arrive in Listener::disconnectReturn().

If the disconnection is completed successfully, then the Listener::disconnectReturn() callback will be called.

Remarks

If a game room is joined, when this function gets called, then the local player leaves that room as if opLeaveRoom() has been called with parameter 'willComeBack' set to 'true'. Please see there for further information about leaving rooms. However no call to Listener::leaveRoomReturn() will happen when leaving a game room is triggered through a call to disconnect().

See also

connect(), opLeaveRoom()

This function executes the PhotonPeer internal processes. Call this regularly!

This function is meant to be called frequently, like once per game loop. It handles the internal calls for keeping the PhotonPeer communication alive, and will take care of sending all local outgoing acknowledgements and messages, as well as dispatching incoming messages to the application and firing the corresponding callbacks. Internally service() calls the following functions:

1. serviceBasic()
2. dispatchIncomingCommands() (called withing a loop until all incoming commands have been dispatched.)
3. sendOutgoingCommands() (called withing a loop until everything queued for sending has been sent.)

service() is provided for convenience. If you need to tweak the performance, you can ignore service() and call its three subfunctions directly with individual time intervals, to gain more control over the internal communication process. For instance, calling sendOutgoingCommands() more rarely will result in less packets to be generated, as more commands will be accumulated into a single packet. See sendOutgoingCommands() for more information on efficiency.

For situations where you want to keep the connection alive, but can't process incoming messages (e.g. when loading a level), you can temporarily pass false for dispatchIncomingCommands to skip the calls to dispatchIncomingCommands(). Incoming commands will be stored in the incoming queue until they are dispatched again.

Parameters

dispatchIncomingCommands

true = dispatchIncomingCommands() will be called; false = dispatchIncomingCommands() won't be called, default is true

This function takes care of exchanging data with the system's network layer.

You only need to call this function in case you choose not to use service(), but call the subfunctions of service() directly. Please see the documentation of service() for more information.

serviceBasic() is called from within service(). If you decide not to use service(), then serviceBasic() needs to be called frequently, like once per game loop.

See also

service()

Sends a custom operation to a custom Server, using reliable or unreliable Photon transmission.

Allows the client to send a custom operation to the Photon server (which has to be modified accordingly). The Server can be extended and modified for special purposes like server side collision detection or a consistent world.

You need to be connected (see connect()) prior to calling opCustom().

Parameters

operationRequest	holds the payload of the operation
sendReliable	= operation will be sent reliably; false = no resend in case of packet loss - will be ignored, when not using udp as protocol
channelID	the logical channel, default is 0. See Fragmentation and Channels for more information.
encrypt	true = encrypt message; false = no encryption

Returns

true, if successful, false otherwise

This function initiates the transmission of outgoing commands.

Any Photon function that generates messages will store these messages as a "command" in an outgoing queue for later transmission. Commands can either be explicitly created operations generated for example by opCustom() or internally generated messages like acknowledgements for reliable messages from other players. sendOutgoingCommands() will initiate the data transmission by passing the outgoing commands to the system's sockets for immediate transmission.

In case of UDP sendOutgoingCommands() will also split the commands into multiple packets if needed and/of aggregate multiple commands together into one packet, if possible. Because of the latter calling sendOutgoingcommands() more rarely will result in less overhead, as there will be fewer packets for the clients to be sent and processed. The underlying platform can also limit the frequency in which outgoing packets can be sent and received. The downside of lower sending frequencies is a higher latency, until messages are exchanged and acknowledged, which may lead to a jerky gameplay.

To help you keeping track of the incoming and outgoing queues at development time and adjust your sending frequency, there will be a warning message sent to your debugReturn callback if a queue has exceeded the warning threshold.

Note

While service() is calling serviceBasic() implicitly, you will have to regularly call it yourself explictly , when you use sendOutgoingCommands() and dispatchIncomingCommands() directly instead.

Usually you don't have to call sendOutgoingCommands() this explicitly, as this is done within service().

See also

service()

Sends only ACKs (UDP) or Ping (TCP) instead of queued outgoing commands. Useful to pause sending actual data.

Note

While service() is calling serviceBasic() implicitly, you will have to regularly call it yourself explictly , when you use sendAcksOnly() and dispatchIncomingCommands() instead.

Checks for incoming commands waiting in the queue, and dispatches a single command to the application.

Dispatching means, that if the command is an operation response or an event, the appropriate callback function will be called). dispatchIncomingCommands() will also take care of generating and queuing acknowledgments for incoming reliable commands. Please note that this function will only dispatch one command per all. If you want to dispatch every single command which is waiting in the queue, call dipatchIncomingCommands() within a while loop, until its return code is false.

Note

While service() is calling serviceBasic() implicitly, you will have to regularly call it yourself explictly, when you use sendOutgoingCommands() and dispatchIncomingCommands() directly instead.

Returns

true if it has successfully dispatched a command, false otherwise (for example, when there has not been any command left in the queue, waiting for dispatching).

See also

service()

This will fetch the server's timestamp and update the approximation for getServerTime() and getServerTimeOffset().

The server time approximation will NOT become more accurate by repeated calls. Accuracy currently depends on a single roundtrip which is done as fast as possible.

The command used for this is immediately acknowledged by the server. This makes sure the roundtriptime is low and the timestamp + roundtriptime / 2 is close to the original value.

Creates new instances of TrafficStats and starts a new timer for those.

Resets traffic stats values that can be maxed out.

Returns a string of the most interesting connection statistics. When you have issues on the client side, these might contain hints about the issue's cause.

Parameters

all	If true, Incoming and Outgoing low-level stats are included in the string.

Returns

stats as a string.

Joins the specified lobby.

This function sends a request to the server to join the specified lobby. If it returns true, then Listener::joinLobbyReturn() gets called when the operation has successfully been finished. Please see Matchmaking Guide regarding the differences between the various lobby types.

Remarks

A Client instance can only be inside one room at a time. Therefor this operation will fail and return false, if the client is already inside another lobby or inside a game room. Leave the other room first, before calling this operation.

For the same reason entering a game room implicitly causes the client to leave the lobby, so if you want to return to the previously joined lobby after leaving that game room, you must explicitly join it again.

Note

If the auto-join lobby feature is enabled (which is the default! - it can be turned off by a call to setAutoJoinLobby()), then the client automatically joins the default lobby when successfully connecting to Photon and when leaving a game room. Call setAutoJoinLobby(false) before calling connect() for opJoinLobby() to work properly.

Parameters

lobbyName	the unique name of the lobby to join
lobbyType	one of the values in LobbyType

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

opLeaveLobby(), setAutoJoinLobby(), getAutoJoinLobby(), Listener::joinLobbyReturn()

Leaves the currently joined lobby.

This function sends a request to the server to leave the currently joined lobby. If it returns true, then Listener::leaveLobbyReturn() gets called when the operation has successfully been finished.

Remarks

This operation will fail and return false if the client does not currently reside inside any lobby.

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

opJoinLobby(), Listener::leaveLobbyReturn()

Creates and enters a new game room.

This function sends a request to the server to create the specified game room. If it returns true, then Listener::createRoomReturn() gets called when the operation has been finished.

If you don't want to create a unique room name, pass L"" as name and the server will assign a roomName (a GUID as string). Room names are unique.

A room will be attached to the lobby that you have specified in the passed in options. Leave the lobby name empty to attach the room to the lobby you are now in. If you are in no lobby, then the default lobby is used.

Multiple lobbies can help to separate players by map or skill or game type. Each room can only be found in one lobby (no matter if defined by name and type or as default).

Remarks

A Client instance can only be inside one room at a time. Therefor this operation will fail and return false, if the client is already inside another game room. Any lobby the client currently resides in will implicitly be left when entering a game room.

If a room with the specified name does already exist, then the operation will fail and Listener::createRoomReturn() will get called with an error code.

Parameters

gameID	The name to create a room with. Must be unique and not in use or the room can't be created. If this is an empty string, then the server will assign a GUID as name.
options	An instance of RoomOptions, that can be used to specify various options for room creation.
expectedUsers	Sets a list of user IDs for which the server should reserve slots. Those slots can't be taken by other players.

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

opJoinOrCreateRoom(), opJoinRoom(), opJoinRandomRoom(), opLeaveRoom(), MutableRoom, RoomOptions, Listener::createRoomReturn()

Joins the specified game room or creates and enters a new game room with the specified ID if such a room does not exist yet.

This function sends a request to the server to join the specified game room if exists and to create it otherwise. If it returns true, then Listener::joinOrCreateRoomReturn() gets called when the operation has been finished.

Unlike opJoinRoom(), this operation does not fail if the room does not exist. This can be useful when you send invitations to a room before actually creating it: Any invited player (whoever is first) can call this and on demand, the room gets created implicitly.

This operation does not allow you to re-join a game. To return to a room, use opJoinRoom() with the playerNumber which was assigned previously.

Remarks

A Client instance can only be inside one room at a time. Therefor this operation will fail and return false, if the client is already inside another game room. Any lobby the client currently resides in will implicitly be left when entering a game room.

If the room is full or closed, then this operation will fail and Listener::joinOrCreateRoomReturn() will get called with an error code.

Parameters

gameID	A unique identifier for the game room to join or create. If this is an empty string, then the server will create a room and assign a GUID as name.
options	An instance of RoomOptions, that can be used to specify various options for room creation. These options will be ignored when the room already exists.
cacheSliceIndex	Allows to request a specific cache slice - all events in that cache slice and upward slices will be published to the client after joining the room - see Lite::EventCache for further information about cached events.
expectedUsers	Sets a list of user IDs for which the server should reserve slots. Those slots can't be taken by other players. If the room already exists, then this list will be merged with any previously set list of expected users for this room.

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

opCreateRoom(), opJoinRoom(), opJoinRandomRoom(), opLeaveRoom(), MutableRoom, RoomOptions, Listener::joinOrCreateRoomReturn()

Joins the specified game room.

This function sends a request to the server to join the specified game room. If it returns true, then Listener::joinRoomReturn() gets called when the operation has been finished.

This function is useful when you are using a lobby to list rooms and know their names. A room's name has to be unique (per region and app version), so it does not matter which lobby the room is in.

It's usually better to use opJoinOrCreateRoom() for invitations. Then it does not matter if the room is already setup.

Remarks

A Client instance can only be inside one room at a time. Therefor this operation will fail and return false, if the client is already inside another game room. Any lobby the client currently resides in will implicitly be left when entering a game room.

If a room with the specified name does not exist or if the room is full or closed, then this operation will fail and Listener::joinRoomReturn() will get called with an error code.

Parameters

gameID	A unique identifier for the game room to join.
rejoin	Needs to be false if this is the initial join of this room for this client and true if this is a rejoin.
cacheSliceIndex	Allows to request a specific cache slice - all events in that cache slice and upward slices will be published to the client after joining the room - see Lite::EventCache for further information about cached events.
expectedUsers	Sets a list of user IDs for which the server should reserve slots. Those slots can't be taken by other players. This list will be merged with any previously set list of expected users for this room.

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

opCreateRoom(), opJoinOrCreateRoom(), opJoinRandomRoom(), opLeaveRoom(), MutableRoom, Listener::joinRoomReturn()

Joins a random game room.

This function sends a request to the server to join a random game room. If it returns true, then Listener::joinRandomRoomReturn() gets called when the operation has been finished.

Remarks

A Client instance can only be inside one room at a time. Therefor this operation will fail and return false, if the client is already inside another game room. Any lobby the client currently resides in will implicitly be left when entering a game room.

If no rooms are fitting or available (all full, closed or not visible), then this operation will fail and Listener::joinRandomRoomReturn() will get get called with an error code.

Parameters

customRoomProperties	Used as a filter for matchmaking. The server only considers rooms for which all custom properties match the specified filters. Note that only those custom room properties that have been specified for listing in the lobby will be used for matchmaking, so a rooms custom property can only match a specified filter if it got specified in the list of properties to show in the lobby. All values must be exact matches.
maxPlayers	Must match the value of a rooms maxPlayers property for that room to be considered for matchmaking.
matchmakingMode	Needs to be one of the values in MatchMakingMode
lobbyName	The name of the lobby in which matchmaking should take place. Only rooms that are listed in that lobby will be considered for matchmaking.
lobbyType	The type of the lobby in which matchmaking should take place. Needs to be one of the values in LobbyType. Note that a lobby with the same name, but a different type can not be considered for matchmaking, as a lobby name only needs to be unique among lobbies of the same type.
sqlLobbyFilter	Only used for LobbyType::SQL_LOBBY. This allows 'bigger', 'less', 'or' and 'and' combinations for filtering against certain room properties.
expectedUsers	Sets a list of user IDs for which the server should reserve slots. Those slots can't be taken by other players. This list will be merged with any previously set list of expected users for this room.

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

opCreateRoom(), opJoinOrCreateRoom(), opJoinRandomRoom(), opLeaveRoom(), MutableRoom, Listener::joinRoomReturn(), Matchmaking and Lobby

Leaves the currently joined game room.

This function sends a request to the server to leave the currently joined game room. If it returns true, then Listener::leaveRoomReturn() gets called when the operation has successfully been finished.

Remarks

This operation will fail and return false if the client does not currently reside inside any game room.

Parameters

willComeBack	If this is set to 'true', then the player becomes inactive and the client could later rejoin the room as the very same player. 'false' means the player leaves the room for good. Note that the player only stays inactive for at maximum as many milliseconds as you have set the playerTtl to during room creation (see RoomOptions::setPlayerTtl()). The default is 'false'.
sendAuthCookie	Pass 'true' to set the sendAuthCookie web flag (please see Webhooks v1.2 for further information). The default is 'false'.

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

opCreateRoom(), opJoinOrCreateRoom(), opJoinRoom(), opJoinRandomRoom(), MutableRoom, RoomOptions, Listener::leaveRoomReturn()

Sends in-game data to other players in the game, who will receive it in their Listener::customEventAction() callback.

The eventCode should be used to define the event's type and content respectively. The payload has to be one of the datatypes that are listed as supported for values at serializable datatypes.

This function provides the option to raise events reliably or unreliably. While both result in ordered events, the ones that got sent with the latter option might get lost, causing gaps in the resulting event sequence. On the other hand, they cause less overhead and are optimal for data that is replaced soon.

Note: the value of the reliability option only takes effect when the ConnectionProtocol passed to Client() equals ConnectionProtocol::UDP (which is the default for most platforms) and the message is small enough to not get fragmented into several UDP packets (rule of thumb: you can safely assume that the message fits into a single UDP packet, when its payload size is below 1kb), otherwise the message gets sent reliably, even when the reliability option asks for sending it unreliably.

Sending is not done immediately, but in intervals of service() calls.

It is recommended to keep the payload as simple as possible, especially for events that get raised multiple times per second. This easily adds up to a huge amount of data otherwise.

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

Listener::customEventAction(), Table of Datatypes

Parameters

reliable	true = the operation will be sent reliably; false = no resend in case of packet loss - will be ignored, when not using ConnectionProtocol::UDP
parameters	the payload of the event to raise - has to be provided in the form of one of the supported data types, specified at Table of Datatypes
eventCode	number for arbitrary classification of the type of the event (like '1' for position updates, '2' for chat messages, and so on).
options	see RaiseEventOptions

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

reliable	true = operation will be sent reliably; false = no resend in case of packet loss - will be ignored, when not using UDP as protocol
pParameterArray	the payload array of the event to raise - has to be provided in the form of a 1D array of one of the supported data types, specified at Table of Datatypes
arrSize	the number of elements in pParameterArray
eventCode	number for arbitrary classification of the type of event (like '1' for position updates, '2' for chat messages, and so on).
options	see RaiseEventOptions

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

reliable	true = operation will be sent reliably; false = no resend in case of packet loss - will be ignored, when not using UDP as protocol
pParameterArray	the payload array of the event to raise - has to be provided in the form of an array of one of the supported data types, specified at Table of Datatypes
pArrSizes	an array holding the number of elements for each dimension of pParameterArray
eventCode	number for arbitrary classification of the type of event (like '1' for position updates, '2' for chat messages, and so on).
options	see RaiseEventOptions

Requests the rooms and online states for the specified list of friends. All clients should set a unique UserID before connecting. The result can be accessed through getFriendList() after the corresponding call to Listener::onFindFriendsResponse() has been received.

This function can be called when the caller does not currently reside in a game room to find the rooms played by a selected list of users. The result can be accessed by a call to getFriendList() and is empty before the first response has arrived in Listener::onFindFriendsResponse(). getFriendListAge() can be used to retrieve the amount of milliseconds that have passed since the value that is returned by getFriendList() has been updated for the last time.

Users identify themselves by passing their UserIDs to AuthenticationValues::setUserID().

The list of userIDs must be fetched from some other source (not provided by Photon).

Remarks

This operation will fail and return false if the client does currently reside inside a game room or if the result for a previous call to this function has not arrived yet.

Parameters

friendsToFind	An array of unique userIDs.
numFriendsToFind	The element count of friendsToFind.

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

getFriendList(), getFriendListAge(), Listener::onFindFriendsResponse()

Sends the specified list of LobbyStatsRequest objects to the server. The corresponding list of LobbyStatsResponse objects arrives in Listener::onLobbyStatsResponse().

This function can be called when the caller does not currently reside in a game room to retrieve statistics for various lobbies.

Remarks

This operation will fail and return false if the client does currently reside inside a game room.

Note

Pass 'true' for the 'autoLobbyStats' parameter of Client() to automatically receive regular stats updates for all lobbies in Listener::onLobbyStatsUpdate(). When doing so, it makes little sense to also additionally call this function. opLobbyStats() should rather be used in combination with passing 'false' for the 'autoLobbyStats' parameter of Client() to achieve fine-grain control of when / how often and for which lobbies you want to retrieve a stats update. This can be useful to reduce traffic when you have lots of lobbies, but only rarely need stats updates for most of them.

Parameters

lobbiesToQuery

A Common::JVector containing a LobbyStatsRequest instance for each lobby that should be queried.

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

Client(), Listener::onLobbyStatsResponse(), Listener::onLobbyStatsUpdate(), LobbyStatsRequest, LobbyStatsResponse

Updates the clients interest groups (for events inside of game rooms).

This function can be called from inside of a game room to change the list of interest groups inside that room to which the local client is subscribed to. For each opRaiseEvent() call one can specify the interest groups to which that event should be sent in the RaiseEventOptions. When doing so, only clients that are subscribed to those interest groups will receive that event.

Note the difference between passing NULL and the address of an empty JVector instance:

• NULL won't add/remove any groups.
• a JVector without any elements will add/remove all (existing) groups.

First, removing groups is executed. This way, you could leave all groups and join only the ones provided.

Changes become active not immediately but when the server executes this operation (approximately getRoundTripTime()/2 milliseconds after the Client has sent it).

Remarks

This operation will fail and return false if the client does not currently reside inside a game room.

Parameters

pGroupsToRemove	Groups to remove from interest. NULL will not remove any. An empty instance will remove all.
pGroupsToAdd	Groups to add to interest. NULL will not add any. An empty instance will add all existing groups.

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

opRaiseEvent(), RaiseEventOptions::setInterestGroups(), Interestgroups

Used in conjunction with Listener::onCustomAuthenticationIntermediateStep() to implement multi-leg custom authentication.

While normally custom authentication is single-legged, occasionally a certain service may require multi-leg authentication. This means that the client sends some authentication data to the server that you pass when calling connect() and the server does not respond with a final result (successful connect or failed connect attempt due to an authentication error), but with some intermediate result data that gets passed to your Listener::onCustomAuthenticationIntermediateStep() implementation and that is needed by your application to acquire the authentication data for the next step of the authentication process. You can then pass that next step data to this function to continue the authentication process that you have started with the connect() call.

Remarks

This operation will fail and return false if the client is not currently expecting it to be called. A call by you is only expected after you have received a call to Listener::onCustomAuthenticationIntermediateStep() beforehand and only one call to this function is expected after each received call to Listener::onCustomAuthenticationIntermediateStep(). If a call is expected, then the connection flow pauses until this call has been made. No call to this function is ever expected if the custom authentication that you have set up is single-legged (which is by far more common) or if you have not set up any custom authentication at all, which means that this function will always fail in these scenarios.

Parameters

authenticationValues

An instance of class AuthenticationValues

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

connect(), Listener::onCustomAuthenticationIntermediateStep(), AuthenticationValues

Makes Photon call your custom web-service by path/name with the given parameters (converted into JSON).

A WebRPC calls a custom, http-based function on a server that you provide. The uriPath is relative to a "base path" which is configured on the server side. The sent parameters get converted to Json. Vice versa, the response of the web-service will be converted back, when it gets sent back to the Client, where it arrives in Listener::webRpcReturn().

To use this feature, you have to setup your server:

For a Photon Cloud application visit the Dashboard and setup "WebHooks". The BaseUrl is used for WebRPCs as well.

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

Listener::webRpcReturn(), Table of Datatypes, Webhooks

Parameters

uriPath

the URL path to call, relative to the baseUrl configured on Photon's server-side

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

uriPath	the URL path to call, relative to the baseUrl configured on Photon's server-side
parameters	the parameters to send to the web-service method - has to be provided in the form of one of the supported data types, specified at Table of Datatypes
sendAuthCookie	defines if the authentication cookie gets sent to a WebHook (if setup)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

uriPath	the URL path to call, relative to the baseUrl configured on Photon's server-side
pParameterArray	the parameter array to send to the web-service method - has to be provided in the form of a 1D array of one of the supported data types, specified at Table of Datatypes
arrSize	the number of elements in pParameterArray
sendAuthCookie	defines if the authentication cookie gets sent to a WebHook (if setup)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

uriPath	the URL path to call, relative to the baseUrl configured on Photon's server-side
pParameterArray	the parameter array to send to the web-service method - has to be provided in the form of an array of one of the supported data types, specified at Table of Datatypes
pArrSizes	an array holding the number of elements for each dimension of pParameterArray
sendAuthCookie	defines if the authentication cookie gets sent to a WebHook (if setup)

Used in conjunction with Listener::onAvailableRegions() and RegionSelectionMode::SELECT to select a certain server region to connect to.

If you pass RegionSelectionMode::SELECT for parameter 'regionSelectionMode' to Client(), then the Client does not automatically choose a server region to connect to on its own during the connection flow, but upon retrieving the list of available regions and the list of server addresses that can be used to ping those regions it passes those lists to your implementation of Listener::onAvailableRegions() and pauses the connection flow. You then need to choose one of the available regions and select it by passing its name to this function to continue the connection flow.

The list of available regions for Photon Public Cloud is available at Regions. However more regions might be added over time after you have released your application and the list of available regions might differ when your appID is associated with a dedicated Cloud or when you connect to a non-default name server address. Also a certain region might be temporarily unavailable for maintenance. Furthermore some regions might consist out of multiple different clusters, while others don't. Therefor you should always assure that the region name that you pass to this function actually matches one of the entries in the list of available regions. Also be prepared to select a fall back option in case that your preferred region is not available.

A typical list of available regions might look like this (more or less regions might be available and the order of the entries is undefined and might change without notice): "eu", "us", "usw", "cae", "asia", "jp", "au", "sa", "in", "kr"

When multiple clusters per region are set up for your appID for some regions, then the list might look like this: "eu/Default", "eu/Cluster2", "us/Default", "us/Cluster2", "usw", "cae", "asia", "jp", "au", "sa", "in", "kr"

Examples for valid strings to pass for the 'eu' region for parameter 'selectedRegion' with the above example lists (adapt accordingly for other regions):

• "eu" - Valid when at least one cluster is available in region 'eu', selects the default cluster for that region.
• "eu/Default" - Only valid when a cluster with the exact name "Default" is available in region 'eu'.
• "eu/Cluster2" - Only valid when a cluster with the exact name "Cluster2" is available in region 'eu'.
• "eu/*" - Only valid when at least 2 clusters are setup in region 'eu' of which at least one is available. The server randomly selects one of the available clusters in the specified region. This string is not contained in the list of available regions and must be constructed by your code when it is valid and when you intend to select a random cluster.

In case of the server randomly selecting a cluster, parameter 'cluster' of Listener::connectReturn() contains the name of the cluster to which the client has connected. Otherwise that parameter is an empty string.

Remarks

This operation will fail and return false if 'regionSelectionMode' has not been set to RegionSelectionMode::SELECT upon construction of this class instance.

Parameters

selectedRegion

Must be a valid region name that matches one of the entries in the list of available regions that got passed to Listener::onAvailableRegions()

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

Client(), connect(), Listener::onAvailableRegions()

Reconnects the the server and rejoins the last previously joined room.

This function reconnects directly to the game server to which it has previously been connected to and sends a request to the server to join the last previously joined game room. If it returns true, then Listener::joinRoomReturn() gets called when the operation has been finished.

The usual requirements for a rejoin apply, meaning the room must still exist, the local player must have entered it before, but it must not have left it for good, but only have become inactive and the playerTTL for the local player in that room must not have run out yet, otherwise this operation will fail and Listener::joinRoomReturn() will get called with an error code.

Remarks

This function will fail and return false if no game room has been entered since the creation of the class instance or if the client is still/already in a connected state.

reconnectAndRejoin() is quicker than the combination of connect() and opJoinRoom().

Returns

true, if the request could successfully be queued for sending to the server, false otherwise.

See also

connect(), opJoinRoom(), Listener::joinRoomReturn()

Sends in-game data to other players in the game, who will receive it in their Listener::onDirectMessage() callback. Data that gets sent with this function, gets sent over a direct peer to peer connection, when possible.

For the Photon clients to attempt to establish direct peer to peer connections to each other when entering a room you need set the the DirectMode Option either to DirectMode::MASTER_TO_ALL or to DirectMode::ALL_TO_ALL on the RoomOptions instance that you provide on room creation. Only when a direct connection to a certain client exists, data can be exchanged with it directly. Otherwise this function either falls back to sending it through the Photon game server with opRaiseEvent(), or doesn't send it at all, depending on the value of the 'fallbackRelay' parameter. Data transfer on a direct p2p connection always happens unreliably over UDP even when a different connection protocol has been chosen for connections to the Photon servers in the constructor of this class. However data transfer over the fall-back relay uses the protocol that has been selected for connections to the Photon server when calling the constructor.

It is recommended to keep the payload as simple as possible, as the data is typically sent multiple times per second. This easily adds up to a huge amount of data otherwise.

Note

A direct connection to a certain client is not guaranteed to exist, even when RoomOptions::setDirectMode() specifies that the Clients should attempt to establish it, as NAT punch-through does not have a 100% success rate. In the case that a direct message is preferable, but a relayed one would be acceptable when no direct connection exists, the 'fallbackRelay' option comes into play.

Furthermore if a client looses its connection to Photon while other clients can still reach the server, then that client most likely lost its internet connection and direct messages won't reach it anymore either.

Remarks

This function provides a rather low-level raw UDP socket like way to send data. If you need any higher level functionality like reliable data delivery, support for bigger messages, message caching, interest groups or webforwarding, then please use opRaiseEvent() instead.

See also

Listener::onDirectMessage(), opRaiseEvent(), DirectMode, RoomOptions::getDirectMode(), RoomOptions::setDirectMode()

Parameters

parameters	the data to send - has to be provided in the form of one of the supported data types, specified at Table of Datatypes - must be less than 1200 bytes
targetPlayer	the player number of the intended receiver of the message - must be the number of another active player inside the same room as the sender
fallbackRelay	true if the Photon game server that hosts the room should be used as a fallback relay (by an automatic call to opRaiseEvent()) when no direct connection to the other client exists, false otherwise

Returns

true, if the request could successfully be sent (this does not guarantee that it will be received), false otherwise.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

pParameterArray	the data to send - has to be provided in the form of a 1D array of one of the supported data types, specified at Table of Datatypes - must be less than 1200 bytes
arrSize	the number of elements in pParameterArray
targetPlayer	the player number of the intended receiver of the message - must be the number of another active player inside the same room as the sender
fallbackRelay	true if the Photon game server that hosts the room should be used as a fallback relay (by an automatic call to opRaiseEvent()) for all specified receivers to which no direct connection exists, false otherwise

Returns

true, if the request could successfully be sent (this does not guarantee that it will be received), false otherwise.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

pParameterArray	the the data to send - has to be provided in the form of an array of one of the supported data types, specified at Table of Datatypes - must be less than 1200 bytes
pArrSizes	an array holding the number of elements for each dimension of pParameterArray
targetPlayer	the player number of the intended receiver of the message - must be the number of another active player inside the same room as the sender
fallbackRelay	true if the Photon game server that hosts the room should be used as a fallback relay (by an automatic call to opRaiseEvent()) for all specified receivers to which no direct connection exists, false otherwise

Returns

true, if the request could successfully be sent (this does not guarantee that it will be received), false otherwise.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

parameters	the data to send - has to be provided in the form of one of the supported data types, specified at Table of Datatypes - must be less than 1200 bytes
targetPlayers	the player numbers of the intended receivers of the message - must be the numbers of other active players inside the same room as the sender
fallbackRelay	true if the Photon game server that hosts the room should be used as a fallback relay (by an automatic call to opRaiseEvent()) for all specified receivers to which no direct connection exists, false otherwise

Returns

the number of target players, for which the request could successfully be sent (this does not guarantee that it will be received).

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

pParameterArray	the data to send - has to be provided in the form of a 1D array of one of the supported data types, specified at Table of Datatypes - must be less than 1200 bytes
arrSize	the number of elements in pParameterArray
targetPlayers	the player numbers of the intended receivers of the message - must be the numbers of other active players inside the same room as the sender
fallbackRelay	true if the Photon game server that hosts the room should be used as a fallback relay (by an automatic call to opRaiseEvent()) for all specified receivers to which no direct connection exists, false otherwise

Returns

the number of target players, for which the request could successfully be sent (this does not guarantee that it will be received).

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

pParameterArray	the data to send - has to be provided in the form of an array of one of the supported data types, specified at Table of Datatypes - must be less than 1200 bytes
pArrSizes	an array holding the number of elements for each dimension of pParameterArray
targetPlayers	the player numbers of the intended receivers of the message - must be the numbers of other active players inside the same room as the sender
fallbackRelay	true if the Photon game server that hosts the room should be used as a fallback relay (by an automatic call to opRaiseEvent()) for all specified receivers to which no direct connection exists, false otherwise

Returns

the number of target players, for which the request could successfully be sent (this does not guarantee that it will be received).

Returns

the difference between the local uptime and the Photon Server's system time in ms.

In real-time games it's often useful to relate game events to a global common timeline, that's valid for all players and independent from derivations throughout the clients' system times. The Photon Server's System Time can serve as this reference time. The serverTimeOffset represents the difference between the client's local system time and the Photon server's system time.

ServerTime = serverTimeOffset + GETTIMEMS()

The serverTimeOffset is fetched shortly after connect by Photon. Use GETTIMEMS() to get your local time in ms. You can let Photon refetch the offset by calling fetchServerTimestamp(). The ServerTimeOffset will be 0 until shortly after initial connect.

Returns

the Photon Server's system time ins ms.

see getServerTimeOffset()

Returns

the total number of outgoing bytes transmitted by this PhotonPeer object.

See also

getBytesIn()

Returns

the total number of incoming bytes received by this PhotonPeer object.

See also

getBytesOut()

Returns

the size of the dispatched event or operation-result in bytes. This value is set before onEvent() or onOperationResponse() is called (within dispatchIncomingCommands()). Get this value directly in onEvent() or onOperationResponse().

Returns

the size of the last serialized operation call in bytes. The value includes all headers for this single operation but excludes those of UDP, Enet Package Headers and TCP. Get this value immediately after calling an operation.

Returns

the number of resend retries before a peer is considered lost/disconnected.

This is udp specific and will always return 0 for other protocols.

See also

setSentCountAllowance() getDisconnectTimeout() setDisconnectTimeout()

Sets the number of re-send retries before a peer is considered lost/disconnected.

This is udp specific and will do nothing at all for other protocols.

Parameters

sentCountAllowance

the new number of re/-send retries before a peer is considered lost/disconnected.

See also

getSentCountAllowance() getDisconnectTimeout() setDisconnectTimeout()

Returns

the time threshold in milliseconds since the last reliable command, before a ping will be sent.

See also

setTimePingInterval()

Sets the time threshold in milliseconds since the last reliable command, before a ping will be sent.

Parameters

timePingInterval

time threshold in milliseconds since the last reliable command, before a ping will be sent.

See also

getTimePingInterval()

Returns

the time in milliseconds until a reliable command is acknowledged by the server.

This is, what is commonly called a ping time or just a ping.

See also

getRoundTripTimeVariance()

Returns

the variance of the roundtrip time in milliseconds. Gives a hint about how much the net latency is varying.

See also

getRoundTripTime()

Returns

timestamp of the last time anything (!) was received from the server (including low level Ping and ACKs but also events and operation-returns). This is not the time when something was dispatched.

Returns the current level of debug information that's passed on to BaseListener::debugReturn().

Returns

one of the values in DebugLevel

See also

setDebugOutputLevel()

Sets the current level of debug information that's passed on to BaseListener::debugReturn().

Parameters

debugLevel

one of the values in DebugLevel

Returns

true if the new debug level has been set correctly, false otherwise.

See also

getDebugOutputLevel()

Returns

the LogFormatOptions that are used by this instance.

See also

setFormatOptions()

Sets the log format options to the supplied value.

Parameters

formatOptions

the new value to which the log format options will be set

See also

getFormatOptions()

Returns

the total number of reliable commands currently waiting in the incoming queues of all channels or -1 if not connected.

Returns

this peer's ID as assigned by the server. Will be -1, if not connected.

Returns

the maximum time interval in milliseconds for doing resend retries before a peer is considered lost/disconnected.

See also

setDisconnectTimeout() getSentCountAllowance() setSentCountAllowance()

Sets the maximum time ins milliseconds for making re-send retries before a peer is considered lost/disconnected.

Parameters

disconnectTimeout

resend max time in ms before a peer is considered lost/disconnected

See also

getDisconnectTimeout() getSentCountAllowance() setSentCountAllowance()

Returns

the number of queued incoming commands in all channels or -1 if not connected

Returns

the number of queued outgoing commands in all channels or -1 if not connected

Returns

this peer's payload encryption availability status. True if payload encryption is available, false otherwise.

See also

getIsEncryptionAvailable(), establishEncryption(), initUserDataEncryption()

Returns

this peer's encryption availability status. True if either payload encryption is available or if the connection protocol is UDP and UDP encryption is available or if the connection protocol is already secure on its own, false otherwise.

See also

getIsPayloadEncryptionAvailable(), establishEncryption(), initUserDataEncryption(), initUDPEncryption()

Returns

the count of commands that got repeated (due to local repeat-timing before an ACK was received).

Returns

the limit for the queue of received unreliable commands.

See also

setLimitOfUnreliableCommands()

Sets the limit for the queue of received unreliable commands. This works only in UDP. This limit is applied when you call dispatchIncomingCommands. If this client (already) received more than this limit, it will throw away the older ones instead of dispatching them. This can produce bigger gaps for unreliable commands but your client catches up faster. This can be useful when the client couldn't dispatch anything for some time (cause it was in a room but loading a level). If set to 20, the incoming unreliable queues are truncated to 20. If 0, all received unreliable commands will be dispatched. This is a "per channel" value, so each channel can hold commands up to specified limit. This value interacts with dispatchIncomingCommands(): If that is called less often, more commands get skipped.

See also

getLimitOfUnreliableCommands()

Returns

true if CRC enabled

See also

setCRCEnabled

Enables or disables CRC. While not connected, this controls if the next connection(s) should use a per-package CRC checksum. If the client is in another state than 'connected', then this function has no effect except for logging an error.

While turned on, the client and server will add a CRC checksum to every sent package. The checksum enables both sides to detect and ignore packages that were corrupted during transfer. Corrupted packages have the same impact as lost packages: They require a re-send, adding a delay and could lead to timeouts. Building the checksum has a low processing overhead but increases integrity of sent and received data. Packages discarded due to failed CRC checks are counted in PhotonPeer.PacketLossByCRC.

Note

This only has effect for UDP connections.

This does not have any effect for connections that use UDP datagram encryption (which always use a built-in checksum).

See also

getCRCEnabled

Returns

the count of packages dropped due to failed CRC checks for this connection.

See also

setCRCEnabled

Returns

true if traffic statistics of a peer are enabled. Default trafficStatsEnabled: false (disabled).

Enables or disables the traffic statistics of a peer. Default trafficStatsEnabled: false (disabled).

Returns

the count of milliseconds the stats are enabled for tracking.

Returns

the byte-count of incoming "low level" messages, which are either Enet Commands or TCP Messages. These include all headers, except those of the underlying internet protocol UDP or TCP.

Returns

the byte-count of outgoing "low level" messages, which are either Enet Commands or TCP Messages. These include all headers, except those of the underlying internet protocol UDP or TCP.

Returns

a statistic of incoming and outgoing traffic, split by operation, operation-result and event. Operations are outgoing traffic, results and events are incoming. Includes the per-command header sizes (UDP: Enet Command Header or TCP: Message Header).

Returns

the number of resend attempts for a reliable command that are done in quick succession (after RoundTripTime+4*RoundTripTimeVariance).

Sets the number of resend attempts for a reliable command can be done in quick succession (after RoundTripTime+4*RoundTripTimeVariance).

Remarks

The default value is 0. Any later resend attempt will then double the time before the next resend takes place. The max value is 4. Make sure to set SentCountAllowance to a slightly higher value, as more repeats will get done.

The IDs from 0 to getChannelCountUserChannels()-1 can be passed as channelID to operations that offer this parameter.

Returns

the number of different channels that are available for sending operations on.

Returns

the count of peers, which have been initialized since the start of the application. Interesting mainly for debugging purposes.

The Current state this Client instance is in. Be Careful: several states are "transitions" that lead to other states.

Note

This is publicly available purely for informational purposes (i.e. when debugging) and your logic should not rely on certain state changes, but should instead wait for the dedicated callbacks.

Returns

one of the values defined in PeerStates

Returns

the address of the master server to which the client is connected when it is not inside a game room.

Returns

the count of players that are currently participating in games on game servers that are in the same cluster (game servers assigned to the same master server) as the local client. Each Photon Cloud region consists of at least one, but potentially multiple separate clusters.

Remarks

This value is only getting updated when the client is on the master server.

Returns

the count of rooms that are currently existing on game servers in the same cluster (game servers assigned to the same master server) as the one the local client is connected to. Each Photon Cloud region consists of at least one, but potentially multiple separate clusters.

Remarks

This value is only getting updated when the client is on the master server.

Returns

the total count of players that are currently connected to the same cluster (clients that are connected to the same master server or to a game server that is assigned to the same master server) as the local client. Each Photon Cloud region consists of at least one, but potentially multiple separate clusters.

Remarks

This value is only getting updated when the client is on the master server.

Returns

a non-const reference to a MutableRoom instance that represents the currently joined room.

Remarks

The behavior when accessing the referenced instance after leaving the room in which that reference has been obtained and the behavior when calling this function without being inside a room is undefined.

Note

Attention: Do not assign the return value of this function to a MutableRoom variable, but only assign it to a MutableRoom reference or simply directly operate on the function return value, as assigning it to a variable means that accessing that variable lets you operate on a local copy and operations that change that copy don't affect the actual room.

Returns

the list of all visible rooms.

Remarks

The value that is returned by this function is only updated inside a lobby of LobbyType::DEFAULT. Clients that are inside a lobby of a different LobbyType, or in no lobby at all, do not receive room list updates. The same Client instance can't be inside of multiple rooms at once. The term 'room' includes game rooms and lobbies. Therefor a Client instance is not able to receive room list updates while it resides inside of a game room.

To show up in the lobby the IsVisible flag of a room needs to be set to true (which is the default value). The MaxPlayers setting and the current amount of players inside a room do not influence the rooms visibility, nor does the IsOpen flag: If the maximum amount of players is already inside of the room or if the room is closed, then the room is still included in the room list, but attempts to join it will fail.

See also

getRoomNameList()

Returns

the list of the names of all visible rooms.

The entries in the returned JVector instance are guarenteed to be in the same order like the entries in the JVector instance that is returned by getRoomList(). The same remarks apply to this function as are mentioned for getRoomList().

See also

getRoomList()

Returns

true if this client instance currently resides within a room, false otherwise.

Remarks

The term 'room' includes game rooms and lobbies.

See also

getIsInGameRoom(), getIsInLobby()

Returns

true if this client instance currently resides within a game room, false otherwise.

See also

getIsInRoom(), getIsInLobby()

Returns

true if this client instance currently resides within a lobby, false otherwise.

See also

getIsInRoom(), getIsInGameRoom()

Returns

the current value of the autJoinLobby flag.

Remarks

The value of the autoJoinLobby flag determines if the client will automatically join the default lobby whenever it has successfully connected and whenever it leaves a game room.

See also

setAutoJoinLobby()

Sets the value of the autJoinLobby flag.

Parameters

autoJoinLobby

the new value to which the flag will be set

Remarks

The value of the autoJoinLobby flag determines if the client will automatically join the default lobby whenever it has successfully connected and whenever it leaves a game room.

See also

getAutoJoinLobby()

Returns

a non-const reference to the MutablePlayer instance that is representing the local player.

Returns

the latest locally cached state of the friend list.

Remarks

You can request the latest state of the local clients friend list from the server by a call to opFindFriends(). Listener::onFindFriendsResponse() informs you when the servers response has arrived. The list that is returned by this function reflects the state that the server has sent in its latest response to an update request or in other words the most up to date state that is available locally at the time of the call.

See also

opFindFriends(), Listener::onFindFriendsResponse(), FriendInfo, getFriendListAge()

Returns

the time in ms that has passed since the last update has been applied to the list that is returned by getFriendList() or 0 if either no friendlist is available yet or if a request for an update is in progress at the time of the call.

Summarizes (aggregates) the different causes for disconnects of a client. A disconnect can be caused by: errors in the network connection or some vital operation failing (which is considered "high level"). While operations always trigger a call to OnOperationResponse, connection related changes are treated in OnStatusChanged. The DisconnectCause is set in either case and summarizes the causes for any disconnect in a single state value which can be used to display (or debug) the cause for disconnection.

Returns

the disconnect cause.

Returns

the unique user ID

See also

setUserID()

Returns

the region code of the Photon Cloud region to which the client has the best ping.

Remarks

When you specify RegionSelectionMode::BEST on constructing the Client instance, then on first connect the Client will aquire a list of available regions and of their adresses and ping each of them multiple times. Afterwards it will connect to the region with the lowest average ping. After you got a call to Listener::connectReturn(), the region code of the region that the Client has chosen based on the ping results can get accessed by a call to this function. Later calls to connect() will use that cached region code to avoid re-doing the time-consuming ping-procedure and therefor to keep the time short that is needed for establishing a connection. For the same reason it is recommend that you acquire the result of the ping-procedure through this function and store it in local persistant storage, so that you can use it with RegionSelectionMode::SELECT. This way you can avoid the time-consuming pinging procedure even for the first connect after constructing the class, if you already have the region code for the region with the best ping stored locally from a connection on another Client instance (for example after your app has been shut down and restarted). However in this case you may want to provide an option to your users through which they can delete your locally stored region code and this way trigger a re-pinging on the next construction of a Client instance.

Note

This function will return an empty string, if no ping result is available (yet), which is the case when another RegionSelectionMode than BEST has been chosen or when you have not received the call to Listener::connectReturn() yet that corresponds to your first successfully established connection since the construction of this class.