Initializes Client instances. Note that Client instances are created automatically by ClientManager. Do not attempt to create Client instances manually.
Returns this client's unique ID, as set automatically by the server. The client's id persists for the length of the client connection, and cannot be changed during that connection. A client's ID expires when the client disconnects.
Note that only two things are guaranteed about the client ID:
The client ID of the current client is available only after the OrbiterEvent.READY event occurs.
Note that in addition to having a client ID, a client might also be logged into a user account that has a userID. Whereas a client ID is a temporary, automatically generated identifier for a single connection, a user ID is the name of a permanent server-side user account, and is available only after a client logs in. See the UserAccount class and the Client class's getAccount() method.
Indicates the state of the client's current server connection. The value is one of the constants of the ConnectionState class.
Returns a Boolean indicating whether the client has administrator privileges. The administrator security role is available to clients that connect and authenticate over Union Server's administration port only.
true if the client has administrator privileges, false otherwise.
Returns true if this client is the current client. See Orbiter.self method.
Asks the server to keep this client's state permanently synchronized. As a result, the current client is notified any time any of following:
Notifications from the server trigger the following events:
The result of an observe() call is returned via a ClientEvent.OBSERVE_RESULT event. If the call succeeds, the ClientEvent.OBSERVE event is triggered. After the client has been synchronized for the first time, the ClientEvent.SYNCRHONIZE event is triggered.
Sends a message, with arguments, to another client. To receive the message, the recipient
client defines a method (or multiple methods) to be executed when the message arrives.
Each method wishing to be executed registers for the message separately using
MessageManager's addMessageListener() method.
To send a message to an arbitrary list of individual clients instead of to a single
client, use ClientManager.sendMessage().
The name of the message to send to the specified client.
An optional comma-separated list of string arguments for the message.
Sets a client attribute for this client. The attribute and its value are stored on, and
managed by, the server. A client attribute contains information about the client, much
like a variable. However, unlike a basic variable, a client attribute and its value can
be shared amongst other connected clients. Logged-in clients can also use user account
attributes to save information to a database or other data source for later retrieval
(see the UserAccount class's setAttribute() method for details).
Client attributes are used to track the characteristics of a client, such as a name, an
age, a hair colour, or a score. Other connected clients could then access the age "39" on
that client by retrieving its "age" attribute via Client.getAttribute(). In addition,
if the client were to change its age from "39" to "40", other interested clients would be
notified of the change. By responding to the change notification, other clients could,
say, keep a user list for a chat room updated with the current user ages.
To be notified of changes to a specific client's attributes, applications can register
with that client for the AttributeEvent.UPDATE event.
Every client attribute must be scoped to either a specific room or to all rooms. A client attribute that is scoped to all rooms is known as a "global client attribute". An attribute's scope determines which clients are updated when the attribute changes.
To delete a client attribute permanently, use Client's deleteAttribute() method. When a
client attribute is deleted, rooms the client is in trigger the
RoomEvent.DELETE_CLIENT_ATTRIBUTE event, and the Client object for the client triggers
the AttributeEvent.DELETE event.
Client attributes are not deleted by the server until the client disconnects.
Applications are expected to delete unwanted attributes explicitly via
deleteAttribute(). Applications that create numerous client attributes for long-lasting
connections should take care to prevent server-side memory accumulation by deleting each
attribute after it is no longer needed.
Note that by default the pipe character ("|") is used internally to separate attributes
during transmission to and from the server. Hence, attribute names and values must not
contain the character "|". For more information, see Tokens.RS.
The attribute name. Must not contain the pipe character ("|").
The attribute value. Must not contain the pipe character ("|").
A fully qualified roomID indicating the attribute's scope. The client need not be in the room to use it as the attribute's scope. However, when a client sets an attribute scoped to a room it is not currently in, other clients in that room are not notified of the attribute update. To create a global attribute (i.e., an attribute scoped to all rooms), set attrScope to undefined (the default). To retrieve a fully qualified room identifier for a Room object, (for use as an attribute scope) use Room's getRoomID() method.
Flag indicating that interested clients should be notified when the attribute changes (true) or that no clients should be notified when the attribute changes (false). Attribute updates are handled via RoomEvent.UPDATE_CLIENT_ATTRIBUTE and AttributeEvent.UPDATE isteners. Defaults to true (shared).
If true, the server will evaluate the attrValue as a mathematical expression before assigning the attribute its new value. Within the expression, the token "%v" means "substitute the attribute's current value". When evaluate is true, attrValue can contain the following characters only: the numbers 0-9, ., *, /, +, -, %, v.
Tells this client that it is the current client. This method is invoked once per connection by the ClientManager when the client manager is provided with a reference to the current client via setSelf().
The Client class represents a unique client that is connected to Union Server. Each client can send and receive messages and store shared data in client attributes.
To learn how Client objects represent client connections in Orbiter's API, let's consider a simple chat application, running on two separate computers, "A" and "B". When chat starts on computer A, it connects to Union Server.
When the connection from computer A's chat to Union Server is established, Union Server creates a server-side client object for the socket opened by computer A's chat, and assigns that client a unique clientID (such as "37"). Likewise, when the connection from computer B's chat to Union Server is established, Union Server creates a second client object and assigns it a unique clientID (such as "38"). At this stage, the two clients are connected to the server, but have no knowledge of each other.
To gain knowledge of each other, the two clients--let's call them clientA (for computer A's chat) and clientB (for computer B's chat)--join a room. Here's the "join-room" code that runs in each chat.
Upon joining the room "examples.chat", each client is automatically sent a list of the room's "occupants" (the clients in the room). Let's suppose computer A's chatjoins the room first, and is sent a list of room occupants for the room "examples.chat". Because clientA was the first client in the room, the list contains clientA only. (If there had already been other occupants in the room, they would also have been included in the list.) After clientA receives the room's occupant list, it triggers a RoomEvent.JOIN event. Once that event has fired, computer A's chat can access the clients in the room using Room.getOccupants method.
Now suppose clientB joins the "examples.chat" room. Because clientA is already in the room, it receives notification that clientB joined the room, and the Room object in computer A's chat.swf triggers the RoomEvent.ADD_OCCUPANT event. That event gives clientA access to the Client object for clientB via the RoomEvent.getClient method.
Once clientA has a reference to clientB's Client object, clientA can access clientB's data by reading its attributes, and clientA can communicate with clientB by sending it messages. For example, in the following code, chat sends a private message to clientB (and any other client that subsequently joins the room).
In addition to joining rooms, clients can gain knowledge of each other via the ClientManager.watchForClients and observeClient() methods. The watchForClients() method gives the current client knowledge of every client on the server. The observeClient() method gives the current client knowledge of one specific client. At any time, the Client object for any known client can be retrieved via ClientManager.getClient method.
In addition to accessing other clients (referred to as "foreign clients") each client can access the Client object representing its own connection via self() method. The Client object representing a client's own connection is known as the current client.
Clients store data in client attributes, which act as shareable multiuser variables. To retrieve a client's attribute values, use the Client.getAttribute method.
To set a client's attributes use setAttribute(). Note, however, that by default, a client can set its own attributes only, and cannot set the attributes of other connected clients.
It is not necessary to poll for changes in client attributes. When a client attribute is shared, changes to its value automatically trigger the RoomEvent.UPDATE_CLIENT_ATTRIBUTE event and the AttributeEvent.UPDATE event.
In order to reduce traffic between the server and clients, by default, not all clients on the server are accessible as Client instances. The current client has access to other clients in it's "sphere of knowledge" only, which includes synchronized rooms, "observed" clients (see ClientManager.observeClient method), and "watched" clients (see ClientManager.watchForClients method).
Because client 1 is in both the "chat1" room and the "chat2" room, its list of Client objects includes the clients with ids 1, 2, 3, 4, and 5. But client 1's list of Client objects does not include the clients with ids 6, 7, and 8 because client 1 is not in the "chat3" room.
Applications can apply custom behaviour to connected clients by assigning a custom client class via the following methods: Client.setClientClass, [[RoomManager.setDefaultClientClass]], and [[ClientManger.setDefaultClientClass]].
Clients can save persistent data for later retrieval by creating and logging into a user account. User accounts are built-in to Union, and come ready to use with every Union Server installation. To login to an account, use the AccountManager.login method. To access a logged-in client's user account, use the Client.getAccount method. For complete information on user accounts, see the UserAccount class.
In cases where an application wishes to retrieve a one-time snapshot of information about an arbitrary client on the server, and does not need that information to be kept up-to-date automatically, the application can use the ClientSnapshot class.