Module chat.ChatClient
Implements Photon Chat API workflow.
Inherits folowing loadbalancing.LoadBalancingClient functions:
instance:service
instance:setCustomAuthentication
instance:connectToNameServer
instance:getRegions
instance:onGetRegionsResult
instance:isConnectedToNameServer
instance:disconnect
instance:setLogLevel
Functions
| new (serverAddress, appId, appVersion) | Creates instance of Photon ChatClient. |
| instance:onStateChange (state) | Called on client state change. |
| instance:onError (errorCode, errorMsg) | Called if client error occures. |
| instance:onSubscribeResult (results) | Called when subscribe request completed. |
| instance:onUnsubscribeResult (results) | Called when unsubscribe request completed. |
| instance:onChatMessages (channelName, messages) | Called when new chat messages received. |
| instance:onPrivateMessage (channelName, message) | Called when new private message received. |
| instance:onUserStatusUpdate (userId, status, gotMessage, statusMessage) | Called when user from friend list changes state. |
| instance:connectToRegionFrontEnd (region) | Connects to a specific region's FrontEnd server, using the NameServer to find the IP. |
| instance:isConnectedToFrontEnd () | Returns true if client connected to Front End. |
| instance:subscribe (channelNames, options) | Sends operation to subscribe to a list of channels by name. Override onSubscribeResult to handle request results. |
| instance:unsubscribe (channelNames) | Sends operation to unsubscribe from a list of channels by name. Override onUnsubscribeResult to handle request results. |
| instance:publishMessage (channelName, content, options) | Sends a message to a public channel. Channel should be subscribed before publishing to it. |
| instance:sendPrivateMessage (userId, content, options) | Sends a private message to a single target user. |
| instance:setUserStatus (status, statusMessage, skipMessage) | Sets the user's status (pre-defined or custom) and an optional message. The predefined status values can be found in constants.UserStatus. |
| instance:addFriends (userIds) | Adds users to the list on the Chat Server which will send you status updates for those. |
| instance:removeFriends (userIds) | Removes users from the list on the Chat Server which will send you status updates for those. |
| instance:getPublicChannels () | Returns list of public channels client subscribed to. |
| instance:getPrivateChannels () | Returns list of channels representing current private conversation. |
Tables
| PeerErrorCode | Enum for client peers error codes. |
| State | Enum for client states. |
Functions
- new (serverAddress, appId, appVersion)
-
Creates instance of Photon ChatClient. Override instance methods to handle system or custom events and operation responses.
Parameters:
- serverAddress string or table Server address:port.
- appId string Cloud application ID.
- appVersion string Cloud application version.
Returns:
-
ChatClient
instance
- instance:onStateChange (state)
-
Called on client state change. Override to handle it.
Parameters:
- state State New client state.
- instance:onError (errorCode, errorMsg)
-
Called if client error occures. Override to handle it.
Parameters:
- errorCode PeerErrorCode Client error code.
- errorMsg string Error message.
- instance:onSubscribeResult (results)
-
Called when subscribe request completed.
Override to handle request results.Parameters:
- results table Table with channel names as keys and boolean results as values.
- instance:onUnsubscribeResult (results)
-
Called when unsubscribe request completed.
Override to handle request results.Parameters:
- results table Table with channel names as keys and boolean results as values.
- instance:onChatMessages (channelName, messages)
-
Called when new chat messages received.
Override to handle messages receive event.Parameters:
- channelName string Chat channel name.
- messages table Array of received chat.Message's.
- instance:onPrivateMessage (channelName, message)
-
Called when new private message received.
Override to handle message receive event.Parameters:
- channelName string Private channel name (counterpart user id).
- message chat.Message Received message.
- instance:onUserStatusUpdate (userId, status, gotMessage, statusMessage)
-
Called when user from friend list changes state.
Override to handle change state event.Parameters:
- userId string User id.
- status int New User status. Predefined constants.UserStatus or custom.
- gotMessage boolean True if status message updated.
- statusMessage string Optional status message (may be nil even if gotMessage = true).
- instance:connectToRegionFrontEnd (region)
-
Connects to a specific region's FrontEnd server, using the NameServer to find the IP.
Parameters:
- region string Region connect to FrontEnd server of.
Returns:
-
boolean
True if current client state allows connection.
- instance:isConnectedToFrontEnd ()
-
Returns true if client connected to Front End. When connected, client can send messages, subscribe to channels and so on.
Returns:
-
boolean
True if connected.
- instance:subscribe (channelNames, options)
-
Sends operation to subscribe to a list of channels by name.
Override onSubscribeResult to handle request results.Parameters:
- channelNames table Array of channel names to subscribe to.
- options
optional table
Additional options:
historyLength: (int) Controls messages history sent on subscription. nil or 0: no history. 1 and higher: number of messages in history. -1: all history.
lastIds: (table) Array of IDs of last messages received per channel. Useful when re subscribing to receive only messages we missed.
Returns:
-
boolean
True if operation sent.
- instance:unsubscribe (channelNames)
-
Sends operation to unsubscribe from a list of channels by name.
Override onUnsubscribeResult to handle request results.Parameters:
- channelNames table Array of channel names to unsubscribe from.
Returns:
-
boolean
True if operation sent.
- instance:publishMessage (channelName, content, options)
-
Sends a message to a public channel.
Channel should be subscribed before publishing to it. Everyone in that channel will get the message.Parameters:
- channelName string Channel name to send message to.
- content Text string or arbitrary data to send.
- options
optional table
Additional options:
webForward: (boolean) Optionally, private messages can be forwarded as webhooks. Configure webhooks for your Chat app to use this.
Returns:
-
boolean
True if message sent.
- instance:sendPrivateMessage (userId, content, options)
-
Sends a private message to a single target user.
Parameters:
- userId string User id to send this message to.
- content Text string or arbitrary data to send.
- options
optional table
Additional options:
encrypt: (boolean) Encrypt sending message.
webForward: (boolean) Optionally, private messages can be forwarded as webhooks. Configure webhooks for your Chat app to use this.
Returns:
-
boolean
True if message sent.
- instance:setUserStatus (status, statusMessage, skipMessage)
-
Sets the user's status (pre-defined or custom) and an optional message.
The predefined status values can be found in constants.UserStatus. State UserStatus.Invisible will make you offline for everyone and send no message.Parameters:
- status int User status to set.
- statusMessage optional string State message (defaults to nil).
- skipMessage optional boolean If true then client does not send state message.
Returns:
-
boolean
True if command sent.
- instance:addFriends (userIds)
-
Adds users to the list on the Chat Server which will send you status updates for those.
Parameters:
- userIds table Array of user ids.
Returns:
-
boolean
True if command sent.
- instance:removeFriends (userIds)
-
Removes users from the list on the Chat Server which will send you status updates for those.
Parameters:
- userIds table Array of user ids.
Returns:
-
boolean
True if command sent.
- instance:getPublicChannels ()
-
Returns list of public channels client subscribed to.
Returns:
-
table
Array of public chat.Channel's.
- instance:getPrivateChannels ()
-
Returns list of channels representing current private conversation.
Returns:
-
table
Array of private chat.Channel's.
Tables
- PeerErrorCode
-
Enum for client peers error codes.
Fields:
- Ok No Error.
- FrontEndError General Front End server peer error.
- FrontEndConnectFailed Front End server connection error.
- FrontEndConnectClosed Disconnected from Front End server.
- FrontEndTimeout Disconnected from Front End server for timeout.
- FrontEndEncryptionEstablishError Front End server encryption establishing failed.
- FrontEndAuthenticationFailed Front End server authentication failed.
- NameServerError General NameServer peer error.
- NameServerConnectFailed NameServer connection error.
- NameServerConnectClosed Disconnected from NameServer.
- NameServerTimeout Disconnected from NameServer for timeout.
- NameServerEncryptionEstablishError NameServer encryption establishing failed.
- NameServerAuthenticationFailed NameServer authentication failed.
- State
-
Enum for client states.
Fields:
- Error Critical error occurred.
- Uninitialized Client is created but not used yet.
- ConnectingToNameServer Connecting to NameServer.
- ConnectedToNameServer Connected to NameServer.
- ConnectingToFrontEnd Connecting to FrontEnd server.
- ConnectedToFrontEnd Connected to FrontEnd server.
- Disconnected The client is no longer connected.