Photon C++ Client API: LitePeer Class Reference

Photon C++ Client API

Photon C++ Client API  4.1.12.2
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, typename Common::Helpers::ArrayLengthType< Ftype >::type 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 short *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)
 
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, typename Common::Helpers::ArrayLengthType< Ftype >::type arrSize)
 
template<typename Ftype >
bool connect (const Common::JString &ipAddr, const Common::JString &appID, const Ftype pCustomDataArray, const short *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, const Common::JVector< nByte > &HMACSecret)
 
PhotonListenergetListener (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::LogFormatOptionsgetLogFormatOptions (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 TrafficStatsgetTrafficStatsIncoming (void) const
 
const TrafficStatsgetTrafficStatsOutgoing (void) const
 
const TrafficStatsGameLevelgetTrafficStatsGameLevel (void) const
 
nByte getQuickResendAttempts (void) const
 
void setQuickResendAttempts (nByte quickResendAttempts)
 
nByte getConnectionProtocol (void) const
 
void setConnectionProtocol (nByte connectionProtocol)
 
nByte getChannelCountUserChannels (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
listenerPointer 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.
connectionProtocolProtocol 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
reliabletrue = operation will be sent reliably; false = no resend in case of packet loss - will be ignored, when not using UDP as protocol
parametersthe 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
eventCodenumber for arbitrary classification of the type of event (like '1' for position updates, '2' for chat messages, and so on).
channelIDthe logical channel, default is 0. See Fragmentation and Channels for more information.
eventCachinghas to be one of the constants specified in EventCache, default is EventCache::DO_NOT_CACHE
targetPlayersthe actorNrs of the clients, which should receive the event, set to NULL, to send the event to all actors in the room
numTargetPlayersthe number of actorNrs passed (array size)
receiverGrouphas to be one of the constants specified in ReceiverGroup, default is ReceiverGroup::OTHERS
interestGroupdefines 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,
typename Common::Helpers::ArrayLengthType< Ftype >::type  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
reliabletrue = operation will be sent reliably; false = no resend in case of packet loss - will be ignored, when not using UDP as protocol
pParameterArraythe 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
arrSizethe number of elements in pParameterArray
eventCodenumber for arbitrary classification of the type of event (like '1' for position updates, '2' for chat messages, and so on).
channelIDthe logical channel, default is 0. See Fragmentation and Channels for more information.
eventCachinghas to be one of the constants specified in EventCache, default is EventCache::DO_NOT_CACHE
targetPlayersthe actorNrs of the clients, which should receive the event, set to NULL, to send the event to all actors in the room
numTargetPlayersthe number of actorNrs passed (array size)
receiverGrouphas to be one of the constants specified in ReceiverGroup, default is ReceiverGroup::OTHERS
interestGroupdefines 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 short *  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
reliabletrue = operation will be sent reliably; false = no resend in case of packet loss - will be ignored, when not using UDP as protocol
pParameterArraythe 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
pArrSizesan array holding the number of elements for each dimension of pParameterArray
eventCodenumber for arbitrary classification of the type of event (like '1' for position updates, '2' for chat messages, and so on).
channelIDthe logical channel, default is 0. See Fragmentation and Channels for more information.
eventCachinghas to be one of the constants specified in EventCache, default is EventCache::DO_NOT_CACHE
targetPlayersthe actorNrs of the clients, which should receive the event, set to NULL, to send the event to all actors in the room
numTargetPlayersthe number of actorNrs passed (array size)
receiverGrouphas to be one of the constants specified in ReceiverGroup, default is ReceiverGroup::OTHERS
interestGroupdefines 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
gameIdany ID string to identify the game
gamePropertiesoptional, set of game properties, by convention: only used if game is new/created
actorPropertiesoptional, set of actor properties
broadcastActorPropertiestrue 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
pGroupsToRemoveGroups to remove from interest. NULL will not leave any. A &JVector<nByte>() will remove all.
pGroupsToAddGroups 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
actorNrthe actorNr of the player for whom properties are being provided
propertiesthe properties to add or update for this player. See Photon Properties for more information
broadcastpassing true will send the event EV_SETPROPERTIES to all other players in the game
channelIDthe 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
propertiesthe properties to add or update for this room. See Photon Properties for more information
broadcastpassing true will send the event EV_SETPROPERTIES to all other players in the game
channelIDthe 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
channelIDthe 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
propertiesan array of the key strings to the requested properties, pass NULL to get all properties for the requested actors
numPropertiesthe number of the key strings passed (array size)
actorNrListthe list of actorNrs of the players for whom to request properties, pass NULL to get the requested properties for all actors
numActorsthe number of actorNrs passed (array size)
channelIDthe 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
propertiesan array of the byte keys to the requested properties, pass NULL to get all properties for the requested actors
numPropertiesthe number of the key strings passed (array size)
actorNrListthe list of actorNrs of the players for whom to request properties, pass NULL to get the requested properties for all actors
numActorsthe number of actorNrs passed (array size)
channelIDthe 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
propertiesan array of the key strings of the properties to request, pass NULL to get all properties
numPropertiesthe number of the key strings passed (array size)
channelIDthe 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
propertiesan array of the byte keys to the requested properties, pass NULL to get all properties
numPropertiesthe number of the key bytes passed (array size)
channelIDthe channel index. See Fragmentation and Channels