RoomManager Class

Constructor

RoomManager(client)

Arguments

client: The UClient instance that created this RoomManager.

Methods

addRoomManagerListener()	Registers an object to receive RoomManagerListener events from this namespace.
createNamespaceOnServer(fullNsID, observe)	Asks Unity to create a namespace on the server. Results of the attempt are sent to RoomManagerListener.onCreateNamespaceResults(). `fullNsID` is the fully qualified identifier of the new namespace (e.g., "moockapps.chat.sports"). If `observe` is `true`, any subnamespaces or rooms subsequently added to the new namespace on the server will trigger the creation of corresponding NameSpace and URoom instances on the client side, accompanied by either a RoomManagerListener.onAddNamespace() or a NamespaceListener.onAddRoom() event notification.
createRoomOnServer(roomID, namespaceID, dieOnEmpty, clientListNotification, maxClients, password, attributesObj)	Asks Unity to create a room on the server. Results of the attempt are sent to RoomManagerListener.onCreateRoomResults(). If room creation is successful and the namespace to which the room was added is being observed, NamespaceListener.onAddRoom() will also fire.
getAllNamespaces()	Returns all the NameSpace instances currently stored by this RoomManager, as a flat array.
getNamespace(fullNsID)	Returns a reference to the NameSpace of the specified name, if it exists. If no such NameSpace exists, returns `null`. To retrieve a reference to the default namespace use "udefault", "null", or "".
getNamespaceListFromServer()	Asks Unity to report a list of all namespaces on the server. The list of namespaces is returned as a flat array that can be retrieved via RoomManagerListener.onNamespaceList().
getRoom(fullRoomID)	Convenience method to retrieve a reference to a URoom based on a fully qualified room id. Shortcut version of RoomManager.getNamespace(someNsID).getRoom(someRoomID).
removeNamespaceFromServer(fullNsID)	Asks Unity to remove the specified namespace from the server. Results of the attempt are sent to NamespaceListener.onRemoveNamespaceResults().
removeRoomFromServer(fullRoomID)	Asks Unity to remove the specified room from the server. Results of the attempt are sent to NamespaceListener.onRemoveRoomResults(). If room removal is successful and the namespace from which the room was removed is being observed, NamespaceListener.onRemoveRoom() will also fire.
removeRoomManagerListener()	Stops an object from receiving RoomManagerListener events from this namespace.
observeNamespace(fullNsID)	Tells the server to notify the client when a room, subnamespace, or room in a subnamespace is added to the specified namespace. Results of the observe request are returned via RoomManagerListener.onObserveNamespaceResults(). Room and subnamespace notifications must be handled by RoomManagerListener.onAddNamespace(), RoomManagerListener.onRemoveNamespace(), NamespaceListener.onAddRoom(), and NamespaceListener.onRemoveRoom().
stopObservingNamespace(fullNsID)	Tells the server not to notify the client when a room or subnamespace is added to the specified namespace. Results of the observation cancellation are returned via RoomManagerListener.onStopObservingNamespaceResults().

Description

The RoomManager class creates, stores, and provides access to Unity namespaces (NameSpace instances) and rooms (URoom instances). Rooms can be created at runtime using RoomManager.createRoomOnServer(). Namespaces can be created at runtime using RoomManager.createNamespaceOnServer(). References to URoom objects can be retrieved via either NameSpace.getRoom() or RoomManager().getRoom(). References to NameSpace objects can be retrieved via RoomManager().getNamespace().

Every UClient instance automatically creates a RoomManager, and provides access to it via UClient.getRoomManager(). A UClient can create rooms only through its RoomManager instance.

RoomManager.createRoomOnServer() Method

Synopsis

theRoomManager.createRoomOnServer([roomID, [namespaceID, [dieOnEmpty, [clientListNotification, [maxClients, [password, [attributesObj]]]]]]])

Arguments

roomID

The fully qualified id of the new room, as a string. If not specified, the room id will be generated automatically by Unity and returned via RoomManagerListener.onCreateRoomResults(). If the namespace is being observed, the room id will also be returned via NameSpaceListener.onAddRoom().

namespaceID

The fully qualified id of the namespace in which to put the new room, as a string. If not specified, the "udefault" is assumed.

dieOnEmpty

Boolean. When true (default) or not specified, the new room should remove itself when it becomes empty (all its clients leave). When false, the room is permanent, and will be deleted from the server only in response to RoomManager.removeRoomFromServer(). If dieOnEmpty is true, and no client enters the room within 5 minutes, the room is automatically deleted.

clientListNotification

Boolean. When true (default) or not specified, Unity automatically notifies all clients in the new room of changes to the room's client list. The addition of each client to the room triggers URoomListener.onAddClient(). The removal of each client from the room triggers URoomListener.onRemoveClient(). When false, Unity does not send notification of client list changes.

maxClients

The maximum number of clients allowed in the room at the same time, or null if no maximum. Defaults to null.

password

The password required to join the room. If not specified, defaults to "null", meaning that the room can be joined without a password.

attributesObj

An XML object that describes the initial room attributes for the room in the following format:

<ATTRIBUTES>
  <ATTRIBUTE>
    <NAME>attrName</NAME>
    <VALUE>attrValue</VALUE>
    <ISSHARED>true|false</ISSHARED>
    <ISPERSISTENT>true|false</ISPERSISTENT>
  </ATTRIBUTE>
</ATTRIBUTES>

Description

The createRoomOnServer() method creates a new room on the Unity server in the specified namespace. If roomID is specified, the new room is given the supplied identifier; otherwise, Unity generates the room's identifier automatically. If no namespaceID is supplied, "udefault" is used.

On the server-side, the UPCRoom class is used for the room. In Unity 2, you cannot specify a custom Java room class to use in place of UPCRoom. To workaround this limitation, use this CustomRoomCreator class. Custom-java room creation from the client side is on the feature list for future versions of Unity.

Results of the room-creation attempt are sent to RoomManagerListener.onCreateRoomResults(). If room creation is successful and the namespace to which the room was added is being observed, NamespaceListener.onAddRoom() will also fire.

UPC

The UPC generated by createRoomOnServer() takes the form:

<UPC>
  <ROOMID>null</ROOMID>
  <METH>createRoom</METH>
  <ARGS>
    <ARG>roomID</ARG>
    <ARG>namespaceID</ARG>
    <ARG>dieOnEmpty</ARG>
    <ARG>clientListNotification</ARG>
    <ARG>maxClients</ARG>
    <ARG>password</ARG>
    <ARG>XattrName1=attrVal1
         [TAB_CHARACTER]
         XattrName2=attrVal2
         [TAB_CHARACTER]
         ...
         XattrNamen=attrValn</ARG>
  </ARGS>
</UPC>

where X is a number indicating the isShared and isPersistent flags for each attribute, as follows:

0    Not shared. Not persistent.
1    Shared. Not Persistent.
2    Not Shared. Persistent.
3    Shared. Persistent.

In response to which, Unity sends the following response UPC to the client that created the room:

<UPC>
  <METH>upcOnCreateRoom</METH>
  <ARGS>
    <ARG>status</ARG>
    <ARG>roomID</ARG>
    <ARG>namespace</ARG>
  </ARGS>
</UPC>

where status is a message describing whether the room was created successfully and roomID is the newly created room's ID. Possible status values are:

ROOM_CREATED
ROOM_EXISTS
ROOM_CREATION_FAILED
NAMESPACE_NOT_FOUND

Example

The following code adds a new room, "chat", to the default namespace, "udefault". The room is permanent (does not die when it's empty), and receives no notification for changes in its client list from Unity. The room's maximum occupancy is 50 clients. The room can be joined without a password, has no initial room attributes.

theUClient.getRoomManager().createRoomOnServer("chat", "udefault", false, false, 50, null, null);

RoomManager.getNamespaceListFromServer() Method

Synopsis

theRoomManager.getNamespaceListFromServer()

Arguments

None

Description

Asks Unity to return a list of namespaces currently on the server. The list is returned as a flat array, accessible via the RoomManagerListener.onNamespaceList() method.

UPC

The UPC generated by removeNamespaceFromServer() takes the form:

<UPC>
  <ROOMID>unity</ROOMID>
  <METH>getNamespaceList</METH>
</UPC>

In response to which, Unity sends the following response UPC to the client that requested the namespace list:

<UPC>
  <METH>upcOnNamespaceList</METH>
  <ARGS>
    <ARG>fullNamespaceID1</ARG>
    <ARG>fullNamespaceID2</ARG>
    ...
    <ARG>fullNamespaceIDn</ARG>
  </ARGS>
</UPC>

where fullNamespaceID1...fullNamespaceIDn is a list of the fully qualified identifiers for the namespaces on the server.

RoomManager.removeNamespaceFromServer() Method

Synopsis

theRoomManager.removeNamespaceFromServer(fullNamespaceID)

Arguments

fullNamespaceID: The namespace id of the room to remove.

Description

Asks Unity to remove the namespace specified by fullNamespaceID. Results of the attempt are returned to the client that invoked removeNamespaceOnServer() via RoomManagerListener.onRemoveNamespaceResults(). If namespace removal is successful RoomManager.onRemoveNamespace() will fire on all connected clients observing the namespace. But before the client-side NameSpace instance is deleted (and before onRemoveNamespace() fires), the NameSpace instance broadcasts onDie() to its listeners. This allows the listeners to clean up any resources associated with the namespace (such as removing a GUI).

The removeNamespaceFromServer() method is recursive: if the namespace contains rooms, they are removed; if the namespace contains other namespaces, they are also removed. For each room removal, the containing namespace broadcasts a NamespaceListener.onRemoveRoom() event to its listeners. For each namespace removal (including the specified fullNamespaceID), the RoomManager broadcasts a RoomManager.onRemoveNamespace() event to its listeners.

UPC

The UPC generated by removeNamespaceFromServer() takes the form:

<UPC>
  <ROOMID>unity</ROOMID>
  <METH>removeNamespace</METH>
  <ARGS>
    <ARG>fullNamespaceID</ARG>
  </ARGS>
</UPC>

In response to which, Unity sends the following response UPC to the client that asked to remove the room:

<UPC>
  <METH>upcOnRemoveNamespace</METH>
  <ARGS>
    <ARG>status</ARG>
    <ARG>namespace</ARG>
  </ARGS>
</UPC>

where status is a message describing the results of the removal attempt. Possible status values are:

NAMESPACE_REMOVED
NAMESPACE_NOT_FOUND
PERMISSION_DENIED

RoomManager.removeRoomFromServer() Method

Synopsis

theRoomManager.removeRoomFromServer(fullRoomID)

Arguments

fullRoomID: The room id of the room to remove.

Description

Asks Unity to remove the room specified by fullRoomID. Results of the attempt are returned to the client that invoked removeRoomFromServer() via RoomManagerListener.onRemoveRoomResults(). If room removal is successful NamespaceListener.onRemoveRoom() will fire on all connected clients observing the room's namespace. Clients in the room when it is removed will be forced to leave the room, generating a URoomListener.onLeave() event.

UPC

The UPC generated by removeRoomFromServer() takes the form:

<UPC>
  <ROOMID>unity</ROOMID>
  <METH>removeRoom</METH>
  <ARGS>
    <ARG>roomID</ARG>
    <ARG>namespaceID</ARG>
  </ARGS>
</UPC>

In response to which, Unity sends the following response UPC to the client that asked to remove the room:

<UPC>
  <METH>upcOnRemoveRoom</METH>
  <ARGS>
    <ARG>status</ARG>
    <ARG>roomID</ARG>
    <ARG>namespace</ARG>
  </ARGS>
</UPC>

where status is a message describing the results of the removal attempt. Possible status values are:

ROOM_REMOVED
ROOM_ERROR
ROOM_NOT_FOUND
PERMISSION_DENIED

Documentation Version

1.0.11