RemoteClient Class

Constructor

Arguments

none

Methods

Description

Represents the data associated with a client on the server.

Each remote client instance stores:

• "Client attributes" (such as a user name or a buddy list. See UClient.setClientAttribute().)
• A list of rooms containing the remote client.

Each Unity application's UClient instance automatically updates the list of RemoteClients for the application. Every client in every room the UClient is in is represented by a RemoteClient instance. RemoteClients are accessed through the RemoteClientManager, which itself is accessed through UClient.getRemoteClientManager(). A client must be in a room in order to "see" the other clients in that room as RemoteClients.

Though it may seem unusual, an application that connects to Unity retrieves its own client attributes through a RemoteClient instance. This allows developers to use a single API for checking client attributes. From the perspective of client attribute management, the current client is treated exactly like any other client connected to the server. For example, suppose a chat client connects to Unity, and happens to be the first client that connects. Unity tells the chat client that its client ID is "1". The chat client then automatically creates a RemoteClient instance for itself, with ID 1. The chat client can access its own RemoteClient instance as:

getRemoteClientManager.getClient(1);

And can access its own "client attributes" using:

getRemoteClientManager.getClient(1).getAttribute(roomID, attributeName);

(Of course, normally, the client ID is not hardcoded as "1", but is retrieved via UClient.getClientID()).

Now suppose that the chat client sets a client attribute, "username" to "Dave", and then joins a room, "Lobby". For each client in the "Lobby" room, a URoomListener.onAddClient() event fires. An observer of the "Lobby" URoom can display each client's username in a listbox by checking the global "username" attribute of each RemoteClient, as follows:

// EXCERPT FROM THE BODY OF THE onAddClient() METHOD

// * 'client' is the application's UClient instance.
// * 'e' is the URoomEvent instance passed to onAddClient().
// * 'users_lb' is the listbox in which to display user names.

var label = client.getRemoteClientManager().getClient(e.getClientID()).getAttribute(null, "username");
users_lb.addItem(label, e.getClientID());

Notice that the above code works even when the client ID is 1! The chat client retrieves its own "username" attribute exactly as it retrieves every other client's "username" attribute.

It is not necessary to poll for changes in client attributes. When a client attribute changes, a URoomListener.onUpdateClientAttribute() event is triggered. This allows an object observing a URoom instance to respond to changes in the attributes of the clients in the room (e.g., a name change from "Dave" to "Bill" or a score update in a game).

RemoteClient.getAttributeList() Method

Synopsis

Arguments

Description

Returns an object containing the names and values of all attributes defined on the RemoteClient instance. The object's property names are the fully qualified room IDs to which the attributes are scoped (for example, "someNamespace.someRoom", or "null" for global attributes). The properties must be accessed with the [] operator, as in: attributesObj["someNamespace.someRoom"]. Each room ID property is, itself, a reference to a nested object containing properties that represent the actual attribute names and values. For example, suppose a RemoteClient stores two attributes, as follows:

• a global attribute "username" with a value of "derek"
• an attribute "score" scoped to room "games.pong", with a value of 8

The attributes object returned by getAttributeList() for that client would be structured as follows:

attributesObj["null"]["username"] = derek;
attributesObj["games.pong"]["score"] = 8;

Example

The following code uses a for-in loop to display all the attributes for a specific scope in the Output panel.

// The id for the client. We'll use 3 for this example.
var clientID = 3;
// The scope for the attributes. We'll use the global 
// scope ("null") for this example.
var scope = "null";
// Retrieve the attributes object.
var attributesObj = someUClient.getRemoteClientManager().getRemoteClient(clientID).getAttributesList();

// Enumerate all attributes in the specified scope.
for (var attrname in attributesObj[scope]) {
  trace("Attribute name: " + attrname 
        + " has the value: " + attributesObj[scope][attrname]);
}

The following code uses a nested for-in loop to display all the attributes in all scopes in the Output panel:

var attributesObj = someUClient.getRemoteClientManager().getClient(clientID).getAttributeList();
for (var roomprop in attributesObj) {
  for (var nameprop in attributesObj[roomprop]) {
    trace("Attribute in scope: " + roomprop 
          + " with the name: " + nameprop 
          + " has the value: " + attributesObj[roomprop][nameprop]);
  }
}

Documentation Version

1.0.7