Inheritance diagram for Client:

Collaboration diagram for Client:

Public Member Functions
	Client (LoadBalancing::Listener &listener, const Common::JString &applicationID, const Common::JString &appVersion, nByte connectionProtocol=Photon::ConnectionProtocol::DEFAULT, bool autoLobbyStats=false, nByte regionSelectionMode=RegionSelectionMode::DEFAULT, bool useAlternativePorts=false)

virtual	~Client (void)

virtual bool	connect (const AuthenticationValues &authenticationValues=AuthenticationValues(), const Common::JString &username=L"", const Common::JString &serverAddress=M_NAMESERVER, nByte serverType=ServerType::NAME_SERVER)

virtual void	disconnect (void)

virtual void	service (bool dispatchIncomingCommands=true)

virtual void	serviceBasic (void)

virtual bool	opCustom (const Photon::OperationRequest &operationRequest, bool sendReliable, nByte channelID=0, bool encrypt=false)

virtual bool	sendOutgoingCommands (void)

virtual bool	sendAcksOnly (void)

virtual bool	dispatchIncomingCommands (void)

virtual void	fetchServerTimestamp (void)

virtual void	resetTrafficStats (void)

virtual void	resetTrafficStatsMaximumCounters (void)

virtual Common::JString	vitalStatsToString (bool all) const

virtual bool	opJoinLobby (const Common::JString &lobbyName=Common::JString(), nByte lobbyType=LobbyType::DEFAULT)

virtual bool	opLeaveLobby (void)

virtual bool	opCreateRoom (const Common::JString &gameID, const RoomOptions &options=RoomOptions(), const Common::JVector< Common::JString > &expectedUsers=Common::JVector< Common::JString >())

virtual bool	opJoinOrCreateRoom (const Common::JString &gameID, const RoomOptions &options=RoomOptions(), int cacheSliceIndex=0, const Common::JVector< Common::JString > &expectedUsers=Common::JVector< Common::JString >())

virtual bool	opJoinRoom (const Common::JString &gameID, bool rejoin=false, int cacheSliceIndex=0, const Common::JVector< Common::JString > &expectedUsers=Common::JVector< Common::JString >())

virtual bool	opJoinRandomRoom (const Common::Hashtable &customRoomProperties=Common::Hashtable(), nByte maxPlayers=0, nByte matchmakingMode=MatchmakingMode::FILL_ROOM, const Common::JString &lobbyName=Common::JString(), nByte lobbyType=LobbyType::DEFAULT, const Common::JString &sqlLobbyFilter=Common::JString(), const Common::JVector< Common::JString > &expectedUsers=Common::JVector< Common::JString >())

virtual bool	opLeaveRoom (bool willComeBack=false, bool sendAuthCookie=false)

template<typename Ftype >
bool	opRaiseEvent (bool reliable, const Ftype &parameters, nByte eventCode, const RaiseEventOptions &options=RaiseEventOptions())

template<typename Ftype >
bool	opRaiseEvent (bool reliable, const Ftype pParameterArray, typename Common::Helpers::ArrayLengthType< Ftype >::type arrSize, nByte eventCode, const RaiseEventOptions &options=RaiseEventOptions())

template<typename Ftype >
bool	opRaiseEvent (bool reliable, const Ftype pParameterArray, const short *pArrSizes, nByte eventCode, const RaiseEventOptions &options=RaiseEventOptions())

virtual bool	opFindFriends (const Common::JString *friendsToFind, short numFriendsToFind)

virtual bool	opLobbyStats (const Common::JVector< LoadBalancing::LobbyStatsRequest > &lobbiesToQuery=Common::JVector< LoadBalancing::LobbyStatsRequest >())

virtual bool	opChangeGroups (const Common::JVector< nByte > pGroupsToRemove, const Common::JVector< nByte > pGroupsToAdd)

virtual bool	opCustomAuthenticationSendNextStepData (const AuthenticationValues &authenticationValues)

virtual bool	opWebRpc (const Common::JString &uriPath)

template<typename Ftype >
bool	opWebRpc (const Common::JString &uriPath, const Ftype &parameters, bool sendAuthCookie=false)

template<typename Ftype >
bool	opWebRpc (const Common::JString &uriPath, const Ftype pParameterArray, typename Common::Helpers::ArrayLengthType< Ftype >::type arrSize, bool sendAuthCookie=false)

template<typename Ftype >
bool	opWebRpc (const Common::JString &uriPath, const Ftype pParameterArray, const short *pArrSizes, bool sendAuthCookie=false)

virtual bool	selectRegion (const Common::JString &selectedRegion)

virtual bool	reconnectAndRejoin (void)

template<typename Ftype >
bool	sendDirect (const Ftype &parameters, int targetPlayer, bool fallbackRelay=false)

template<typename Ftype >
bool	sendDirect (const Ftype pParameterArray, typename Common::Helpers::ArrayLengthType< Ftype >::type arrSize, int targetPlayer, bool fallbackRelay=false)

template<typename Ftype >
bool	sendDirect (const Ftype pParameterArray, const short *pArrSizes, int targetPlayer, bool fallbackRelay=false)

template<typename Ftype >
int	sendDirect (const Ftype &parameters, const Common::JVector< int > &targetPlayers=Common::JVector< int >(), bool fallbackRelay=false)

template<typename Ftype >
int	sendDirect (const Ftype pParameterArray, typename Common::Helpers::ArrayLengthType< Ftype >::type arrSize, const Common::JVector< int > &targetPlayers=Common::JVector< int >(), bool fallbackRelay=false)

template<typename Ftype >
int	sendDirect (const Ftype pParameterArray, const short *pArrSizes, const Common::JVector< int > &targetPlayers=Common::JVector< int >(), bool fallbackRelay=false)

int	getServerTimeOffset (void) const

int	getServerTime (void) const

int	getBytesOut (void) const

int	getBytesIn (void) const

int	getByteCountCurrentDispatch (void) const

int	getByteCountLastOperation (void) const

int	getSentCountAllowance (void) const

void	setSentCountAllowance (int sentCountAllowance)

int	getTimePingInterval (void) const

void	setTimePingInterval (int timePingInterval)

int	getRoundTripTime (void) const

int	getRoundTripTimeVariance (void) const

int	getTimestampOfLastSocketReceive (void) const

int	getDebugOutputLevel (void) const

bool	setDebugOutputLevel (int debugLevel)

const Common::LogFormatOptions &	getLogFormatOptions (void) const

void	setLogFormatOptions (const Common::LogFormatOptions &formatOptions)

int	getIncomingReliableCommandsCount (void) const

short	getPeerID (void) const

int	getDisconnectTimeout (void) const

void	setDisconnectTimeout (int disconnectTimeout)

int	getQueuedIncomingCommands (void) const

int	getQueuedOutgoingCommands (void) const

bool	getIsPayloadEncryptionAvailable (void) const

bool	getIsEncryptionAvailable (void) const

int	getResentReliableCommands (void) const

int	getLimitOfUnreliableCommands (void) const

void	setLimitOfUnreliableCommands (int value)

bool	getCRCEnabled (void) const

void	setCRCEnabled (bool crcEnabled)

int	getPacketLossByCRC (void) const

bool	getTrafficStatsEnabled (void) const

void	setTrafficStatsEnabled (bool trafficStatsEnabled)

int	getTrafficStatsElapsedMs (void) const

const Photon::TrafficStats &	getTrafficStatsIncoming (void) const

const Photon::TrafficStats &	getTrafficStatsOutgoing (void) const

const Photon::TrafficStatsGameLevel &	getTrafficStatsGameLevel (void) const

nByte	getQuickResendAttempts (void) const

void	setQuickResendAttempts (nByte quickResendAttempts)

nByte	getChannelCountUserChannels (void) const

int	getState (void) const

const Common::JString &	getMasterserverAddress (void) const

int	getCountPlayersIngame (void) const

int	getCountGamesRunning (void) const

int	getCountPlayersOnline (void) const

MutableRoom &	getCurrentlyJoinedRoom (void)

const Common::JVector< Room * > &	getRoomList (void) const

const Common::JVector< Common::JString > &	getRoomNameList (void) const

bool	getIsInRoom (void) const

bool	getIsInGameRoom (void) const

bool	getIsInLobby (void) const

bool	getAutoJoinLobby (void) const

void	setAutoJoinLobby (bool autoJoinLobby)

MutablePlayer &	getLocalPlayer (void)

const Common::JVector< FriendInfo > &	getFriendList (void) const

int	getFriendListAge (void) const

int	getDisconnectedCause (void) const

const Common::JString &	getUserID (void) const

const Common::JString &	getRegionWithBestPing (void) const

Static Public Member Functions
static short	getPeerCount (void)

Detailed Description

This class implements the Photon LoadBalancing work flow by using a Peer. It keeps a state and automatically executes transitions between the Master and Game Servers.

This class (and the Player, MutablePlayer, Room and MutableRoom classes) might be extended to implement your own logic.

However this is not necessary. You can also just put your game specific network logic into a class that uses this class as is, which is the recommended approach.

Override MutableRoom:createPlayer() when subclassing Player, getMutablePlayerFactory() + MutablePlayerFactory::create() + MutablePlayerFactory::destroy() when subclassing MutablePlayer, createRoom() when subclassing Room and getMutableRoomFactory() + MutableRoomFactory::create() + MutableRoomFactory::destroy() when subclassing MutableRoom.

Remarks: Extension notes: An extension of this class should override the functions that are inherited from Photon::PhotonListener, as they are called when the state changes. Call the base implementation first, then pick the operation response, event or state that you want to react to and put it in a switch-case.

We try to provide demos to each platform where this API can be used, so lookout for those.

Constructor & Destructor Documentation

§ Client()

Client	(	LoadBalancing::Listener &	listener,
		const Common::JString &	applicationID,
		const Common::JString &	appVersion,
		nByte	connectionProtocol = `Photon::ConnectionProtocol::DEFAULT`,
		bool	autoLobbyStats = `false`,
		nByte	regionSelectionMode = `RegionSelectionMode::DEFAULT`,
		bool	useAlternativePorts = `false`
	)

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

§ ~Client()

~Client ( void )

virtual

Destructor.

Member Function Documentation

§ connect()

bool connect	(	const AuthenticationValues &	authenticationValues = `AuthenticationValues()`,
		const Common::JString &	username = `L""`,
		const Common::JString &	serverAddress = `M_NAMESERVER`,
		nByte	serverType = `ServerType::NAME_SERVER`
	)

virtual

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

§ disconnect()

void disconnect ( void )

virtual

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()

§ service()

void service ( bool dispatchIncomingCommands = true )

virtual

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:

serviceBasic()
dispatchIncomingCommands() (called withing a loop until all incoming commands have been dispatched.)
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

§ serviceBasic()

void serviceBasic ( void )

virtual

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()

§ opCustom()

bool opCustom	(	const Photon::OperationRequest &	operationRequest,
		bool	sendReliable,
		nByte	channelID = `0`,
		bool	encrypt = `false`
	)

virtual

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

§ sendOutgoingCommands()

bool sendOutgoingCommands ( void )

virtual

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()

§ sendAcksOnly()

bool sendAcksOnly ( void )

virtual

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.

§ dispatchIncomingCommands()

bool dispatchIncomingCommands ( void )

virtual

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()

§ fetchServerTimestamp()

void fetchServerTimestamp ( void )

virtual

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.

§ resetTrafficStats()

void resetTrafficStats ( void )

virtual

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

§ resetTrafficStatsMaximumCounters()

void resetTrafficStatsMaximumCounters ( void )

virtual

Resets traffic stats values that can be maxed out.

§ vitalStatsToString()

Common::JString vitalStatsToString ( bool all ) const

virtual

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.

§ opJoinLobby()

bool opJoinLobby	(	const Common::JString &	lobbyName = `Common::JString()`,
		nByte	lobbyType = `LobbyType::DEFAULT`
	)

virtual

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()

§ opLeaveLobby()

bool opLeaveLobby ( void )

virtual

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()

§ opCreateRoom()

bool opCreateRoom	(	const Common::JString &	gameID,
		const RoomOptions &	options = `RoomOptions()`,
		const Common::JVector< Common::JString > &	expectedUsers = `Common::JVector<Common::JString>()`
	)

virtual

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()

§ opJoinOrCreateRoom()

bool opJoinOrCreateRoom	(	const Common::JString &	gameID,
		const RoomOptions &	options = `RoomOptions()`,
		int	cacheSliceIndex = `0`,
		const Common::JVector< Common::JString > &	expectedUsers = `Common::JVector<Common::JString>()`
	)

virtual

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()

§ opJoinRoom()

bool opJoinRoom	(	const Common::JString &	gameID,
		bool	rejoin = `false`,
		int	cacheSliceIndex = `0`,
		const Common::JVector< Common::JString > &	expectedUsers = `Common::JVector<Common::JString>()`
	)

virtual

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()

§ opJoinRandomRoom()

bool opJoinRandomRoom	(	const Common::Hashtable &	customRoomProperties = `Common::Hashtable()`,
		nByte	maxPlayers = `0`,
		nByte	matchmakingMode = `MatchmakingMode::FILL_ROOM`,
		const Common::JString &	lobbyName = `Common::JString()`,
		nByte	lobbyType = `LobbyType::DEFAULT`,
		const Common::JString &	sqlLobbyFilter = `Common::JString()`,
		const Common::JVector< Common::JString > &	expectedUsers = `Common::JVector<Common::JString>()`
	)

virtual

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

§ opLeaveRoom()

bool opLeaveRoom	(	bool	willComeBack = `false`,
		bool	sendAuthCookie = `false`
	)

virtual

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()

§ opRaiseEvent() [1/3]

template< typename Ftype > bool opRaiseEvent	(	bool	reliable,
		const Ftype &	parameters,
		nByte	eventCode,
		const RaiseEventOptions &	options = `RaiseEventOptions()`
	)

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

§ opRaiseEvent() [2/3]

template< typename Ftype > bool opRaiseEvent	(	bool	reliable,
		const Ftype	pParameterArray,
		typename Common::Helpers::ArrayLengthType< Ftype >::type	arrSize,
		nByte	eventCode,
		const RaiseEventOptions &	options = `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

§ opRaiseEvent() [3/3]

template< typename Ftype > bool opRaiseEvent	(	bool	reliable,
		const Ftype	pParameterArray,
		const short *	pArrSizes,
		nByte	eventCode,
		const RaiseEventOptions &	options = `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

§ opFindFriends()

bool opFindFriends	(	const Common::JString *	friendsToFind,
		short	numFriendsToFind
	)

virtual

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()

§ opLobbyStats()

bool opLobbyStats ( const Common::JVector< LoadBalancing::LobbyStatsRequest > & lobbiesToQuery = Common::JVector<LoadBalancing::LobbyStatsRequest>() )

virtual

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

§ opChangeGroups()

bool opChangeGroups	(	const Common::JVector< nByte > *	pGroupsToRemove,
		const Common::JVector< nByte > *	pGroupsToAdd
	)

virtual

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

§ opCustomAuthenticationSendNextStepData()

bool opCustomAuthenticationSendNextStepData ( const AuthenticationValues & authenticationValues )

virtual

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

§ opWebRpc() [1/4]

bool opWebRpc ( const Common::JString & uriPath )

virtual

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

§ opWebRpc() [2/4]

template< typename Ftype > bool opWebRpc	(	const Common::JString &	uriPath,
		const Ftype &	parameters,
		bool	sendAuthCookie = `false`
	)

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)

§ opWebRpc() [3/4]

template< typename Ftype > bool opWebRpc	(	const Common::JString &	uriPath,
		const Ftype	pParameterArray,
		typename Common::Helpers::ArrayLengthType< Ftype >::type	arrSize,
		bool	sendAuthCookie = `false`
	)

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)

§ opWebRpc() [4/4]

template< typename Ftype > bool opWebRpc	(	const Common::JString &	uriPath,
		const Ftype	pParameterArray,
		const short *	pArrSizes,
		bool	sendAuthCookie = `false`
	)

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)

§ selectRegion()

bool selectRegion ( const Common::JString & selectedRegion )

virtual

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()

§ reconnectAndRejoin()

bool reconnectAndRejoin ( void )

virtual

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()

§ sendDirect() [1/6]

template< typename Ftype > bool sendDirect	(	const Ftype &	parameters,
		int	targetPlayer,
		bool	fallbackRelay = `false`
	)

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.

§ sendDirect() [2/6]

template< typename Ftype > bool sendDirect	(	const Ftype	pParameterArray,
		typename Common::Helpers::ArrayLengthType< Ftype >::type	arrSize,
		int	targetPlayer,
		bool	fallbackRelay = `false`
	)

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.

§ sendDirect() [3/6]

template< typename Ftype > bool sendDirect	(	const Ftype	pParameterArray,
		const short *	pArrSizes,
		int	targetPlayer,
		bool	fallbackRelay = `false`
	)

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.

§ sendDirect() [4/6]

template< typename Ftype > bool sendDirect	(	const Ftype &	parameters,
		const Common::JVector< int > &	targetPlayers = `Common::JVector<int>()`,
		bool	fallbackRelay = `false`
	)

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

§ sendDirect() [5/6]

template< typename Ftype > bool sendDirect	(	const Ftype	pParameterArray,
		typename Common::Helpers::ArrayLengthType< Ftype >::type	arrSize,
		const Common::JVector< int > &	targetPlayers = `Common::JVector<int>()`,
		bool	fallbackRelay = `false`
	)

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

§ sendDirect() [6/6]

template< typename Ftype > bool sendDirect	(	const Ftype	pParameterArray,
		const short *	pArrSizes,
		const Common::JVector< int > &	targetPlayers = `Common::JVector<int>()`,
		bool	fallbackRelay = `false`
	)

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

§ getServerTimeOffset()

int getServerTimeOffset ( void ) const

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.

§ getServerTime()

int getServerTime ( void ) const

Returns: the Photon Server's system time ins ms.

see getServerTimeOffset()

§ getBytesOut()

int getBytesOut ( void ) const

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

See also: getBytesIn()

§ getBytesIn()

int getBytesIn ( void ) const

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

See also: getBytesOut()

§ getByteCountCurrentDispatch()

int getByteCountCurrentDispatch ( void ) const

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().

§ getByteCountLastOperation()

int getByteCountLastOperation ( void ) const

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.

§ getSentCountAllowance()

int getSentCountAllowance ( void ) const

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()

§ setSentCountAllowance()

void setSentCountAllowance ( int sentCountAllowance )

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()

§ getTimePingInterval()

int getTimePingInterval ( void ) const

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

See also: setTimePingInterval()

§ setTimePingInterval()

void setTimePingInterval ( int timePingInterval )

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()

§ getRoundTripTime()

int getRoundTripTime ( void ) const

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()

§ getRoundTripTimeVariance()

int getRoundTripTimeVariance ( void ) const

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

See also: getRoundTripTime()

§ getTimestampOfLastSocketReceive()

int getTimestampOfLastSocketReceive ( void ) const

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.

§ getDebugOutputLevel()

int getDebugOutputLevel ( void ) const

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

Returns: one of the values in DebugLevel

See also: setDebugOutputLevel()

§ setDebugOutputLevel()

bool setDebugOutputLevel ( int debugLevel )

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()

§ getLogFormatOptions()

const LogFormatOptions & getLogFormatOptions ( void ) const

Returns: the LogFormatOptions that are used by this instance.

See also: setFormatOptions()

§ setLogFormatOptions()

void setLogFormatOptions ( const Common::LogFormatOptions & formatOptions )

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()

§ getIncomingReliableCommandsCount()

int getIncomingReliableCommandsCount ( void ) const

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

§ getPeerID()

short getPeerID ( void ) const

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

§ getDisconnectTimeout()

int getDisconnectTimeout ( void ) const

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

See also: setDisconnectTimeout() getSentCountAllowance() setSentCountAllowance()

§ setDisconnectTimeout()

void setDisconnectTimeout ( int disconnectTimeout )

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()

§ getQueuedIncomingCommands()

int getQueuedIncomingCommands ( void ) const

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

§ getQueuedOutgoingCommands()

int getQueuedOutgoingCommands ( void ) const

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

§ getIsPayloadEncryptionAvailable()

bool getIsPayloadEncryptionAvailable ( void ) const

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

See also: getIsEncryptionAvailable(), establishEncryption(), initUserDataEncryption()

§ getIsEncryptionAvailable()

bool getIsEncryptionAvailable ( void ) const

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()

§ getResentReliableCommands()

int getResentReliableCommands ( void ) const

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

§ getLimitOfUnreliableCommands()

int getLimitOfUnreliableCommands ( void ) const

Returns: the limit for the queue of received unreliable commands.

See also: setLimitOfUnreliableCommands()

§ setLimitOfUnreliableCommands()

void setLimitOfUnreliableCommands ( int value )

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()

§ getCRCEnabled()

bool getCRCEnabled ( void ) const

Returns: true if CRC enabled

See also: setCRCEnabled

§ setCRCEnabled()

void setCRCEnabled ( bool crcEnabled )

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

§ getPacketLossByCRC()

int getPacketLossByCRC ( void ) const

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

See also: setCRCEnabled

§ getTrafficStatsEnabled()

bool getTrafficStatsEnabled ( void ) const

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

§ setTrafficStatsEnabled()

void setTrafficStatsEnabled ( bool trafficStatsEnabled )

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

§ getTrafficStatsElapsedMs()

int getTrafficStatsElapsedMs ( void ) const

Returns: the count of milliseconds the stats are enabled for tracking.

§ getTrafficStatsIncoming()

const Photon::TrafficStats & getTrafficStatsIncoming ( void ) const

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.

§ getTrafficStatsOutgoing()

const Photon::TrafficStats & getTrafficStatsOutgoing ( void ) const

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.

§ getTrafficStatsGameLevel()

const Photon::TrafficStatsGameLevel & getTrafficStatsGameLevel ( void ) const

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

§ getQuickResendAttempts()

nByte getQuickResendAttempts ( void ) const

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

§ setQuickResendAttempts()

void setQuickResendAttempts ( nByte quickResendAttempts )

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.

§ getChannelCountUserChannels()

nByte getChannelCountUserChannels ( void ) const

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.

§ getPeerCount()

short getPeerCount ( void )

static

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

§ getState()

int getState ( void ) const

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

§ getMasterserverAddress()

const JString & getMasterserverAddress ( void ) const

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

§ getCountPlayersIngame()

int getCountPlayersIngame ( void ) const

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.

§ getCountGamesRunning()

int getCountGamesRunning ( void ) const

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.

§ getCountPlayersOnline()

int getCountPlayersOnline ( void ) const

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.

§ getCurrentlyJoinedRoom()

MutableRoom & getCurrentlyJoinedRoom ( void )

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.

§ getRoomList()

const JVector< Room * > & getRoomList ( void ) const

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()

§ getRoomNameList()

const JVector< JString > & getRoomNameList ( void ) const

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()

§ getIsInRoom()

bool getIsInRoom ( void ) const

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()

§ getIsInGameRoom()

bool getIsInGameRoom ( void ) const

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

See also: getIsInRoom(), getIsInLobby()

§ getIsInLobby()

bool getIsInLobby ( void ) const

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

See also: getIsInRoom(), getIsInGameRoom()

§ getAutoJoinLobby()

bool getAutoJoinLobby ( void ) const

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()

§ setAutoJoinLobby()

void setAutoJoinLobby ( bool autoJoinLobby )

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()

§ getLocalPlayer()

MutablePlayer & getLocalPlayer ( void )

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

§ getFriendList()

const JVector< FriendInfo > & getFriendList ( void ) const

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()

§ getFriendListAge()

int getFriendListAge ( void ) const

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.

§ getDisconnectedCause()

int getDisconnectedCause ( void ) const

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.

§ getUserID()

const JString & getUserID ( void ) const

Returns: the unique user ID

See also: setUserID()

§ getRegionWithBestPing()

const JString & getRegionWithBestPing ( void ) const

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.

Photon C++ Client API: Client Class Reference

Photon C++ Client API

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

§ Client()

§ ~Client()

Member Function Documentation

§ connect()

§ disconnect()

§ service()

§ serviceBasic()

§ opCustom()

§ sendOutgoingCommands()

§ sendAcksOnly()

§ dispatchIncomingCommands()

§ fetchServerTimestamp()

§ resetTrafficStats()

§ resetTrafficStatsMaximumCounters()

§ vitalStatsToString()

§ opJoinLobby()

§ opLeaveLobby()

§ opCreateRoom()

§ opJoinOrCreateRoom()

§ opJoinRoom()

§ opJoinRandomRoom()

§ opLeaveRoom()

§ opRaiseEvent() [1/3]

§ opRaiseEvent() [2/3]

§ opRaiseEvent() [3/3]

§ opFindFriends()

§ opLobbyStats()

§ opChangeGroups()

§ opCustomAuthenticationSendNextStepData()

§ opWebRpc() [1/4]

§ opWebRpc() [2/4]

§ opWebRpc() [3/4]

§ opWebRpc() [4/4]

§ selectRegion()

§ reconnectAndRejoin()

§ sendDirect() [1/6]

§ sendDirect() [2/6]

§ sendDirect() [3/6]

§ sendDirect() [4/6]

§ sendDirect() [5/6]

§ sendDirect() [6/6]

§ getServerTimeOffset()

§ getServerTime()

§ getBytesOut()

§ getBytesIn()

§ getByteCountCurrentDispatch()

§ getByteCountLastOperation()

§ getSentCountAllowance()

§ setSentCountAllowance()

§ getTimePingInterval()

§ setTimePingInterval()

§ getRoundTripTime()

§ getRoundTripTimeVariance()

§ getTimestampOfLastSocketReceive()

§ getDebugOutputLevel()

§ setDebugOutputLevel()

§ getLogFormatOptions()

§ setLogFormatOptions()

§ getIncomingReliableCommandsCount()

§ getPeerID()

§ getDisconnectTimeout()

§ setDisconnectTimeout()

§ getQueuedIncomingCommands()

§ getQueuedOutgoingCommands()

§ getIsPayloadEncryptionAvailable()

§ getIsEncryptionAvailable()

§ getResentReliableCommands()

§ getLimitOfUnreliableCommands()

§ setLimitOfUnreliableCommands()

§ getCRCEnabled()

§ setCRCEnabled()

§ getPacketLossByCRC()

§ getTrafficStatsEnabled()

§ setTrafficStatsEnabled()