Photon .NET Client API
Public Member Functions | Public Attributes | Properties | List of all members
ExitGames.Client.Photon.Chat.ChatClient Class Reference

Central class of the Photon Chat API to connect, handle channels and messages. More...

Inheritance diagram for ExitGames.Client.Photon.Chat.ChatClient:
ExitGames.Client.Photon.IPhotonPeerListener

Public Member Functions

 ChatClient (IChatClientListener listener, ConnectionProtocol protocol=ConnectionProtocol.Udp)
 
bool Connect (string appId, string appVersion, AuthenticationValues authValues)
 Connects this client to the Photon Chat Cloud service, which will also authenticate the user (and set a UserId). More...
 
void Service ()
 Must be called regularly to keep connection between client and server alive and to process incoming messages. More...
 
void Disconnect ()
 
void StopThread ()
 
bool Subscribe (string[] channels)
 Sends operation to subscribe to a list of channels by name. More...
 
bool Subscribe (string[] channels, int messagesFromHistory)
 Sends operation to subscribe client to channels, optionally fetching a number of messages from the cache. More...
 
bool Unsubscribe (string[] channels)
 Unsubscribes from a list of channels, which stops getting messages from those. More...
 
bool PublishMessage (string channelName, object message)
 Sends a message to a public channel which this client subscribed to. More...
 
bool SendPrivateMessage (string target, object message)
 Sends a private message to a single target user. Calls OnPrivateMessage on the receiving client. More...
 
bool SendPrivateMessage (string target, object message, bool encrypt)
 Sends a private message to a single target user. Calls OnPrivateMessage on the receiving client. More...
 
bool SetOnlineStatus (int status)
 Sets the user's status without changing your status-message. More...
 
bool SetOnlineStatus (int status, object message)
 Sets the user's status without changing your status-message. More...
 
bool AddFriends (string[] friends)
 Adds friends to a list on the Chat Server which will send you status updates for those. More...
 
bool RemoveFriends (string[] friends)
 Removes the provided entries from the list on the Chat Server and stops their status updates. More...
 
string GetPrivateChannelNameByUser (string userName)
 Get you the (locally used) channel name for the chat between this client and another user. More...
 
bool TryGetChannel (string channelName, bool isPrivate, out ChatChannel channel)
 Simplified access to either private or public channels by name. More...
 
bool TryGetChannel (string channelName, out ChatChannel channel)
 Simplified access to all channels by name. Checks public channels first, then private ones. More...
 
void SendAcksOnly ()
 

Public Attributes

readonly Dictionary< string,
ChatChannel
PublicChannels
 
readonly Dictionary< string,
ChatChannel
PrivateChannels
 

Properties

string NameServerAddress [get, set]
 The address of last connected Name Server. More...
 
string FrontendAddress [get, set]
 The address of the actual chat server assigned from NameServer. Public for read only. More...
 
string ChatRegion [get, set]
 Settable only before you connect! Defaults to "EU". More...
 
ChatState State [get, set]
 Current state of the ChatClient. Also use CanChat. More...
 
ChatDisconnectCause DisconnectedCause [get, set]
 
bool CanChat [get]
 
string AppVersion [get, set]
 The version of your client. A new version also creates a new "virtual app" to separate players from older client versions. More...
 
string AppId [get, set]
 The AppID as assigned from the Photon Cloud. If you host yourself, this is the "regular" Photon Server Application Name (most likely: "LoadBalancing"). More...
 
AuthenticationValues AuthValues [get, set]
 Settable only before you connect! More...
 
string UserId [get, set]
 The unique ID of a user/person, stored in AuthValues.UserId. Set it before you connect. More...
 
DebugLevel DebugOut [get, set]
 Sets the level (and amount) of debug output provided by the library. More...
 

Detailed Description

Central class of the Photon Chat API to connect, handle channels and messages.

This class must be instantiated with a IChatClientListener instance to get the callbacks. Integrate it into your game loop by calling Service regularly. Call Connect with an AppId that is setup as Photon Chat application. Note: Connect covers multiple messages between this client and the servers. A short workflow will connect you to a chat server.

Each ChatClient resembles a user in chat (set in Connect). Each user automatically subscribes a channel for incoming private messages and can message any other user privately. Before you publish messages in any non-private channel, that channel must be subscribed.

PublicChannels is a list of subscribed channels, containing messages and senders. PrivateChannels contains all incoming and sent private messages.

Constructor & Destructor Documentation

ExitGames.Client.Photon.Chat.ChatClient.ChatClient ( IChatClientListener  listener,
ConnectionProtocol  protocol = ConnectionProtocol.Udp 
)
inline

Member Function Documentation

bool ExitGames.Client.Photon.Chat.ChatClient.AddFriends ( string[]  friends)
inline

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

AddFriends and RemoveFriends enable clients to handle their friend list in the Photon Chat server. Having users on your friends list gives you access to their current online status (and whatever info your client sets in it).

Each user can set an online status consisting of an integer and an arbitratry (serializable) object. The object can be null, Hashtable, object[] or anything else Photon can serialize.

The status is published automatically to friends (anyone who set your user ID with AddFriends).

Photon flushes friends-list when a chat client disconnects, so it has to be set each time. If your community API gives you access to online status already, you could filter and set online friends in AddFriends.

Actual friend relations are not persistent and have to be stored outside of Photon.

Parameters
friendsArray of friend userIds.
Returns
If the operation could be sent.
bool ExitGames.Client.Photon.Chat.ChatClient.Connect ( string  appId,
string  appVersion,
AuthenticationValues  authValues 
)
inline

Connects this client to the Photon Chat Cloud service, which will also authenticate the user (and set a UserId).

Parameters
appIdGet your Photon Chat AppId from the Dashboard.
appVersionAny version string you make up. Used to separate users and variants of your clients, which might be incompatible.
authValuesValues for authentication. You can leave this null, if you set a UserId before. If you set authValues, they will override any UserId set before.
Returns
void ExitGames.Client.Photon.Chat.ChatClient.Disconnect ( )
inline
string ExitGames.Client.Photon.Chat.ChatClient.GetPrivateChannelNameByUser ( string  userName)
inline

Get you the (locally used) channel name for the chat between this client and another user.

Parameters
userNameRemote user's name or UserId.
Returns
The (locally used) channel name for a private channel.
bool ExitGames.Client.Photon.Chat.ChatClient.PublishMessage ( string  channelName,
object  message 
)
inline

Sends a message to a public channel which this client subscribed to.

Before you publish to a channel, you have to subscribe it. Everyone in that channel will get the message.

Parameters
channelNameName of the channel to publish to.
messageYour message (string or any serializable data).
Returns
False if the client is not yet ready to send messages.
bool ExitGames.Client.Photon.Chat.ChatClient.RemoveFriends ( string[]  friends)
inline

Removes the provided entries from the list on the Chat Server and stops their status updates.

Photon flushes friends-list when a chat client disconnects. Unless you want to remove individual entries, you don't have to RemoveFriends.

AddFriends and RemoveFriends enable clients to handle their friend list in the Photon Chat server. Having users on your friends list gives you access to their current online status (and whatever info your client sets in it).

Each user can set an online status consisting of an integer and an arbitratry (serializable) object. The object can be null, Hashtable, object[] or anything else Photon can serialize.

The status is published automatically to friends (anyone who set your user ID with AddFriends).

Photon flushes friends-list when a chat client disconnects, so it has to be set each time. If your community API gives you access to online status already, you could filter and set online friends in AddFriends.

Actual friend relations are not persistent and have to be stored outside of Photon.

AddFriends and RemoveFriends enable clients to handle their friend list in the Photon Chat server. Having users on your friends list gives you access to their current online status (and whatever info your client sets in it).

Each user can set an online status consisting of an integer and an arbitratry (serializable) object. The object can be null, Hashtable, object[] or anything else Photon can serialize.

The status is published automatically to friends (anyone who set your user ID with AddFriends).

Actual friend relations are not persistent and have to be stored outside of Photon.

Parameters
friendsArray of friend userIds.
Returns
If the operation could be sent.
void ExitGames.Client.Photon.Chat.ChatClient.SendAcksOnly ( )
inline
bool ExitGames.Client.Photon.Chat.ChatClient.SendPrivateMessage ( string  target,
object  message 
)
inline

Sends a private message to a single target user. Calls OnPrivateMessage on the receiving client.

Parameters
targetUsername to send this message to.
messageThe message you want to send. Can be a simple string or anything serializable.
Returns
True if this clients can send the message to the server.
bool ExitGames.Client.Photon.Chat.ChatClient.SendPrivateMessage ( string  target,
object  message,
bool  encrypt 
)
inline

Sends a private message to a single target user. Calls OnPrivateMessage on the receiving client.

Parameters
targetUsername to send this message to.
messageThe message you want to send. Can be a simple string or anything serializable.
encryptOptionally, private messages can be encrypted. Encryption is not end-to-end as the server decrypts the message.
Returns
True if this clients can send the message to the server.
void ExitGames.Client.Photon.Chat.ChatClient.Service ( )
inline

Must be called regularly to keep connection between client and server alive and to process incoming messages.

This method limits the effort it does automatically using the private variable msDeltaForServiceCalls. That value is lower for connect and multiplied by 4 when chat-server connection is ready.

bool ExitGames.Client.Photon.Chat.ChatClient.SetOnlineStatus ( int  status)
inline

Sets the user's status without changing your status-message.

The predefined status values can be found in class ChatUserStatus. State ChatUserStatus.Invisible will make you offline for everyone and send no message.

You can set custom values in the status integer. Aside from the pre-configured ones, all states will be considered visible and online. Else, no one would see the custom state.

This overload does not change the set message.

Parameters
statusPredefined states are in class ChatUserStatus. Other values can be used at will.
Returns
True if the operation gets called on the server.
bool ExitGames.Client.Photon.Chat.ChatClient.SetOnlineStatus ( int  status,
object  message 
)
inline

Sets the user's status without changing your status-message.

The predefined status values can be found in class ChatUserStatus. State ChatUserStatus.Invisible will make you offline for everyone and send no message.

You can set custom values in the status integer. Aside from the pre-configured ones, all states will be considered visible and online. Else, no one would see the custom state.

The message object can be anything that Photon can serialize, including (but not limited to) Hashtable, object[] and string. This value is defined by your own conventions.

Parameters
statusPredefined states are in class ChatUserStatus. Other values can be used at will.
messageAlso sets a status-message which your friends can get.
Returns
True if the operation gets called on the server.
void ExitGames.Client.Photon.Chat.ChatClient.StopThread ( )
inline
bool ExitGames.Client.Photon.Chat.ChatClient.Subscribe ( string[]  channels)
inline

Sends operation to subscribe to a list of channels by name.

Parameters
channelsList of channels to subscribe to. Avoid null or empty values.
Returns
If the operation could be sent at all (Example: Fails if not connected to Chat Server).
bool ExitGames.Client.Photon.Chat.ChatClient.Subscribe ( string[]  channels,
int  messagesFromHistory 
)
inline

Sends operation to subscribe client to channels, optionally fetching a number of messages from the cache.

Subscribes channels will forward new messages to this user. Use PublishMessage to do so. The messages cache is limited but can be useful to get into ongoing conversations, if that's needed.

Parameters
channelsList of channels to subscribe to. Avoid null or empty values.
messagesFromHistory0: no history. 1 and higher: number of messages in history. -1: all available history.
Returns
If the operation could be sent at all (Example: Fails if not connected to Chat Server).
bool ExitGames.Client.Photon.Chat.ChatClient.TryGetChannel ( string  channelName,
bool  isPrivate,
out ChatChannel  channel 
)
inline

Simplified access to either private or public channels by name.

Parameters
channelNameName of the channel to get. For private channels, the channel-name is composed of both user's names.
isPrivateDefine if you expect a private or public channel.
channelOut parameter gives you the found channel, if any.
Returns
True if the channel was found.
bool ExitGames.Client.Photon.Chat.ChatClient.TryGetChannel ( string  channelName,
out ChatChannel  channel 
)
inline

Simplified access to all channels by name. Checks public channels first, then private ones.

Parameters
channelNameName of the channel to get.
channelOut parameter gives you the found channel, if any.
Returns
True if the channel was found.
bool ExitGames.Client.Photon.Chat.ChatClient.Unsubscribe ( string[]  channels)
inline

Unsubscribes from a list of channels, which stops getting messages from those.

The client will remove these channels from the PublicChannels dictionary once the server sent a response to this request.

The request will be sent to the server and IChatClientListener.OnUnsubscribed gets called when the server actually removed the channel subscriptions.

Unsubscribe will fail if you include null or empty channel names.

Parameters
channelsNames of channels to unsubscribe.
Returns
False, if not connected to a chat server.

Member Data Documentation

readonly Dictionary<string, ChatChannel> ExitGames.Client.Photon.Chat.ChatClient.PrivateChannels
readonly Dictionary<string, ChatChannel> ExitGames.Client.Photon.Chat.ChatClient.PublicChannels

Property Documentation

string ExitGames.Client.Photon.Chat.ChatClient.AppId
getset

The AppID as assigned from the Photon Cloud. If you host yourself, this is the "regular" Photon Server Application Name (most likely: "LoadBalancing").

string ExitGames.Client.Photon.Chat.ChatClient.AppVersion
getset

The version of your client. A new version also creates a new "virtual app" to separate players from older client versions.

AuthenticationValues ExitGames.Client.Photon.Chat.ChatClient.AuthValues
getset

Settable only before you connect!

bool ExitGames.Client.Photon.Chat.ChatClient.CanChat
get
string ExitGames.Client.Photon.Chat.ChatClient.ChatRegion
getset

Settable only before you connect! Defaults to "EU".

DebugLevel ExitGames.Client.Photon.Chat.ChatClient.DebugOut
getset

Sets the level (and amount) of debug output provided by the library.

This affects the callbacks to IChatClientListener.DebugReturn. Default Level: Error.

ChatDisconnectCause ExitGames.Client.Photon.Chat.ChatClient.DisconnectedCause
getset
string ExitGames.Client.Photon.Chat.ChatClient.FrontendAddress
getset

The address of the actual chat server assigned from NameServer. Public for read only.

string ExitGames.Client.Photon.Chat.ChatClient.NameServerAddress
getset

The address of last connected Name Server.

ChatState ExitGames.Client.Photon.Chat.ChatClient.State
getset

Current state of the ChatClient. Also use CanChat.

string ExitGames.Client.Photon.Chat.ChatClient.UserId
getset

The unique ID of a user/person, stored in AuthValues.UserId. Set it before you connect.

This value wraps AuthValues.UserId. It's not a nickname and we assume users with the same userID are the same person.


The documentation for this class was generated from the following file: