| Unity uClientCore > UClient |
UClient(target, server, port, configURL, disableLog)
null to indicate the current domain (i.e., the domain from which the movie was downloaded).<?xml version="1.0"?>
<config>
<server>yourserver.com</server>
<port>thePort</port>
<logLevel>theLogLevel</logLevel>
<policyPort>thePolicyPort</policyPort>
</config><?xml version="1.0"?>
<config>
<server>moock.org</server>
<port>9100</port>
<logLevel>DEBUG</logLevel>
<policyPort></policyPort>
</config>true) or enable logging (false). Defaults to false (enable logging) if not specified. For information about the in-movie log, see the UClient.logPanel property.| logPanel | A private property that stores a reference to an in-movie log, which is a simple window that displays logging information. The logPanel responds to the following methods: setSize(w, h), setPosition(x, y), minimize(), maximize(), hide(), show(). For example, the following code places, sizes, then minimizes the in-movie log. To completely disable logging for an application, set the disableLog parameter of the UClient constructor to true.
logPanel.setPosition(17, 374);
|
| changePersistentClient(name, password, newPassword) | Asks the Unity server to change the password of the persistent client with the specified name and password. Results are returned via UClient.onChangePersistentClient(). See createPersistentClient() and loginClient(). |
| connect() | Connects to Unity at the UClient's current host/port. Note that when an external config.xml file is used when constructing UClient, UClient automatically connects to Unity when it is constructed. When UClient is constructed without a config file, connect() must be called manually after construction. See method detail (below) for information on catching connection success and failure events. |
| createPersistentClient(name, password) | Asks the Unity server to create a new persistent client with the specified name and password. Results are returned via UClient.onCreatePersistentClient(). Applications use createPersistentClient() to allow client attributes to be saved across sessions and to implement a client login system. Once a persistent client has been created, a client can login under the specified name using loginClient(). After logging in, all persistent client attributes will be stored under the name provided to loginClient() at login time. See setClientAttribute() and loginClient(). |
| disconnect() | Disconnects from Unity. Triggers a SocketListener.onClientKillConnect() event. |
| getClientID() | Returns the client's ID, or null if the client ID has not yet been received. The client ID is available from any uClientCore event except SocketListener.onConnectSuccess() and SocketListener.onConnectFailure(). |
| getNumClientsOnServer() | Asks Unity how many clients are on the server. Unity's response automatically triggers UClient.onNumClientsOnServer(), which can be overridden to respond to the client count. |
| getRemoteClientManager() | Returns this application's RemoteClientManager. |
| getRoomManager() | Returns this application's RoomManager. |
| getSocketManager() | Returns this application's SocketManager. |
| getTargetMC() | Returns the MovieClip instance on which all GUI for this application should be created. |
| getNewTargetDepth() | Returns an unoccupied depth above all other depths in the clip returned by UClient.getTargetMC(). Every object added to that clip should use a depth returned by getNewTargetDepth(). |
| invokeOnAll(methodName, includeSelf, arg1, arg2,...argn) | Invokes an arbitrary method on all clients on the server. |
| invokeOnClient(methodName, clientID, arg1, arg2,...argn) | Invokes an arbitrary method on a single specified client. |
| invokeOnNamespace(methodName, fullNsID, includeSelf, arg1, arg2,...argn) | Invokes an arbitrary method on clients in rooms belonging to specified namespace. |
| invokeOnRoom(methodName, fullRoomID, includeSelf, arg1, arg2,...argn) | Invokes an arbitrary method on clients in a specified room. |
| isConnected() | Returns true if the client is currently connected to the server; false otherwise. |
| joinRoom(fullRoomID, password) | Sends a message to the server asking to join the specified room. UClient.joinRoom() is identical to URoom.join() except that it can be used to join a room that exists on the server but is not yet reflected by a client-side URoom instance. |
| loginClient(name, password) | Asks the Unity server to authenticate the named client using the specified password. Results are returned via UClient.onLoginClient(). The client name must have been created earlier via createPersistentClient(). Once a client is logged in, it can retrieve and store persistent attributes (attributes that are saved after the client disconnects). The loginClient() method (along with createPersistentClient() and removePersistentClient()) are used to implement a basic login system for an application, where clients can store personal preferences that are retained between sessions. Persistent client attributes are saved when the client disconnects, and are retained even after Unity is shut down or restarted. For more information on client attributes, see setClientAttribute().To log out a client, disconnect the socket using UClient.disconnect(). |
| removePersistentClient(name, password) | Asks the Unity server to delete an existing persistent client with the specified name and password. Results are returned via UClient.onRemovePersistentClient(). See createPersistentClient() and loginClient(). |
| sendUPC(roomID, methodName, arg1, arg2,...argn) | Creates and transmits a UPC to Unity. |
| sendXML(xmlObj) | Transmits an arbitrary XML object to Unity. Used only by custom applications that have server-side rooms that require custom XML-formatted data. |
| setClientAttribute (attrName, attrValue, attrScope, isShared, isPersistent, appendVal) | Sets a server-side attribute for this client, with a scope of attrScope (use scope null to create/set a global attribute, accessible from all rooms). The attrScope must be a fully qualified room identifier, specifying the room in which the attribute is accessible (i.e., the room that will broadcast a URoomListener.onUpdateClientAttribute() event when the attribute changes). To retrieve a fully qualified room identifier for a URoom object, use URoom.getFullRoomID(). If the URoom instance specified by attrScope does not exist, the attribute will not be sent.
When When To delete a client attribute permanently, use "null" for Note that Unity uses the pipe character ("|") internally to separate attributes during transimission to and from the server. Hence, attribute names and values must not contain the character "|". |
| setLogLevel(level) | Sets the filter level for the log. level must be one of: FATAL, ERROR, WARN, INFO, DEBUG. For example, setLogLevel("INFO") suppresses the display of DEBUG severity log messages. |
| setServer(host, port, policyPort) | Assigns the host and port on which Unity is running, and optionally specifies the port (policyPort) on which the Flash Player can retrieve a policy file describing the permissions on the server. In Flash Player 7.0.19.0 and later, a policy file can be loaded to allow connections to ports under 1024 and to allow connections to the server from other domains. Prior to 7.0.19.0, connections to ports under 1024 were not allowed, and cross-domain connections were achieved via either a shim movie (Flash Player 6) or a crossdomain.xml file served over HTTP. For more information on using policy files, see: Configuring Unity to Serve Policy Files and Macromedia's Release Notes for Flash Player 7.0.19.0. Policy port support was added to Unity in version 2.0.1. |
The following methods are invoked automatically on UClient subclass instances when the corresponding event occurs.
| onChangePersistentClient(status) | A callback invoked automatically when an attempt to change a persistent client's password completes. Possible values for status are: NAME_NOT_FOUND, SUCCESS, AUTHENTICATION_FAILED and FAILURE. See changePersistentClient(). |
| onClientReady() | A callback invoked automatically when a connection to Unity has been established and the client is fully initialized. Every UClient subclass should implement onClientReady(), supplying code that starts the application in motion. |
| onCreatePersistentClient(status) | A callback invoked automatically when an attempt to create a persistent client completes. Possible values for status are: NAME_EXISTS, SUCCESS, and FAILURE. See createPersistentClient(). |
| onLoginClient(status) | A callback invoked automatically when an attempt to create a persistent client completes. Possible values for status are: SUCCESS, FAILURE, NAME_NOT_FOUND, ALREADY_LOGGED_IN, and AUTHENTICATION_FAILED. If the login was successful, the client attributes will be available from within the onLoginClient() method, and are accessible via RemoteClient.getAttribute(). See loginClient(). |
| onNumClientsOnServer(numClients) | A callback invoked automatically when a server-wide client count is received (in response to an earlier getNumClientsOnServer() call). A UClient subclass can implement onNumClientsOnServer() to define custom behaviour when the client count arrives. |
| onRemovePersistentClient(status) | A callback invoked automatically when an attempt to remove a persistent client completes. Possible values for status are: NAME_NOT_FOUND, SUCCESS, and FAILURE. See removePersistentClient(). |
| onUnityError(msg) | A callback invoked automatically when the Unity server broadcasts a generic error message. Possible values for msg are: BANNED and SERVER_FULL. |
| onXML() | A callback invoked automatically when a non-UPC formatted message is received from Unity. A UClient subclass can implement onXML() to define custom behaviour when raw XML arrives. See SocketListener.onXML(). |
The UClient class represents a basic Unity client, and provides a suite of services for connection to and communication with Unity. Every Unity application starts with a UClient subclass that provides the application's foundation. UClient provides basic default implementions for the methods in the SocketListener interface. These methods should be overridden by a UClient subclass to define the basic responses for connection to and disconnection from Unity. (In a typical client-side only application, the UClient subclass's implementation of onClientReady() will create the namespaces and rooms in the application, but separate NamespaceListeners will place the client in the room(s) as they appear.)
UClient's central tasks are:
A "Unity Procedure Call" (UPC) describes a remote method invocation request, in one of the following two directions:
When a UPC is sent to Unity, it specifies a method that the Unity server, or a particular room, should invoke. When a UPC is received from Unity, it specifies a method that an instance of UClient (or one of its subclasses) should invoke. These two directions of UPC transmission require slightly different UPC syntax, described next.
A UPC sent by UClient has the following XML format:
<UPC>
<ROOMID>roomID</ROOMID>
<METH>methodName</METH>
<ARGS>
<ARG>value1</ARG>
<ARG>value2</ARG>
<ARG>...</ARG>
<ARG>valuen</ARG>
</ARGS>
</UPC>
Where roomID is the server-side identifier of the Unity room that should handle the UPC. If roomID is missing, Unity discards the UPC. If roomID is null, Unity delivers the UPC to default room for the server.
A UPC received by UClient has the following XML format:
<UPC>
<METH>methodName</METH>
<ARGS>
<ARG>value1</ARG>
<ARG>value2</ARG>
<ARG>...</ARG>
<ARG>valuen</ARG>
</ARGS>
</UPC>
Notice that UPCs received by UClient do not have a <ROOMID> tag. When UClient receives a UPC, it simply invokes the specified methodName on itself. It is up to that method to direct the message to a subordinate object, if required.
Generally speaking, the developer need not be concerned with the internal format of raw UPCs. Most UPC traffic is automatically handled by UClient and, when appropriate, delivered to the appropriate recipient. For example, a client joins a room by invoking URoom.join(), not by sending the actual "joinRoom" UPC. Similarly, when a client has joined a room, Unity sends a UPC ("upcOnJoinRoom") to UClient, but the developer need not respond to that UPC directly. Instead, she simply implements URoomListener.onJoin().
Furthermore, UClient includes a series of built-in tools for invoking remote methods on other connected clients:
Typically, developers will require the first two of the above methods only, using invokeOnRoom() to call methods on other clients in a room and invokeOnClient() to call methods on a specific client. However, when multiple rooms are running on the server, the remaining two methods become useful. The invokeOnAll() method provides an easy means of executing a method on every other connected client in every room. The invokeOnNamespace() method lets a client execute a method on all clients in a particular namespace (e.g., all "sports" rooms, including "hockey", "baseball", and "snowboarding").
Complex applications that involve custom Unity rooms may require use their own UPCs. An arbitrary custom UPC can be sent via UClient.sendUPC(). Arbitrary XML can also be sent to a server-side room via UClient.sendXML().
theClient.connect()
Connects the client to Unity at the current server and port. Note that UClient automatically connects to Unity when it is constructed with an external config.xml file. Hence, UClient.connect() is used only to re-establish a lost connection or to connect when an external config.xml file is not used. Use UClient.setServer() to change the current server and port.
When a connection succeeds and the UClient object has been initialized, UClient.onClientReady() executes. Each UClient subclass should implement onClientReady() and use it to start the application in motion (often by creating namespaces and rooms).
Lower level connection events can be handled by implementing the methods in the SocketListener interface (onConnectSuccess(), onConnectFailure(), onServerKillConnect(), and onClientKillConnect()). You do not need to register to receive these events from the UClient's SocketManager; each UClient instance automatically registers itself to receive SocketListener events.
If a connection attempt is rejected by the server because the server is full or the client is banned, onUnityError() will fire, providing information about the rejection.
theClient.invokeOnAll(methodName, [includeSelf, [arg1, arg2,...argn]])
methodName on the client that issued the invokeOnAll(). Defaults to false.methodName.The invokeOnAll() method invokes the specified method, methodName, on all clients on the server. However, when includeSelf is false, the methodName is not invoked on the client that issued the invokeOnAll() request. In order for invokeOnAll() to have an effect, all clients must implement methodName in a UClient subclass.
<UPC>
<ROOMID>unity</ROOMID>
<METH>invokeOnAll</METH>
<ARGS>
<ARG>methodName</ARG>
<ARG>includeSelf</ARG>
<ARG>arg1</ARG>
<ARG>arg2</ARG>
<ARG>...</ARG>
<ARG>argn</ARG>
</ARGS>
</UPC>
In response to which, Unity sends the following response UPC to all clients on the server:
<UPC>
<METH>methodName</METH>
<ARGS>
<ARG>fromClientID</ARG>
<ARG>arg1</ARG>
<ARG>arg2</ARG>
<ARG>...</ARG>
<ARG>argn</ARG>
</ARGS>
</UPC>
Hence, in order to catch an invokeOnAll() response UPC, each target client must implement a custom UClient subclass method of the form:
methodName(fromClientID, arg1, arg2,...argn)where
methodName is the methodName originally passed to invokeOnAll().
// Invokes broadcastText("Hello world!") on all clients on the server,
// including the sender.
chatClient.invokeOnAll("broadcastText", true, "Hello world!");
invokeOnClient(methodName, clientID, [arg1, arg2,...argn])
methodName will be invoked.methodName.The invokeOnClient() method invokes the specified methodName on the specified clientID.
The UPC generated by invokeOnClient() takes the form:
<UPC>
<ROOMID>unity</ROOMID>
<METH>invokeOnClient</METH>
<ARGS>
<ARG>methodName</ARG>
<ARG>clientID</ARG>
<ARG>arg1</ARG>
<ARG>arg2</ARG>
<ARG>...</ARG>
<ARG>argn</ARG>
</ARGS>
</UPC>
Unity responds to an invokeOnClient() UPC with the following response UPC, sent to clientID:
<UPC>
<METH>methodName</METH>
<ARGS>
<ARG>fromClientID</ARG>
<ARG>arg1</ARG>
<ARG>arg2</ARG>
<ARG>...</ARG>
<ARG>argn</ARG>
</ARGS>
</UPC>
Hence, in order to catch an invokeOnClient() response UPC, the target client must implement a custom UClient subclass method of the form:
methodName(fromClientID, arg1, arg2,...argn)
where methodName is the methodName originally passed to invokeOnClient().
theClient.invokeOnNamespace(methodName, [fullNsID, [includeSelf, [arg1, arg2,...argn]]])
methodName will be invoked. If null or not specified, defaults to the namespace "udefault".methodName on the client that issued the invokeOnNamespace(). Defaults to false.methodName.The invokeOnNamespace() method invokes the specified method, methodName, on all clients in the rooms of the namespace specified by fullNsID. However, when includeSelf is false, the methodName is not invoked on the client that issued the invokeOnNamespace() request. In order for invokeOnNamespace() to have an effect, all clients in fullNsID must implement methodName in a UClient subclass. If a client is in multiple rooms in the target namespace (fullNsID), it receives only one remote method invocation.
The invokeOnNamepace() method is a convenience method intended to provide Unity client-side developers with a means of invoking arbitrary custom methods on the clients in a namespace, without requiring any server-side coding.
The UPC generated by invokeOnNamespace() takes the form:
<UPC>
<ROOMID>unity</ROOMID>
<METH>invokeOnNamespace</METH>
<ARGS>
<ARG>methodName</ARG>
<ARG>fullNsID</ARG>
<ARG>includeSelf</ARG>
<ARG>arg1</ARG>
<ARG>arg2</ARG>
<ARG>...</ARG>
<ARG>argn</ARG>
</ARGS>
</UPC>
In response to which, Unity sends the following response UPC to all clients in toNamespace:
<UPC>
<METH>methodName</METH>
<ARGS>
<ARG>fromClientID</ARG>
<ARG>arg1</ARG>
<ARG>arg2</ARG>
<ARG>...</ARG>
<ARG>argn</ARG>
</ARGS>
</UPC>
Hence, in order to catch an invokeOnNamespace() response UPC, each target client must implement a custom UClient subclass method of the form:
methodName(fromClientID, arg1, arg2,...argn)
where methodName is the methodName originally passed to invokeOnNamespace().
// Invokes adminBroadcast() on all clients in the 'music' namespace.
starchatClient.invokeOnNamespace("adminBroadcast",
"music",
false,
"Michael Jackson arrives in 10 minutes!");
theClient.invokeOnRoom(methodName, fullRoomID, [includeSelf, [arg1, arg2,...argn]])
methodName will be invoked. (e.g., "moockapps.uchat.sports.snowboarding".methodName on the client that issued the invokeOnRoom(). Defaults to false.methodName.The invokeOnRoom() method invokes the specified methodName on the clients in the specified room, fullRoomID. However, when includeSelf is false, the methodName is not invoked on the client that issued the invokeOnRoom() request. In order for invokeOnRoom() to have an effect all clients in fullRoomID must implement methodName in a UClient subclass.
The UPC generated by invokeOnRoom() takes the form:
<UPC>
<ROOMID>unity</ROOMID>
<METH>invokeOnRoom</METH>
<ARGS>
<ARG>methodName</ARG>
<ARG>fullRoomID</ARG>
<ARG>includeSelf</ARG>
<ARG>arg1</ARG>
<ARG>arg2</ARG>
<ARG>...</ARG>
<ARG>argn</ARG>
</ARGS>
</UPC>
In response to which, Unity sends the following response UPC to clients in fullRoomID:
<UPC>
<METH>methodName</METH>
<ARGS>
<ARG>fromClientID</ARG>
<ARG>arg1</ARG>
<ARG>arg2</ARG>
<ARG>...</ARG>
<ARG>argn</ARG>
</ARGS>
</UPC>
Hence, in order to catch an invokeOnRoom() response UPC, each target client must implement a custom UClient subclass method of the form:
methodName(fromClientID, arg1, arg2,...argn)
where methodName is the methodName originally passed to invokeOnRoom().
// Invokes move("85", "x", "topright") on all clients in the games.tictactoe
// room, including the sender.
gameClient.invokeOnRoom("move", "games.tictactoe", true, "x", "topright");
// Invokes newPos("85", "120", "335") on all clients in the
// room "chat.avatarchat", excluding the sender.
avatarClient.invokeOnRoom("newPos", "chat.avatarchat", false, "120", "335");
// Invokes doClickNoise("85") on all clients in the room
// "udefault.audioExperiment", excluding the sender. Notice that value
// for includeSelf is not needed when the default value suffices.
avatarClient.invokeOnRoom("doClickNoise", "udefault.audioExperiment");
theClient.joinRoom(fullRoomID, [password])
Sends a message to the server asking to join the specified room. UClient.joinRoom() is identical to URoom.join() except that it can be used to join a room that exists on the server but is not yet reflected by a client-side URoom instance.
For example, suppose the room "moockapps.chat" is specified in the server's "uconfig.xml" file. The "moockapps.chat" room exists on the server before it exists on the client. The client cannot call URoom.join() because there is not yet a URoom instance representing the room "moockapps.chat". Hence, the client must use UClient.joinRoom() to join the room. When "moockapps.chat" is joined, a NameSpace instance, "moockapps", will be created and a URoom instance, "chat", will be added to that NameSpace. During the creation of the "moockapps" NameSpace and the "chat" URoom, the client application has the opportunity to register listeners to receive events for the namespace and the room (see RoomManagerListener.onAddNamespace() and NamespaceListener.onAddRoom()).
If the room is not found, RoomManager.onJoinNonExistentRoom() will be triggered. That method is implemented by UClient automatically, and can be overridden in a UClient subclass to provide an application-specific response to the failed room-join attempt.
If the room is found but cannot be joined for some reason (e.g., because it is full), the room will trigger URoomListener.onJoin() and the status of the join attempt will be passed to observers in a URoomEvent object.
The UPC generated by joinRoom() takes the form:
<UPC>
<ROOMID>unity</ROOMID>
<METH>joinRoom</METH>
<ARGS>
<ARG>roomID</ARG>
<ARG>namespace</ARG>
<ARG>password</ARG>
</ARGS>
</UPC>
In response to which, Unity sends the following response UPC to the client that asked to join the room:
<UPC>
<METH>upcOnJoinRoom</METH>
<ARGS>
<ARG>roomID</ARG>
<ARG>namespace</ARG>
<ARG>status</ARG>
<ARG>attrName1=attrVal1
[TAB_CHARACTER]
attrName2=attrVal2
[TAB_CHARACTER]
...
attrNamen=attrValn</ARG>
</ARGS>
</UPC>
where status is a message describing the results of the join attempt. Possible status values are:
status is anything other than ROOM_NOT_FOUND, the status codes shown above are made available via a URoomEvent passed to URoomListener.onJoin().
1.0.23