Union Procedure Call Protocol Specification

Specification Version
1.6.2

Release Date
January 31, 2010

The Union Procedure Call (UPC) protocol is the Union platform's central communications protocol. It describes the message format used in all client/server communication and specifies a list of native messages supported by the Union server.

Structurally, UPC is a simple XML format that includes a message id and a list of arguments. A UPC message can be sent from the client to the server or the server to the client. Either way, every UPC message has the following general form:

<u>
  <m>messageID</m>
  <l>
    <a>value1</a>
    <a>value2</a>
    <a>...</a>
    <a>valuen</a>
  </l>
</u>

In the preceding message, the messageID is the message's identifier, which is typically a short code such as "u1" or "u2". The arguments for the message are specified by value1, value2, ...valuen.

Note that typical Union application developers need not be concerned with the internal format of raw UPC messages because most UPC traffic is automatically handled by the server or client SDKs. For example, in the Reactor SDK for Flash-client development, a client joins a room by invoking the Room class's join() method, not by manually transmitting the XML for a "u4" UPC message. Similarly, the result of the join-room request is sent to the client in the form of a "u6" UPC message, but the client need not read that message directly; instead, the client simply handles the RoomEvent.JOIN event.

Reserved Characters

Fully qualified room IDs in UPC messages must not contain the following reserved characters.

* (asterisk)
| (pipe)

The asterisk character is reserved for use as a wildcard character when indicating "all rooms qualifed by a specified qualifier." For example, the expression "a.b.*" means "all rooms with the room qualifier 'a.b'". By contrast, the expression "a.b" means "room 'b', qualified by 'a'". The pipe character is reserved for use as a record separator.

Furthermore, in room qualifiers and fully qualified room ids, the dot character (.) is reserved for use as a room id separator.

In the following tables, the record separator character, "|", is represented by the token "[RS]".

Native UPC Messages

The following tables list all messages in the UPC protocol.

Table 1: Client-to-Server Messages

Official Message Name Internal Message ID Arguments Corresponding Reactor API Description
SEND_MESSAGE_TO_ROOMS u1
  • messageName
  • roomIDorQualifier1 [RS] roomIDorQualifier2 [RS] roomIDorQualifiern
  • includeSelf
  • filters ##[add link to UFP spec]
  • arg1
  • arg2
  • ...
  • argn
 RoomManager.sendMessage(), Room.sendMessage() Asks the server to send a u7 with the specified messageName to all clients in the room list that pass the provided filter tests. The includeSelf argument is a Boolean indicating whether the message should be echoed to the sending client (assuming the sender is in the room list and passes the filter tests). If any of the rooms in the list is a room qualifier, the message is sent to all rooms qualified by that qualifier. Qualifiers in the room list must be formed using the * character; for example, "examples.*" means "the examples qualifier" whereas "examples" means the room named "examples". The server sends separate u7 messages for every room in the room list. For example, if the room list is "chat1|chat2" and a client is in both "chat1" and "chat2", the client will receive u7 twice (once for each room).
SEND_MESSAGE_TO_CLIENTS u2
  • messageName
  • clientID1 [RS] clientID2 [RS] clientIDn
  • filters ##[add link to UFP spec]
  • arg1
  • arg2
  • ...
  • argn
 Client.sendMessage() Asks the server to send a u7 with the specified messageName to all clients in client list that pass the provided filter tests.
SEND_MESSAGE_TO_SERVER u57
  • messageName
  • includeSelf
  • filters ##[add link to UFP spec]
  • arg1
  • arg2
  • ...
  • argn
 Server.sendMessage() Asks the server to send a u7 with the specified messageName to all clients on the server that pass the provided filter tests. The includeSelf argument is a Boolean indicating whether the message should be echoed to the sending client.
SET_CLIENT_ATTR u3
  • clientID
  • attrName
  • escapedAttrValue
  • attrScope
  • attrOptions, an integer whose bits have the following meaning when set:
    • 0 - RESERVED
    • 1 - RESERVED
    • 2 - shared
    • 3 - persistent
    • 4 - unique
    • 5 - RESERVED BY SERVER
    • 6 - RESERVED BY SERVER
    • 7 - RESERVED BY SERVER
    • 8 - evaluate
 Client.setAttribute() Asks the server to set a client attribute for client specified by clientID. The result of the request is returned to the sender via a u73. If the attribute is shared, any clients needing to be notified of the attribute assignment will receive a u8. Note that attrScope must be a room, and cannot be a qualifier; however, future versions of the UPC protocol might support qualifier-scoped attributes. The meanings of the "attrOptions" bits are as follows:
  • 0 - RESERVED
  • 1 - RESERVED
  • 2 - shared: interested clients will receive notification that the attribute changed
  • 3 - persistent: the attribute will be stored persistently, and will be available across multiple client sessions
  • 4 - unique: the attribute's value must be unique among the clients that define the same attribute
  • 5 - RESERVED BY SERVER
  • 6 - RESERVED BY SERVER
  • 7 - RESERVED BY SERVER
  • 8 - evaluate: evaluate the supplied escapedAttrValue as a mathematical expression before assignment. Within escapedAttrValue, the token "%v" represents the attribute's current value. For example, "%v+1" means "increment by one". Supported mathematical operators are: *, /, +, -, %, ., (, and ). If the expression contains any character other than a number or one of the supported operators, the attribute assignment fails and the server responds with a u73 with status of EVALUATION_FAILED.
JOIN_ROOM u4
  • roomID
  • password
 Room.join() Asks the server to attempt to add the sender to the specified room. The result of attempting to join the room is returned to the sender via a u72. If the attempt is successful, the sender is also sent a u6, followed by updates for the room according to the sender's specified update levels (see u64). When a room is removed from the server, clients in that room receive a u44, but do not automatically receive notification that the room was removed. Clients wishing to be notified when a room is removed must register for notifications via WATCH_FOR_ROOMS.
SET_ROOM_ATTR u5
  • roomID
  • attrName
  • escapedAttrValue
  • attrOptions, an integer whose bits have the following meaning when set:
    • 0 - RESERVED
    • 1 - RESERVED
    • 2 - shared
    • 3 - persistent
    • 4 - UNUSED
    • 5 - RESERVED BY SERVER
    • 6 - RESERVED BY SERVER
    • 7 - RESERVED BY SERVER
    • 8 - evaluate
 Room.setAttribute() Asks the server to set a room attribute for the specified room. The result of the request is returned to the sender via a u74. If the attribute is shared, any clients needing to be notified of the attribute assignment will receive a u9. The meanings of the "attrOptions" bits are as follows:
  • 0 - RESERVED
  • 1 - RESERVED
  • 2 - shared: interested clients will receive notification that the attribute changed
  • 3 - persistent: the attribute will be stored persistently, and will be available across multiple server restarts
  • 4 - UNUSED
  • 5 - RESERVED BY SERVER
  • 6 - RESERVED BY SERVER
  • 7 - RESERVED BY SERVER
  • 8 - evaluate: evaluate the supplied escapedAttrValue as a mathematical expression before assignment. Within escapedAttrValue, the token "%v" represents the attribute's current value. For example, "%v+1" means "increment by one". Supported mathematical operators are: *, /, +, -, %, ., (, and ). If the expression contains any character other than a number or one of the supported operators, the attribute assignment fails and the server responds with a u74 with status of EVALUATION_FAILED.
LEAVE_ROOM u10
  • roomID
 Room.leave() Asks the server to remove the sender from the specified room. The result of attempting to leave the room is returned to the sender via a u76. If the attempt is successful, the sender is also sent a u44.
CREATE_ACCOUNT u11
  • userID
  • password
 ClientManager.createAccount() Asks the server to create a new client account, used to store information permanently in a persistent data source such as a database. Results of the create-account attempt are returned via a u47.
REMOVE_ACCOUNT u12
  • userID
  • password
 ClientManager.removeAccount() Asks the server to remove the client account for the specified userID. Results of the remove-account attempt are returned via a u48.
CHANGE_ACCOUNT_PASSWORD u13
  • userID
  • oldPassword
  • newPassword
 Client.changePassword() Asks the server to change the specified userID's account password. Results of the change password attempt are returned via a u46. If the attempt succeeds, and a client is currently logged in under the specified userID, the server also sends a u90 to that client.
LOGIN u14
  • userID
  • password
 Client.login() Asks the server to log in the sending client. Results of the login attempt are returned via a u49. If the attempt succeeds, the server also sends a u88 followed by a series of u8s containing the client's persistent attributes. If the userID specified for a u14 is already logged in under another client ID, the previous client is logged off and disconnected before the new login proceeds. Note that the sending client can ask to log in itself only; a u14 cannot be used to log in a foreign client.
GET_NUM_CLIENTS u18
  • roomIDorQualifier
 RoomManager.getNumClientsInRooms(), Room.synchronizeClientCount(), Server.getNumClientsOnServer() Asks the server to return the number of clients in the specified room or in all rooms with the specified room ID qualifier. For server-wide count, supply the empty string ("") for roomIDorQualifier. For a count of clients in the unnamed qualifier, supply an asterisk ("*") for roomIDorQualifier. For a count of clients in rooms with the qualifier "chat.sports", supply "chat.sports.*" for roomIDorQualifier. The result is returned to the sender via a u75. If the request is successful, the number of clients in the specified roomIDorQualifier is returned to the sender via a u34.
SYNC_TIME u19 None Server.syncTime() Asks the server to return the current time. The result is returned via a u50.
GET_ROOM_LIST u21
  • roomIdQualifier
 RoomManager.synchronizeRoomList() Asks the server to return a list of the rooms whose ids are qualified by roomIdQualifier. The result is returned via a u38. To request a list of all rooms on the server, set roomIdQualifier to the empty string (""). To request a list of rooms with the unnamed qualifier, set roomIdQualifier to "*".
CREATE_ROOM u24
  • roomID
  • roomSettingName1[RS]roomSettingValue1 [RS] roomSettingNamen[RS]roomSettingValuen
  • attrName1[RS]attrVal1[RS]attrOptions [RS] attrName2[RS]attrVal2[RS]attrOptions [RS]...attrNamen[RS]attrValn[RS]attrOptions
  • CLASS[RS]qualifiedClassName1 [RS] CLASS[RS]qualifiedClassNamen [RS] SCRIPT[RS]pathToScript1 [RS] SCRIPT[RS]pathToScriptn
 RoomManager.createRoom()

Asks the server to create the specified room.

If roomID is empty, then the server creates the room ID automatically. To determine the room's ID, the client must watch for a room addition message (u39).

Recognized setting names for the second argument are as follows:

  • _DIE_ON_EMPTY: true, false
  • _MAX_CLIENTS: int (-1 for no max)
  • _PASSWORD: String ("" for no password)
  • _CLIENT_TIMEOUT: int (-1 for no timeout)

The third argument lists the room's initial attributes.

The fourth argument lists room's room modules, which can be defined by a script or a class. Scripts and classes can be listed in any order. A path to a script indicates the location of a script relative to the server's central scripts directory.
REMOVE_ROOM u25
  • roomID
  • password
 RoomManager.removeRoom() Asks the server to remove the specified room. If the request is successful, the server sends a u40 to all clients in or observing the room. The client that sent the u25 message also receives a u33. Clients do not receive separate u37 (CLIENT_REMOVED) notifications for clients that are forced out of the room when it is removed.
WATCH_FOR_ROOMS u26
  • roomIdQualifier
 RoomManager.watchForRooms() Asks the server to inform the client when new rooms qualified by roomIdQualifier are added to or removed from the server. The server sends the result of the request via a u42. If the request was successful, the server also sends a u38. Subsequent room additions trigger u39; subsequent room removals trigger u40. It is legal to watch a qualifier that does not yet exist.

To watch for rooms with the unnamed qualifier, set roomIdQualifier to "*".

u26 is currently not recursive; for example, given qualifiers "a" and "a.b", a client that watches for rooms with qualifier "a" will not be notified when rooms qualified by "a.b" are added to the server. u26 is expected to support recursion in the future, at which time, clients that wish to watch for all rooms on the server should set roomIdQualifier to the empty string ("").
STOP_WATCHING_FOR_ROOMS u27
  • roomIdQualifier
 RoomManager.stopWatchingForRooms() Asks the server to stop sending room-addition-and-removal notifications for the specified roomIdQualifier. The server sends the result of the request via a u43.

To stop watching for rooms with the unnamed qualifier, set roomIdQualifier to "*".

u27 is currently not recursive; for example, given qualifiers "a" and "a.b", a client that stops watching for rooms with qualifier "a" will not also stop watching for rooms qualified by "a.b". u27 is expected to support recursion in the future, at which time, clients that wish to stop watching for all rooms on the server should set roomIdQualifier to the empty string ("").
SYNC_ROOM u55
  • roomID
  • password
 Room.synchronize(), RoomManager.synchronizeRoom() Asks the server to send a room snapshot for the specified room. In response, the server sends a u60 and, if the request succeeds, a u54.
OBSERVE_ROOM u58
  • roomID
  • password
 Room.observe(), RoomManager.observeRoom()

Used for spectating a room the client is not in. A u58 asks the server to register the sender as an observer of the specified room. The result of attempting to observe the room is returned to the sender via a u77. If the attempt is successful, the sender is also sent a u59, and will subsequently receive updates for the room in accordance with the client's specified occupant, room, and message update levels. If a client changes its update levels, subsequent updates are sent according to the new levels. For details on which updates are sent and how levels affect updates, see u64.

If a client is in a room, it can still register to observe that room. Likewise, a client can observe a room, and then join and leave it arbitrarily without affecting observation status. When a client is both an observer and an occupant of a room, it receives updates about the room even after leaving it. Clients that observe a room and then join it will not receive a u54 at join time.

When a room is removed from the server, clients in that room receive a u62, but do not automatically receive notification that the room was removed. Clients wishing to be notified when a room is removed must register for notifications via WATCH_FOR_ROOMS.
STOP_OBSERVING_ROOM u61
  • roomID
 Room.stopObserving(), RoomManager.stopObservingRoom() Asks the server to unregister the sender as an observer of the specified room. The result of the request is returned to the sender via a u78. If the attempt is successful, the sender is also sent a u62.
SET_ROOM_UPDATE_LEVELS u64
  • roomID
  • occupantUpdateLevel [RS] roomUpdateLevel [RS] messageUpdateLevel
 Room.setUpdateLevels(), Room.join(), Room.observe(), RoomManager.joinRoom(), RoomManager.observeRoom() Asks the server to change the client's update levels for the specified room. The server applies only those changes permitted for the client's security level. Assignments that fail due to insufficient client privileges trigger a server-side log update, but are not reported to the client.

Valid values for occupantUpdateLevel are:
  • 0: None
  • 1: Client count only
  • 2: All (send full client list, including all client attributes)
Valid values for roomUpdateLevel are:
  • 0: None
  • 1: All (send room attributes)
Valid values for messageUpdateLevel are:
  • 0: None
  • 1: All (send messages)
The specified update levels determine how much information is pushed to the client when it is either in or observing a room. Clients are sent information about rooms according to the following algorithm:
  1. Client joins room. If already observing room, goto 6. Else, goto 3.
  2. Client observes room. If already in room, goto 6. Else, goto 3.
  3. If occupantUpdateLevel is 2, send client a u54 (room snapshot) containing the client's specified level of occupant and room information. (If roomUpdateLevel is 1, room attributes are included; if roomUpdateLevel is 0, room attributes are omitted.)
  4. If occupantUpdateLevel is 1 and roomUpdateLevel is 1, send client a u54 (room snapshot) and a u34 (num clients).
  5. If occupantUpdateLevel is 1 and roomUpdateLevel is 0, send client a u34 (num clients).
  6. If client is still in or observing room, goto 7. Else goto 14.
  7. If client's occupantUpdateLevel is 1, and another client joins or leaves the room, send a u34 (num clients).
  8. If client's occupantUpdateLevel is 2, and another client joins the room, send a u36 (client added).
  9. If client's occupantUpdateLevel is 2, and another client leaves the room, send a u37 (client removed).
  10. If client's occupantUpdateLevel is 2, and another client changes an attribute, send a u8 (client attribute update).
  11. If client's roomUpdateLevel is 1, and a room attribute changes, send a u9 (room attribute update).
  12. If client's messageUpdateLevel is 1, and a message is sent to the room, send a u7 (receive message).
  13. Goto 6.
  14. End.
CLIENT_HELLO u65
  • clientType
  • userAgent
  • upcVersion
 ReactorEvent.PROTOCOL_INCOMPATIBLE. CLIENT_HELLO is the first step in the client-server connection process. It tells the server the client's type, the user agent (software name and version) being used to make the connection, and the UPC protocol version used by the client to communicate. The server responds with a u66, and then:
  • if the client and server are considered unacceptably incompatible, the server disconnects the client (see compatibility details below)
  • otherwise, the server sends a u29 followed by a u63

Example values for clientType are:

  • Reactor
  • Mariner

The userAgent is a human-readable string set arbitrarily by the client, and is used for logging purposes only. For example, "Flash Player WIN 9,0,124,0 StandAlone (debug, localTrusted)".

The upcVersion specifies the version of the UPC specification used by the client, in the format: majorNumber.minorNumber.revisionNumber. For example, 1.2.0. If the client's majorNumber, minorNumber, and revisionNumber all match the server's majorNumber, minorNumber, and revisionNumber, the server is considered compatible with the client. Otherwise:

  • If the server's majorNumber and the client's majorNumber do not match, or the server's minorNumber and the client's minorNumber do not match, the server sends a u66 with the "upcCompatible" argument set to false, and disconnects the client.
  • If the server's revisionNumber and the client's revisionNumber do not match, but the majorNumber and minorNumber both match, then the server sends a u66 with the "upcCompatible" argument set to false, but does not disconnect the client. The client application must, itself, decide whether to stay connected. The application might wish to stay connected if it does not use any features that differ between the client's protocol version and the server's protocol version. For example, imagine a hypothetical UPC-specification version, 4.5.5, that is succeeded by a minor revision 4.5.6. The 4.5.6 revision is identical to its predecessor except that it contains a new UPC message, "REMOVE_ALL_ROOMS", that was not present in 4.5.5. All 4.5.5-compatible client applications can safely communicate with all 4.5.6-compatible servers because all 4.5.5 messages are still supported in revision 4.5.6. However, a 4.5.6-compatible client application, can safely communicate with a 4.5.5-compatible server only if it does not use REMOVE_ALL_ROOMS, which is not supported by the 4.5.5-compatible server. A 4.5.6-compatible client application that uses REMOVE_ALL_ROOMS would, hence, be expected to disconnect itself from a 4.5.5-compatible server.
REMOVE_ROOM_ATTR u67
  • roomID
  • attrName
 Room.deleteAttribute() Asks the server to remove a room attribute from the specified room. The result is returned via a u80. If the request is successful, all clients requiring notification of the change are sent a u79.
REMOVE_CLIENT_ATTR u69
  • clientID
  • attrName
  • attrScope
 Client.deleteAttribute() Asks the server to remove a client attribute from the specified client. The result of the request is returned via a u82. If the request succeeds, all clients needing to be notified of the deletion are sent a u81. If clientID is not specified, the attribute is deleted from the sending client.
SEND_ROOMMODULE_MESSAGE u70
  • roomID
  • moduleMessageName
  • argName1|argValue1
  • argName2|argValue2
  • ...
  • argNamen|argValuen
 Room.sendModuleMessage() Sends the specified message to all of the modules of the specified room. The argument names (argName1, argName2,...argNamen) must not contain the pipe (|) character. Argument values can contain the pipe (|) character.
SEND_SERVERMODULE_MESSAGE u71
  • moduleID
  • moduleMessageName
  • argName1|argValue1
  • argName2|argValue2
  • ...
  • argNamen|argValuen
 Server.sendModuleMessage() Sends the specified message to the specified server module. The moduleID must be the ID of a deployed server module on the server. The argument names (argName1, argName2,...argNamen) must not contain the pipe (|) character. Argument values can contain the pipe (|) character.
TERMINATE_SESSION u83
  • sessionID
 Asks the server to terminate the session specified by sessionID.
LOGOFF u86
  • userID
  • password
 Client.logoff() Asks the server to logoff the client account specified by userID. Results of the logoff attempt are returned via a u87. If the attempt succeeds, the server logs off and then disconnects the client.
GET_CLIENT_LIST u91 ClientManager.synchronizeClientList() Asks the server to send a list of clientIDs for all clients currently connected to the server. The list will also include userIDs for all clients with user accounts that are currently logged in. The result is sent via a u101. See also u97 (GET_USER_LIST).
WATCH_FOR_CLIENTS u92 ClientManager.watchForClients() Asks the server to inform the client when new clients connect. The server sends the result of the request via a u107. If the request was successful, the server also sends a u101. Subsequent client connections trigger a u102; subsequent client disconnections trigger a u103.
STOP_WATCHING_FOR_CLIENTS u93 ClientManager.stopWatchingForClients() Asks the server to stop sending client connection-and-disconnnection notifications. The server sends the result of the request via a u108.
SYNC_CLIENT u94
  • clientID
 Client.synchronize(), ClientManager.synchronizeClient() Asks the server to send a client snapshot for the specified client. In response, the server sends a u115 and, if the request succeeds, a u104.
OBSERVE_CLIENT(clientID) u95
  • clientID
 Client.observe(), ClientManager.observeClient() Asks the server to register the sender as an observer of the specified client. In response, the server sends a u105 and, if the request succeeds, a u119 followed by a u104. Subsequently if the specified client's state changes, the observing client is notified in the following ways:
  • Observed client's attribute changes: observer receives a u8
  • Observed client's attribute is deleted: observer receives a u81
  • Observed client joins a room: observer receives a 113
  • Observed client leaves a room: observer receives a 114
  • Observed client observes a room: observer receives a 117
  • Observed client stops observing a room: observer receives a 118
  • Observed client logs in: observer receives a u88
  • Observed client logs off: observer receives a u89
  • Observed client disconnects: observer receives a u103
STOP_OBSERVING_CLIENT(clientID) u96
  • clientID
 Client.stopObserving(), ClientManager.stopObservingClient() Asks the server to unregister the sender as an observer of the specified client. In response, the server sends a u106. If the request succeeds, the server also sends a u120, and stops sending updates about the specified client.
GET_USER_LIST u97 ClientManager.synchronizeUserList() Asks the server to send a list of userIDs for all registered user accounts on the server. The list will also include clientIDs for all users that are currently logged in. The result is sent via a u101. See also u91 (GET_CLIENT_LIST).
WATCH_FOR_USERS u98 ClientManager.watchForUsers() Asks the server to inform the client when new user accounts are created. The server sends the result of the request via a u109. If the request was successful, the server also sends a u101. Subsequent user-account creations trigger a u111; subsequent user-account removals trigger a u112.
STOP_WATCHING_FOR_USERS u99 ClientManager.stopWatchingForUsers() Asks the server to stop sending user-account creation-and-removal notifications. The server sends the result of the request via a u110.
SYNC_USER u100
  • userID
 Client.synchronize(), ClientManager.synchronizeUser() Asks the server to send a client snapshot for the specified user, including all persistent data stored in the user's account. In response, the server sends a u116 and, if the request succeeds, a u104.

Table 2: Server-to-Client Messages

Official Message Name Internal Message ID Arguments Corresponding Reactor API Description Status Codes
JOINED_ROOM u6
  • roomID
 RoomEvent.JOIN Informs the client that it joined a room.
RECEIVE_MESSAGE u7
  • messageName
  • broadcastType
  • fromClientID
  • roomID
  • messageArg1
  • messageArg2
  • ...
  • messageArgn
 No direct corresponding method. But see MessageManager.addMessageListener(), Room.addMessageListener(). Causes the client to execute listeners registered for "messageName". u7 is sent in response to u1, u2, and u57. The broadcastType argument's three possible values--0, 1, or 2--indicate which clients received the message, as follows:
  • 0 ("TO SERVER": all clients on the entire server)
  • 1 ("TO ROOMS": all clients in the specified rooms)
  • 2 ("TO CLIENTS": a list of individually specified clients)
When u7 is a u1 response, broadcastType is 2, and u7's fourth argument is empty. When u7 is a u2 response, broadcastType is 1, and u7's fourth argument is the room receiving the message. When u7 is a u57 response, broadcastType is 0, and u7's fourth argument is empty.
CLIENT_ATTR_UPDATE u8
  • roomID
  • clientID
  • attrName
  • attrVal
 RoomEvent.UPDATE_CLIENT_ATTRIBUTE Reports a change to a client attribute.
ROOM_ATTR_UPDATE u9
  • roomID
  • clientID
  • attrName
  • attrVal
 RoomEvent.UPDATE_ROOM_ATTRIBUTE Reports a change to a room attribute. The clientID specifies the id of the client that changed the attribute. If the attribute was not changed by a client (as is the case when the server sets the attribute), clientID is empty.
CLIENT_METADATA u29
  • clientID
 None. This UPC is handled internally. Provides each connecting client with its initial setup information.
CREATE_ROOM_RESULT u32
  • roomID
  • status
 RoomManagerEvent.CREATE_ROOM_RESULT Reports the result of a room-creation attempt to the client.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • ROOM_EXISTS
REMOVE_ROOM_RESULT u33
  • roomID
  • status
 RoomManagerEvent.REMOVE_ROOM_RESULT Reports the result of a room-removal attempt to the client.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • ROOM_NOT_FOUND
  • AUTHORIZATION_REQUIRED
  • AUTHORIZATION_FAILED
NUM_CLIENTS_UPDATE u34
  • scope
  • numClientsTotal
  • numClientsUnique
 RoomEvent.CLIENT_COUNT, RoomManagerEvent.CLIENT_COUNT, ServerEvent.CLIENT_COUNT Reports the number of clients in the specified scope, where scope is one of:
  • a room id
  • a room id qualifier (where "*" means the unnamed qualifier, and "chat.sports.*" means all rooms with the qualifier "chat.sports")
  • "" (meaning the entire server)

The numClientsTotal and numClientsUnique arguments have the following meanings:

  • If scope is a room, numClientsTotal and numClientsUnique both indicate the number of clients in that room.
  • If scope is a room ID qualifier, numClientsUnique is the number of unique clients in all rooms qualified by that qualifier; numClientsTotal is the total number of occupants in all rooms qualified by that qualifier. For example, if one client joins two rooms, "example.roomA" and "example.roomB", then for scope "example.*", numClientsUnique would be 1 (because there is only one client) and numClientsTotal would be 2 (because the one client is an occupant of two different rooms).
  • If scope is empty, numClients is the number of clients on the entire server.
CLIENT_ADDED_TO_ROOM u36
  • roomID
  • clientID
  • userID
  • globalAttrName1 [RS] globalAttrValue1 [RS] ... globalAttrNamen [RS] globalAttrValuen
  • roomAttrName1 [RS] roomAttrValue1 [RS] ... roomAttrNamen [RS] roomAttrValuen
 RoomEvent.ADD_CLIENT Reports that the specified client has joined the specified room.
CLIENT_REMOVED_FROM_ROOM u37
  • roomID
  • clientID
 RoomEvent.REMOVE_CLIENT Reports that the specified client has left the specified room.
ROOM_LIST_UPDATE u38
  • scope
  • roomID1
  • roomID2
  • ...
  • roomIDn
 RoomManagerEvent.ROOM_ADDED, RoomManagerEvent.ROOM_REMOVED Provides a list of the rooms in the specified scope, where scope is a room qualifier ("*" for the unnamed qualifier) or the empty string (""). When scope is a room qualifier, roomID1...roomIDn is a list of simple room ids (e.g., "hockey" not "sports.hockey". When scope is the empty string, roomID1...roomIDn is a list of full room ids (e.g., "sports.hockey" not "hockey"). A u38 is sent to clients that watch a specified room's qualifier. See u26. Also sent in response to u21.
ROOM_ADDED u39
  • roomID
 RoomManagerEvent.ROOM_ADDED Reports that the specified room was added. Sent to clients watching the specified room's qualifier. See u26.
ROOM_REMOVED u40
  • roomID
 RoomManagerEvent.ROOM_REMOVED Reports that the specified room was removed. Sent to clients watching the specified room's qualifier. See u26. Also sent to clients in or observing a room when the room is removed (regardless of their update levels). Note that clients do not receive separate u37 (CLIENT_REMOVED) notifications for clients that are forced out of a room when it is removed.
WATCH_FOR_ROOMS_RESULT u42
  • roomIdQualifier
  • status
 RoomManagerEvent.WATCH_FOR_ROOMS_RESULT Reports the result of a u26 request.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • INVALID_QUALIFIER
  • ALREADY_WATCHING
STOP_WATCHING_FOR_ROOMS_RESULT u43
  • roomIdQualifier
  • status
 RoomManagerEvent.STOP_WATCHING_FOR_ROOMS_RESULT Reports the result of a u27 request.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • INVALID_QUALIFIER
  • NOT_WATCHING (If the client had no watch set for the specified qualifier.)
LEFT_ROOM u44
  • roomID
 RoomEvent.LEAVE Informs the client that it left the specified roomID, normally as a result of an earlier u10 request.
CHANGE_ACCOUNT_PASSWORD_RESULT u46
  • userID
  • status
 ClientEvent.CHANGE_PASSWORD_RESULT Reports the result of an attempt to change the password for the account specified by userID. See u13.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • ACCOUNT_NOT_FOUND
  • AUTHORIZATION_FAILED
CREATE_ACCOUNT_RESULT u47
  • userID
  • status
 ClientManagerEvent.CREATE_ACCOUNT_RESULT Reports the result of an attempt to create the client account specified by userID. See u11.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • ACCOUNT_EXISTS
REMOVE_ACCOUNT_RESULT u48
  • userID
  • status
 ClientManagerEvent.REMOVE_ACCOUNT_RESULT Reports the result of an attempt to remove (delete) the client account specified by userID. See u12.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • ACCOUNT_NOT_FOUND
  • AUTHORIZATION_FAILED
LOGIN_RESULT u49
  • userID
  • status
 ClientEvent.LOGIN_RESULT Reports the result of a login attempt made by the receiving client. See u14.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • ALREADY_LOGGED_IN
  • ACCOUNT_NOT_FOUND
  • AUTHORIZATION_FAILED
SERVER_TIME_UPDATE u50
  • timeOnServer
 ServerEvent.TIME_SYNC Reports the current time on the server, in UTC, using milliseconds-from-1970 format. See u19.
ROOM_SNAPSHOT u54
  • roomID
  • roomAttrName1[RS]roomAttrValue1 [RS] roomAttrName2[RS]roomAttrValue2 [RS] roomAttrNamen[RS]roomAttrValuen
  • client1clientID
  • client1userID
  • client1GlobalAttrName1 [RS] client1GlobalAttrValue1 [RS]
    ...
    client1GlobalAttrNamen [RS] client1GlobalAttrValuen
  • client1RoomAttrName1 [RS] client1RoomAttrValue1 [RS]
    ...
    client1RoomAttrNamen [RS] client1RoomAttrValuen
  • ...
  • clientnclientID
  • clientnuserID
  • clientnGlobalAttrName1 [RS] clientnGlobalAttrValue1 [RS]
    ...
    clientnGlobalAttrNamen [RS] clientnGlobalAttrValuen
  • clientnRoomAttrName1 [RS] clientnRoomAttrValue1 [RS]
    ...
    clientnRoomAttrNamen [RS] clientnRoomAttrValuen
 Room.synchronize(), RoomEvent.SYNCHRONIZE, Room.join(), Room.observe() Provides a manifest of a room's contents (attributes and clients). The content of the manifest is limited by the receiving client's update levels (set via u64) and security privileges. Clients can receive u54 messages in response to either joining a room (u4), observing a room (u58), or manually synchronizing a room (u55). The algorithm that determines when u54 messages are sent is listed under u64.
OBSERVED_ROOM u59
  • roomID
 RoomEvent.OBSERVE Informs the client that it started observing the specified room.
SYNC_ROOM_RESULT u60
  • roomID
  • status
 RoomEvent.SYNCHRONIZE_RESULT, RoomManagerEvent.SYNC_NONEXISTENT_ROOM Reports the result of a room sync request (u55) by the client. (Successful room sync requests also trigger u54).
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • ROOM_NOT_FOUND
  • AUTHORIZATION_REQUIRED
  • AUTHORIZATION_FAILED
  • ALREADY_SYNCHRONIZED (because the client is currently in or observing the room)
STOPPED_OBSERVING_ROOM u62
  • roomID
 RoomEvent.STOP_OBSERVING Informs the client that it has stopped observing the specified room, normally in response to an earlier "stop observing rooms" request (u61).
CLIENT_READY u63 UConnectionEvent.READY Informs the client that all setup tasks have completed and the client is ready for use.
SERVER_HELLO u66
  • serverVersion
  • sessionID
  • upcVersion
  • protocolCompatible
 ReactorEvent.PROTOCOL_INCOMPATIBLE SERVER_HELLO is the second step in the client-server connection process. It tells the client the server's version and protocol version, and provides the client with a server-side session ID used to identify the connection. If the server determines the client to be unacceptably protocol-incompatible, the server will automatically disconnect the client. For compatibility details, see u65.
JOIN_ROOM_RESULT u72
  • roomID
  • status
 RoomEvent.JOIN_RESULT, RoomManagerEvent.JOIN_NONEXISTENT_ROOM Reports the result of a join-room request (u4). If status is SUCCESS, the client is also sent a separate u6 message.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • ALREADY_IN_ROOM
  • ROOM_NOT_FOUND
  • ROOM_FULL
  • AUTHORIZATION_REQUIRED
  • AUTHORIZATION_FAILED
SET_CLIENT_ATTR_RESULT u73
  • roomID
  • clientID
  • attrName
  • status
 RoomEvent.SET_CLIENT_ATTRIBUTE_RESULT, ClientEvent.SET_ATTRIBUTE_RESULT Reports the result of a request to change a client attribute.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • DUPLICATE_VALUE
  • CLIENT_NOT_FOUND
  • IMMUTABLE
  • SERVER_ONLY
  • EVALUATION_FAILED
SET_ROOM_ATTR_RESULT u74
  • roomID
  • attrName
  • status
 RoomEvent.SET_ROOM_ATTRIBUTE_RESULT Reports the result of a request to change a room attribute.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • IMMUTABLE
  • SERVER_ONLY
  • ROOM_NOT_FOUND
  • EVALUATION_FAILED
GET_NUM_CLIENTS_RESULT u75
  • scope
  • status
 RoomEvent.GET_NUM_CLIENTS_RESULT, RoomManagerEvent.GET_NUM_CLIENTS_RESULT, ServerEvent.GET_NUM_CLIENTS_RESULT Reports the result of a request for the number of clients in the specified scope, where scope is one of:
  • a room id
  • a room id qualifier (where "*" means the unnamed qualifier, and "chat.sports.*" means all rooms with the qualifier "chat.sports")
  • "" (meaning the entire server)
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • ROOM_NOT_FOUND
LEAVE_ROOM_RESULT u76
  • roomID
  • status
 RoomEvent.LEAVE_RESULT, RoomManagerEvent.LEAVE_NONEXISTENT_ROOM Reports the result of an attempt to leave the specified roomID. See u10.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • NOT_IN_ROOM
  • ROOM_NOT_FOUND
OBSERVE_ROOM_RESULT u77
  • roomID
  • status
 RoomEvent.OBSERVE_RESULT, RoomManagerEvent.OBSERVE_NONEXISTENT_ROOM Reports the result of a room observation attempt (u58) by the client. If status is SUCCESS, the client is also sent a separate u59 message.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • ROOM_NOT_FOUND
  • AUTHORIZATION_REQUIRED
  • AUTHORIZATION_FAILED
  • ALREADY_OBSERVING
STOP_OBSERVING_ROOM_RESULT u78
  • roomID
  • status
 RoomEvent.STOP_OBSERVING, RoomManagerEvent.STOP_OBSERVING_NONEXISTENT_ROOM Reports the result of an attempt to stop observing the specified roomID. See u61.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • ROOM_NOT_FOUND
  • NOT_OBSERVING
ROOM_ATTR_REMOVED u79
  • roomID
  • clientID
  • attrName
 RoomEvent.DELETE_ROOM_ATTRIBUTE Reports the removal of a room attribute. The clientID specifies the id of the client that removed the attribute. If the attribute was not removed by a client (as is the case when the server removes the attribute), clientID is empty.
REMOVE_ROOM_ATTR_RESULT u80
  • roomID
  • attrName
  • status
 RoomEvent.DELETE_ROOM_ATTRIBUTE_RESULT Reports the result of a request to remove a room attribute.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • IMMUTABLE
  • SERVER_ONLY
  • ROOM_NOT_FOUND
  • ATTR_NOT_FOUND
CLIENT_ATTR_REMOVED u81
  • roomID
  • clientID
  • attrName
 RoomEvent.DELETE_CLIENT_ATTRIBUTE Reports the removal of a client attribute.
REMOVE_CLIENT_ATTR_RESULT u82
  • roomID
  • clientID
  • attrName
  • status
 RoomEvent.DELETE_CLIENT_ATTRIBUTE_RESULT Reports the result of a request to remove a client attribute.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • CLIENT_NOT_FOUND
  • IMMUTABLE
  • SERVER_ONLY
  • ATTR_NOT_FOUND
SESSION_TERMINATED u84 Informs the client that its session has been terminated. u84 is sent to the client when the server forcibly ends the client's session.
SESSION_NOT_FOUND u85 Informs the client that it sent an unknown session id. u85 is sent to the client in the following situations:
  • The client sends a sessionID that is no longer valid on the server
  • The client sends a sessionID that has never existed on the server
  • The client sends a malformed sessionID
    LOGOFF_RESULT u87
    • userID
    • status
    		 ClientEvent.LOGOFF_RESULT Reports the result of an attempt to log off the client with the specified userID. See u86.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • AUTHORIZATION_FAILED
    • ACCOUNT_NOT_FOUND
    • NOT_LOGGED_IN
    LOGGED_IN u88
    • clientID
    • userID
    		 ClientEvent.LOGGED_IN Informs the recipient that the client with the specified clientID has logged in. See u14.
    LOGGED_OFF u89
    • clientID
    • userID
    		 ClientEvent.LOGGED_OFF Informs the recipient that the client with the specified clientID has logged off. That client will also subsequently be disconnected. See u86.
    ACCOUNT_PASSWORD_CHANGED u90 ClientEvent.ACCOUNT_PASSWORD_CHANGED Informs the receiving client that its password has been changed. See u13.
    CLIENT_LIST_UPDATE u101
    • clientID1 [RS] userID1 [RS] clientID2 [RS] userID2 [RS]...clientIDn [RS] userIDn
    		 ClientManagerEvent.ADD_CLIENT, ClientManagerEvent.REMOVE_CLIENT Provides a list of either all clients currently connected to the server or all user accounts currently registered on the server. When u101 lists all connected clients, userIDs are also included for all logged in clients. When u101 lists all user accounts, clientIDs are also included for all logged in clients. See u91 and u97.
    CLIENT_ADDED_TO_SERVER u102
    • clientID
    		 ClientManagerEvent.CLIENT_CONNECTED Informs the recipient that the client with the specified clientID has connected to the server. See u92.
    CLIENT_REMOVED_FROM_SERVER u103
    • clientID
    		 ClientManagerEvent.CLIENT_DISCONNECTED Informs the recipient that the client with the specified clientID has disconnected from the server. See u92.
    CLIENT_SNAPSHOT u104
    • clientID
    • userID
    • occupiedRoom1 [RS] occupiedRoomID2 [RS] ...occupiedRoomIDn
    • observedRoom1 [RS] observedRoomID2 [RS] ...observedRoomIDn
    • globalAttrName1[RS]globalAttrValue1 [RS] globalAttrName2[RS]globalAttrValue2 [RS] globalAttrNamen[RS]globalAttrValuen
    • roomID1
    • roomAttrName1[RS]roomAttrValue1 [RS] roomAttrName2[RS]roomAttrValue2 [RS] roomAttrNamen[RS]roomAttrValuen
    • roomID2
    • roomAttrName1[RS]roomAttrValue1 [RS] roomAttrName2[RS]roomAttrValue2 [RS] roomAttrNamen[RS]roomAttrValuen
    • ...
    • roomIDn
    • roomAttrName1[RS]roomAttrValue1 [RS] roomAttrName2[RS]roomAttrValue2 [RS] roomAttrNamen[RS]roomAttrValuen
    		 ClientEvent.UPDATE_ATTRIBUTE, ClientEvent.DELETE_ATTRIBUTE, ClientEvent.JOIN_ROOM, ClientEvent.LEAVE_ROOM, ClientEvent.OBSERVE_ROOM, ClientEvent.STOP_OBSERVING_ROOM, ClientEvent.SYNCHRONIZE Provides a manifest describing the state of the specified client or user account (or both, in the case of logged-in users). See u94 and u100. The content of the manifest is limited by the receiving client's security privileges.
    OBSERVE_CLIENT_RESULT u105
    • clientID
    • status
    		 ClientEvent.OBSERVE_RESULT, ClientManagerEvent.OBSERVE_NONEXISTENT_CLIENT Reports the result of a client observation attempt (u95) made by the recipient. If status is SUCCESS, the client is also sent a separate u119 message.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • CLIENT_NOT_FOUND
    • ALREADY_OBSERVING
    STOP_OBSERVING_CLIENT_RESULT u106
    • clientID
    • status
    		 ClientEvent.STOP_OBSERVING_RESULT, ClientManagerEvent.STOP_OBSERVING_NONEXISTENT_CLIENT Reports the result of an attempt by the recipient to stop observing the specified client (see u96). If status is SUCCESS, the client is also sent a separate u120 message.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • CLIENT_NOT_FOUND
    • NOT_OBSERVING
    WATCH_FOR_CLIENTS_RESULT u107
    • status
    		 ClientManagerEvent.WATCH_FOR_CLIENTS_RESULT Reports the result of a WATCH_FOR_CLIENTS (u92) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • ALREADY_WATCHING
    STOP_WATCHING_FOR_CLIENTS_RESULT u108
    • status
    		 ClientManagerEvent.STOP_WATCHING_FOR_CLIENTS_RESULT Reports the result of a STOP_WATCHING_FOR_CLIENTS (u93) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • NOT_WATCHING
    WATCH_FOR_USERS_RESULT u109
    • status
    		 ClientManagerEvent.WATCH_FOR_USERS_RESULT Reports the result of a WATCH_FOR_USERS (u98) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • ALREADY_WATCHING
    STOP_WATCHING_FOR_USERS_RESULT u110
    • status
    		 ClientManagerEvent.STOP_WATCHING_FOR_USERS_RESULT Reports the result of a STOP_WATCHING_FOR_USERS (u99) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • NOT_WATCHING
    USER_ADDED u111
    • userID
    		 ClientManagerEvent.USER_ACCOUNT_ADDED Informs the recipient that a new user account with the specified userID was created. See u98.
    USER_REMOVED u112
    • userID
    		 ClientManagerEvent.USER_ACCOUNT_REMOVED Informs the recipient that the user account with the specified userID was removed from the server. See u98.
    JOINED_ROOM_ADDED_TO_CLIENT u113
    • clientID
    • roomID
    		 ClientEvent.JOIN_ROOM Informs the recipient that the specified client joined the specified room.
    JOINED_ROOM_REMOVED_FROM_CLIENT u114
    • clientID
    • roomID
    		 ClientEvent.LEAVE_ROOM Informs the recipient that the specified client left the specified room.
    SYNC_CLIENT_RESULT u115
    • clientID
    • status
    		 ClientManagerEvent.SYNC_NONEXISTING_CLIENT, ClientEvent.SYNCHRONIZE_RESULT Reports the result of a SYNC_CLIENT (u94) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • CLIENT_NOT_FOUND
    • ALREADY_SYNCHRONIZED (because the recipient is currently observing the specified client)
    SYNC_USER_RESULT u116
    • userID
    • status
    		 ClientManagerEvent.SYNC_NONEXISTING_USER, ClientEvent.SYNCHRONIZE_RESULT Reports the result of a SYNC_USER (u100) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • USER_NOT_FOUND
    OBSERVED_ROOM_ADDED_TO_CLIENT u117
    • clientID
    • roomID
    		 ClientEvent.OBSERVE_ROOM Informs the recipient that the specified client observed the specified room.
    OBSERVED_ROOM_REMOVED_FROM_CLIENT u118
    • clientID
    • roomID
    		 ClientEvent.STOP_OBSERVING_ROOM Informs the recipient that the specified client stopped observing the specified room.
    CLIENT_OBSERVED u119
    • clientID
    		 ClientEvent.OBSERVE Informs the recipient that it started observing the specified client.
    STOPPED_OBSERVING_CLIENT u120
    • clientID
    		 ClientEvent.STOP_OBSERVING Informs the recipient that it stopped observing the specified client.