LitePeer Class Reference

Inheritance diagram for LitePeer:

Collaboration diagram for LitePeer:

Public Member Functions
	LitePeer (Photon::PhotonListener &listener, nByte connectionProtocol=Photon::ConnectionProtocol::DEFAULT)
virtual	~LitePeer (void)
template<typename Ftype >
bool	opRaiseEvent (bool reliable, Ftype parameters, nByte eventCode, nByte channelID=0, nByte eventCaching=EventCache::DO_NOT_CACHE, const int *targetPlayers=NULL, short numTargetPlayers=0, nByte receiverGroup=ReceiverGroup::OTHERS, nByte interestGroup=0)
template<typename Ftype >
bool	opRaiseEvent (bool reliable, Ftype pParameterArray, int arrSize, nByte eventCode, nByte channelID=0, nByte eventCaching=EventCache::DO_NOT_CACHE, const int *targetPlayers=NULL, short numTargetPlayers=0, nByte receiverGroup=ReceiverGroup::OTHERS, nByte interestGroup=0)
template<typename Ftype >
bool	opRaiseEvent (bool reliable, Ftype pParameterArray, const int *pArrSizes, nByte eventCode, nByte channelID=0, nByte eventCaching=EventCache::DO_NOT_CACHE, const int *targetPlayers=NULL, short numTargetPlayers=0, nByte receiverGroup=ReceiverGroup::OTHERS, nByte interestGroup=0)
virtual bool	opJoin (const Common::JString &gameId, const Common::Hashtable &gameProperties=Common::Hashtable(), const Common::Hashtable &actorProperties=Common::Hashtable(), bool broadcastActorProperties=false)
virtual bool	opLeave (void)
virtual bool	opChangeGroups (const Common::JVector< nByte > *pGroupsToRemove, const Common::JVector< nByte > *pGroupsToAdd)
virtual bool	opSetPropertiesOfActor (int actorNr, const Common::Hashtable &properties, bool broadcast, nByte channelID=0)
virtual bool	opSetPropertiesOfGame (const Common::Hashtable &properties, bool broadcast, nByte channelID=0)
virtual bool	opGetProperties (nByte channelID=0)
virtual bool	opGetPropertiesOfActor (const Common::JString *properties, short numProperties, const int *actorNrList=NULL, short numActors=0, nByte channelID=0)
virtual bool	opGetPropertiesOfActor (const nByte *properties, short numProperties, const int *actorNrList=NULL, short numActors=0, nByte channelID=0)
virtual bool	opGetPropertiesOfGame (const Common::JString *properties, short numProperties, nByte channelID=0)
virtual bool	opGetPropertiesOfGame (const nByte *properties, short numProperties, nByte channelID=0)
Public Member Functions inherited from PhotonPeer
	PhotonPeer (PhotonListener &listener, nByte connectionProtocol=ConnectionProtocol::DEFAULT, nByte serializationProtocol=Common::SerializationProtocol::DEFAULT)
virtual	~PhotonPeer (void)
virtual bool	connect (const Common::JString &ipAddr, const Common::JString &appID=Common::JString())
template<typename Ftype >
bool	connect (const Common::JString &ipAddr, const Common::JString &appID, const Ftype &customData)
template<typename Ftype >
bool	connect (const Common::JString &ipAddr, const Common::JString &appID, const Ftype pCustomDataArray, int arrSize)
template<typename Ftype >
bool	connect (const Common::JString &ipAddr, const Common::JString &appID, const Ftype pCustomDataArray, const int *pArrSizes)
virtual void	disconnect (void)
virtual void	service (bool dispatchIncomingCommands=true)
virtual void	serviceBasic (void)
virtual bool	opCustom (const OperationRequest &operationRequest, bool sendReliable, nByte channelID=0, bool encrypt=false)
virtual bool	sendOutgoingCommands (void)
virtual bool	sendAcksOnly (void)
virtual bool	dispatchIncomingCommands (void)
virtual bool	establishEncryption (void)
virtual void	fetchServerTimestamp (void)
virtual void	resetTrafficStats (void)
virtual void	resetTrafficStatsMaximumCounters (void)
virtual Common::JString	vitalStatsToString (bool all) const
virtual void	pingServer (const Common::JString &address, unsigned int pingAttempts)
virtual void	initUserDataEncryption (const Common::JVector< nByte > &secret)
virtual void	initUDPEncryption (const Common::JVector< nByte > &encryptSecret)
PhotonListener *	getListener (void)
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	getPeerState (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
Common::JString	getServerAddress (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 trafficStasEnabled)
int	getTrafficStatsElapsedMs (void) const
const TrafficStats &	getTrafficStatsIncoming (void) const
const TrafficStats &	getTrafficStatsOutgoing (void) const
const TrafficStatsGameLevel &	getTrafficStatsGameLevel (void) const
nByte	getQuickResendAttempts (void) const
void	setQuickResendAttempts (nByte quickResendAttempts)
nByte	getConnectionProtocol (void) const
void	setConnectionProtocol (nByte connectionProtocol)
nByte	getChannelCountUserChannels (void) const
nByte	getSerializationProtocol (void) const

Additional Inherited Members
Static Public Member Functions inherited from PhotonPeer
static short	getPeerCount (void)
static unsigned int	getMaxAppIDLength (void)

Detailed Description

A LitePeer is an extended PhotonPeer and implements the operations offered by the Lite Application of the Photon Server SDK.

This class is used by many of our demos and allows rapid development of simple games. You can use rooms and properties and send events. For many games, this is a good start.

Operations are prefixed as "op" and are always asynchronous.

Constructor & Destructor Documentation

LitePeer()

LitePeer	(	Photon::PhotonListener &	listener,
		nByte	connectionProtocol = Photon::ConnectionProtocol::DEFAULT
	)

Constructor

Parameters

listener	Pointer to the application's implementation of the Listener callback interface. Has to be valid for at least the lifetime of the LitePeer instance, which is created by this constructor.
connectionProtocol	Protocol to use to connect to Photon. One of the constants specified in Photon::ConnectionProtocol.

See also

PhotonListener

Photon::ConnectionProtocol

~LitePeer()

~LitePeer ( void  )

virtual

Destructor.

Member Function Documentation

opRaiseEvent() [1/3]

template< typename Ftype > bool opRaiseEvent	(	bool	reliable,
		Ftype	parameters,
		nByte	eventCode,
		nByte	channelID = 0,
		nByte	eventCaching = EventCache::DO_NOT_CACHE,
		const int *	targetPlayers = NULL,
		short	numTargetPlayers = 0,
		nByte	receiverGroup = ReceiverGroup::OTHERS,
		nByte	interestGroup = 0
	)

Sends in-game data to all other players in the game, who will receive it in their PhotonListener::onEvent() 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. Receiving clients can access it with key EventKey::DATA.

This function provides the option to raise events reliable or unreliable. While both result in ordered events, the latter ones might be 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.

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

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.

As soon as the Photon Server acknowledged the reception of the opRaiseEvent() operation, the local application will be notified by a call to the PhotonListener::onOperationResponse() callback with the parameter opCode being set to OperationCode::RAISE_EV.

Hashtable ev;
ev.put(POS_X, player.getPositionX());
mPeer->opRaiseEvent(true, ev, eventCode);

Returns

true, if successful, false otherwise

See also

PhotonListener::onEvent(), PhotonListener::onOperationResponse(), Table of Datatypes

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
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 event (like '1' for position updates, '2' for chat messages, and so on).
channelID	the logical channel, default is 0. See Fragmentation and Channels for more information.
eventCaching	has to be one of the constants specified in EventCache, default is EventCache::DO_NOT_CACHE
targetPlayers	the actorNrs of the clients, which should receive the event, set to NULL, to send the event to all actors in the room
numTargetPlayers	the number of actorNrs passed (array size)
receiverGroup	has to be one of the constants specified in ReceiverGroup, default is ReceiverGroup::OTHERS
interestGroup	defines to which interest group the event is sent. Players can subscribe or unsubscribe to groups. Group 0 is always sent to all, default is 0.

opRaiseEvent() [2/3]

template< typename Ftype > bool opRaiseEvent	(	bool	reliable,
		Ftype	pParameterArray,
		int	arrSize,
		nByte	eventCode,
		nByte	channelID = 0,
		nByte	eventCaching = EventCache::DO_NOT_CACHE,
		const int *	targetPlayers = NULL,
		short	numTargetPlayers = 0,
		nByte	receiverGroup = ReceiverGroup::OTHERS,
		nByte	interestGroup = 0
	)

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).
channelID	the logical channel, default is 0. See Fragmentation and Channels for more information.
eventCaching	has to be one of the constants specified in EventCache, default is EventCache::DO_NOT_CACHE
targetPlayers	the actorNrs of the clients, which should receive the event, set to NULL, to send the event to all actors in the room
numTargetPlayers	the number of actorNrs passed (array size)
receiverGroup	has to be one of the constants specified in ReceiverGroup, default is ReceiverGroup::OTHERS
interestGroup	defines to which interest group the event is sent. Players can subscribe or unsubscribe to groups. Group 0 is always sent to all, default is 0.

opRaiseEvent() [3/3]

template< typename Ftype > bool opRaiseEvent	(	bool	reliable,
		Ftype	pParameterArray,
		const int *	pArrSizes,
		nByte	eventCode,
		nByte	channelID = 0,
		nByte	eventCaching = EventCache::DO_NOT_CACHE,
		const int *	targetPlayers = NULL,
		short	numTargetPlayers = 0,
		nByte	receiverGroup = ReceiverGroup::OTHERS,
		nByte	interestGroup = 0
	)

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).
channelID	the logical channel, default is 0. See Fragmentation and Channels for more information.
eventCaching	has to be one of the constants specified in EventCache, default is EventCache::DO_NOT_CACHE
targetPlayers	the actorNrs of the clients, which should receive the event, set to NULL, to send the event to all actors in the room
numTargetPlayers	the number of actorNrs passed (array size)
receiverGroup	has to be one of the constants specified in ReceiverGroup, default is ReceiverGroup::OTHERS
interestGroup	defines to which interest group the event is sent. Players can subscribe or unsubscribe to groups. Group 0 is always sent to all, default is 0.

opJoin()

bool opJoin ( const Common::JString &  gameId, const Common::Hashtable &  gameProperties = Common::Hashtable(), const Common::Hashtable &  actorProperties = Common::Hashtable(), bool  broadcastActorProperties = false  )

virtual

This function joins the room with the given name on the Photon Server.

This operation will join an existing room by name or create one if the name is not in use yet.

Rooms (or games) are simply identified by name. Lite assumes that users always want to get into a room - no matter if it existed before or not, so it might be a new one. If you want to make sure a room is created (new, empty), the client side might come up with a unique name for it (make sure the name was not taken yet).

The application "Lite Lobby" lists room names and effectively allows the user to select a distinct one.

Each actor (a.k.a. player) in a room will get events that are raised for the room by any player (if he is conained in the receiver list).

To distinguish the actors, each gets a consecutive actornumber. This is used in events to mark who triggered the event. A client finds out it's own actornumber in the return callback for operation Join. Number 1 is the lowest actornumber in each room and the client with that actornumber created the room.

Each client could easily send custom data around. If the data should be available to newcomers, it makes sense to use Properties.

Joining a room will result in a call to PhotonListener::onOperationResponse(), with the opCode being set to OPC_RT_JOIN. Joining a room will also trigger an event EV_RT_JOIN for all players in the room, to inform them about the new player.

Parameters

gameId	any ID string to identify the game
gameProperties	optional, set of game properties, by convention: only used if game is new/created
actorProperties	optional, set of actor properties
broadcastActorProperties	true to broadcast actor proprties in join/-event, false to not broadcast them, default is false

Returns

true, if successful, false otherwise

See also

PhotonListener::onEvent(), PhotonListener::onOperationResponse(), opLeave()

opLeave()

bool opLeave ( void  )

virtual

Leaves a room, which has been previously joined with opJoin().

Leaving a room will result in a call to PhotonListener::onOperationResponse() with the opCode being set to OPC_RT_LEAVE. This operation also triggers an event EV_RT_LEAVE for the remaining players in the room. This event includes the number of the player who left in key EV_RT_KEY_ACTORNR.

Returns

true, if successful, false otherwise

See also

PhotonListener::onEvent(), PhotonListener::onOperationResponse(), opJoin()

opChangeGroups()

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

virtual

Operation to handle this client's interest groups (for events inside rooms).

Note the difference between passing NULL and &JVector<nByte>(): NULL won't add/remove any groups. &JVector<nByte>() will add/remove all (existing) groups. First, removing groups is executed. This way, you could leave all groups and join only the ones provided.

Parameters

pGroupsToRemove	Groups to remove from interest. NULL will not leave any. A &JVector<nByte>() will remove all.
pGroupsToAdd	Groups to add to interest. NULL will not add any. A &JVector<nByte>() will add all current.

Returns

true, if successful, false otherwise

opSetPropertiesOfActor()

bool opSetPropertiesOfActor ( int  actorNr, const Common::Hashtable &  properties, bool  broadcast, nByte  channelID = 0  )

virtual

Adds or updates properties for the player, to whom the passed actorNr. belongs to

Parameters

actorNr	the actorNr of the player for whom properties are being provided
properties	the properties to add or update for this player. See Photon Properties for more information
broadcast	passing true will send the event EV_SETPROPERTIES to all other players in the game
channelID	the channelIndex, see Fragmentation and Channels. Default is 0

Returns

true, if successful, false otherwise

See also

Photon Properties, opGetPropertiesOfActor()

opSetPropertiesOfGame()

bool opSetPropertiesOfGame ( const Common::Hashtable &  properties, bool  broadcast, nByte  channelID = 0  )

virtual

Adds or updates properties for the currently joined room.

Parameters

properties	the properties to add or update for this room. See Photon Properties for more information
broadcast	passing true will send the event EV_SETPROPERTIES to all other players in the game
channelID	the channelIndex, see Fragmentation and Channels. Default is 0

Returns

true, if successful, false otherwise

See also

Photon Properties, opGetPropertiesOfGame()

opGetProperties()

bool opGetProperties ( nByte  channelID = 0 )

virtual

Creates a request to get all properties of the currently joined room and all players, which are inside it at the moment, when the server processes this operation. See Photon Properties

Parameters

channelID

the channel index. See Fragmentation and Channels

Returns

true, if successful, false otherwise

See also

Photon Properties

opGetPropertiesOfActor() [1/2]

bool opGetPropertiesOfActor ( const Common::JString *  properties, short  numProperties, const int *  actorNrList = NULL, short  numActors = 0, nByte  channelID = 0  )

virtual

Creates a request to get the selected properties of the players with the specified actor numbers.

See Photon Properties

Parameters

properties	an array of the key strings to the requested properties, pass NULL to get all properties for the requested actors
numProperties	the number of the key strings passed (array size)
actorNrList	the list of actorNrs of the players for whom to request properties, pass NULL to get the requested properties for all actors
numActors	the number of actorNrs passed (array size)
channelID	the channel index. See Fragmentation and Channels

Returns

true, if successful, false otherwise

See also

Photon Properties, opSetPropertiesOfActor()

opGetPropertiesOfActor() [2/2]

bool opGetPropertiesOfActor ( const nByte *  properties, short  numProperties, const int *  actorNrList = NULL, short  numActors = 0, nByte  channelID = 0  )

virtual

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

Parameters

properties	an array of the byte keys to the requested properties, pass NULL to get all properties for the requested actors
numProperties	the number of the key strings passed (array size)
actorNrList	the list of actorNrs of the players for whom to request properties, pass NULL to get the requested properties for all actors
numActors	the number of actorNrs passed (array size)
channelID	the channel index. See Fragmentation and Channels

opGetPropertiesOfGame() [1/2]

bool opGetPropertiesOfGame ( const Common::JString *  properties, short  numProperties, nByte  channelID = 0  )

virtual

Creates a request to get the selected properties of the currently joined room.

See Photon Properties

Parameters

properties	an array of the key strings of the properties to request, pass NULL to get all properties
numProperties	the number of the key strings passed (array size)
channelID	the channel index. See Fragmentation and Channels

Returns

true, if successful, false otherwise

See also

Photon Properties, opSetPropertiesOfGame()

opGetPropertiesOfGame() [2/2]

bool opGetPropertiesOfGame ( const nByte *  properties, short  numProperties, nByte  channelID = 0  )

virtual

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

Parameters

properties	an array of the byte keys to the requested properties, pass NULL to get all properties
numProperties	the number of the key bytes passed (array size)
channelID	the channel index. See Fragmentation and Channels