Photon C++ Client API: Client Class Reference

Constructor.

Parameters

listener	pointer to the application's implementation of the Chat:Listener callback interface.
applicationID	Photon Chat application id
appVersion	Photon Chat application version
connectionProtocol	connection protocol

Destructor.

Initiates a connection to the Photon name server. After a successful connection the client automatically connects to a chat front end server and goes to ConnectedToFrontEnd state. After that the client can subscribe to channels and send and receive messages.

Parameters

authenticationValues	a user's authentication values used during connect for Custom Authentication with Photon.
nameServerAddress	used to specify a name server address different from the public Photon Cloud name server

Disconnects from servers.

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

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

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

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

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

Parameters

dispatchIncomingCommands

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

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

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

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

See also

service()

This function initiates the transmission of outgoing commands.

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

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

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

Note

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

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

See also

service()

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

Note

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

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

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

Note

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

Returns

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

See also

service()

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

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

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

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

Resets traffic stats values that can be maxed out.

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

Parameters

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

Returns

stats as a string.

Sends a request to subscribe the client to the specified channels, optionally fetching messages newer than a specific ID.

Parameters

channels	list of channels to subscribe to.
messagesFromHistory	0: no history. 1 and higher: number of messages in history. -1: all history.

Returns

true if request sent

Unsubscribes the client from a list of channels.

The client will remove these channels from the PublicChannels dictionary immediately, if it could send the operation.

Parameters

channels

list of channels to unsubscribe from.

Returns

true if request sent and channels removed

Sends a message to the specified public channel.

Parameters

channelName	channel name
message	message to send

Returns

false in case of an error, true otherwise

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

Parameters

channelName	channel name
pMessageArray	message to send
arrSize	the number of elements in pParameterArray

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

Parameters

channelName	channel name
pMessageArray	message to send
pArrSizes	an array holding the number of elements for each dimension of pParameterArray

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

Parameters

userName	user name
pMessageArray	message to send
arrSize	the number of elements in pParameterArray
encrypt	true to send the message encrypted, false (default) to send it unencrypted

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

Parameters

userName	user name
pMessageArray	message to send
pArrSizes	an array holding the number of elements for each dimension of pParameterArray
encrypt	true to send the message encrypted, false (default) to send it unencrypted

Sets the user's status (pre-defined or custom) and a status message.

The predefined status values can be found in namespace UserStatus. States UserStatus::INVISIBLE and UserStatus::OFFLINE will make you offline for everyone and send no message.

Parameters

status

predefined states are in namespace UserStatus. Other values can be used at will

Returns

false in case of an error, true otherwise

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

Parameters

status	predefined states are in namespace UserStatus. Other values can be used at will
pMessageArray	optional status message
arrSize	the number of elements in pParameterArray

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

Parameters

status	predefined states are in namespace UserStatus. Other values can be used at will
pMessageArray	optional status message
pArrSizes	an array holding the number of elements for each dimension of pParameterArray

Adds users to the list on the Chat Server which will send you status updates for those.

Parameters

userIDs

list of friend user names

Returns

true if the command has been sent

Removes users from the list on the Chat Server which will send you status updates for those.

Parameters

userIDs

list of friend user names

Returns

true if the command has been sent

Returns

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

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

ServerTime = serverTimeOffset + GETTIMEMS()

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

Returns

the Photon Server's system time ins ms.

see getServerTimeOffset()

Returns

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

See also

getBytesIn()

Returns

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

See also

getBytesOut()

Returns

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

Returns

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

Returns

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

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

See also

setSentCountAllowance() getDisconnectTimeout() setDisconnectTimeout()

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

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

Parameters

sentCountAllowance

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

See also

getSentCountAllowance() getDisconnectTimeout() setDisconnectTimeout()

Returns

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

See also

setTimePingInterval()

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

Parameters

timePingInterval

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

See also

getTimePingInterval()

Returns

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

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

See also

getRoundTripTimeVariance()

Returns

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

See also

getRoundTripTime()

Returns

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

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

Returns

one of the values in DebugLevel

See also

setDebugOutputLevel()

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

Parameters

debugLevel

one of the values in DebugLevel

Returns

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

See also

getDebugOutputLevel()

Returns

the LogFormatOptions that are used by this instance.

See also

setFormatOptions()

Sets the log format options to the supplied value.

Parameters

formatOptions

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

See also

getFormatOptions()

Returns

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

Returns

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

Returns

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

See also

setDisconnectTimeout() getSentCountAllowance() setSentCountAllowance()

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

Parameters

disconnectTimeout

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

See also

getDisconnectTimeout() getSentCountAllowance() setSentCountAllowance()

Returns

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

Returns

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

Returns

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

See also

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

Returns

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

Returns

the limit for the queue of received unreliable commands.

See also

setLimitOfUnreliableCommands()

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

See also

getLimitOfUnreliableCommands()

Returns

true if CRC enabled

See also

setCRCEnabled

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

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

Note

This only has effect for UDP connections.

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

See also

getCRCEnabled

Returns

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

See also

setCRCEnabled

Returns

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

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

Returns

the count of milliseconds the stats are enabled for tracking.

Returns

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

Returns

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

Returns

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

Returns

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

Returns

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

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

Returns

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

Returns

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

Returns the unique user id.

Returns

the user id

Returns client state

Returns cause of last disconnect event.

Returns

disconnect cause constant from Chat::DisconnectCause.

See also

Chat::DisconnectCause

Returns chat (Name Server) region.

Sets chat (Name Server) region. Set it before connect() call.

Parameters

region

region

Returns list of subscribed public channels.

Returns

list of subscribed channels

Returns list of private chats that client currently has.

Returns

list of private chats

Search subscribed public channels by channel name.

Parameters

channelName

channel name to search

Returns

found channel or NULL otherwise

Search private chat by user name.

Parameters

userName

user name to search

Returns

found chat or NULL otherwise