Union Procedure Call Protocol Specification

UPC Protocol Version

1.10.3

Latest Version

The most recent version of the UPC protocol is available at: http://unionplatform.com/specs/upc/.

Prior Versions

Older versions of the UPC protocol are available under Revision History.

Message Structure

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 Union application developers need not necessarily be concerned with the format of raw UPC messages because Union Server and some Union client frameworks wrap UPC messages in a higher-level API. For example, in the Reactor framework 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. However, some lightweight frameworks, such as OrbiterMicro, require the application developer to communicate by sending and responding to UPC messages directly.

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]".

Nested CDATA

Before transporting UPC messages that contain other UPC messages (e.g., u155), Union Server and Union clients escape any nested CDATA-section start-and-end tokens as follows:

For example, the following CDATA section:

<[CDATA[Hello]]>

becomes:

<([CDATA[Hello]])>

Protocol Compatibility

The UPC protocol version takes format: majorNumber.minorNumber.revisionNumber. For example, in the version number 1.2.0, the majorNumber is 1, the minorNumber is 2, and the revisionNumber is 0. Every client must declare its UPC protocol version in its initial u65 message. If a client's declared version number does not match the server's then the client is either loosely or strictly incompatible with the server. Strictly incompatible clients are disconnected automatically. For complete details, see the description for the u65 message.

Native UPC Messages

Tables 1 and 2 list all messages in the UPC protocol.

Table 1: Client-to-Server Messages

Official Message Name Internal Message ID Arguments Corresponding Client 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". To send a message to all rooms qualified by the unnamed qualifier, use "*" for the room qualifier.

The server sends separate u7 messages for every room in the room list. For example, if the room list is "chat1 [RS] 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
  • userID
  • attrName
  • escapedAttrValue
  • attrScope
  • attrOptions, an integer whose bits have the following meaning when set:
    • 0 - RESERVED
    • 1 - RESERVED
    • 2 - shared
    • 3 - persistent
    • 4 - RETIRED (formerly "unique")
    • 5 - RESERVED BY SERVER
    • 6 - RESERVED BY SERVER
    • 7 - RESERVED BY SERVER
    • 8 - evaluate
 Client.setAttribute(), UserAccount.setAttribute()

Asks the server to set a client attribute for client specified by clientID or the user account specified by userID. If the persistent bit is set, the server sets the attribute on the specified userID's account; if not, the server sets the attribute on the specified client. 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. When the sender sets one of its own attributes via u3, the new attribute value is echoed back to the sender in a u8 in the following situations only:

  • The persistent bit is set
  • The evaluate bit is set

The specified 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 in the account specified by userID, and will be available to any client that successfully logs into that account
  • 4 - RETIRED (formerly "unique")
  • 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(), RoomManager.joinRoom() 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
 AccountManager.createAccount() Asks the server to create a new user 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
 AccountManager.removeAccount() Asks the server to remove the user account for the specified userID. Results of the remove-account attempt are returned via a u48.
CHANGE_ACCOUNT_PASSWORD u13
  • userID
  • oldPassword
  • newPassword
 AccountManager.changePassword(), UserAccount.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
 AccountManager.login() Asks the server to login 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_CLIENTCOUNT_SNAPSHOT u18
  • requestID
 ClientCountSnapshot

Asks the server to return the number of clients on the server.

The result of a u18 request is returned to the sender via a u75. If the request is successful, the number of clients on the server 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_ROOMLIST_SNAPSHOT u21
  • requestID
  • roomIdQualifier
  • recursive
 RoomListSnapshot

Asks the server to return a list of the rooms whose ids are qualified by roomIdQualifier. The result is returned via a u38.

For a server-wide room list, supply the empty string ("") for roomIdQualifier and true for recursive.

For a list of rooms with the unnamed qualifier, supply the empty string ("") for roomIdQualifier and false for recursive.

For a list of rooms with the qualifier "chat.sports", supply "chat.sports" for roomIdQualifier and false for recursive.

Note: the recursive argument is currently available for the unnamed qualifier ("") only. Recursion for other qualifiers is planned for future versions of the UPC protocol.
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)

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
  • recursive
 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 all rooms on the server, supply the empty string ("") for roomIdQualifier and true for recursive.

To watch for rooms with the unnamed qualifier, supply the empty string ("") for roomIdQualifier and false for recursive.

To watch for rooms with the qualifier "examples", supply "examples" for roomIdQualifier and false for recursive.

Note: the recursive argument is currently available for the unnamed qualifier ("") only. Recursion for other qualifiers is planned for future versions of the UPC protocol.
STOP_WATCHING_FOR_ROOMS u27
  • roomIdQualifier
  • recursive
 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 all rooms on the server, supply the empty string ("") for roomIdQualifier and true for recursive.

To stop watching for rooms with the unnamed qualifier, supply the empty string ("") for roomIdQualifier and false for recursive.

To stop watching for rooms with the qualifier "examples", supply "examples" for roomIdQualifier and false for recursive.

Note: the recursive argument is currently available for the unnamed qualifier ("") only. Recursion for other qualifiers is planned for future versions of the UPC protocol.
GET_ROOM_SNAPSHOT u55
  • requestID
  • roomID
  • password
  • updateLevels
 RoomSnapshot 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. The updateLevels parameter specifies the amount of information that should be included in the snapshot, following the rules described under u64. If updateLevels is not supplied, the sender's update levels for the room are used. If the sender does not have update levels specified for the room, the room's maximum levels are used.
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
  • updateLevel
 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. When a client's room update levels change, the server sends that client a u128. The updateLevel parameter is an integer whose ordered bits represent the following update levels:

  • 0 room messages
  • 1 room shared attributes *
  • 2 occupant count
  • 3 observer count
  • 4 occupant list *
  • 5 observer list *
  • 6 occupant shared room attributes *, **
  • 7 observer shared room attributes *, ***
  • 8 occupant shared global attributes *, **
  • 9 observer shared global attributes *, ***
  • 10 occupant login/logoffs *, **
  • 11 observer login/logoffs *, ***
  • 12 all room attributes *, ****

The update levels specified by the preceding bits determine how much information is pushed to the client when it is either in or observing a room.

In the preceding list, *, **, ***, and **** have the following meanings:

  • * When a client joins a room it is not already observing, or observes a room it is not already in, it is sent a u54 describing the current state of the room
  • ** When this bit is on, bit 4 is automatically turned on
  • *** When this bit is on, bit 5 is automatically turned on
  • **** This bit requires administrator privileges
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 strictly 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
  • Orbiter
  • OrbiterMicro
  • 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. In this case, the client is considered strictly incompatible with the server.
  • 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. In this case, the client is considered loosely incompatible with the server. Based on the features required in the application, the client application must, itself, decide whether to stay connected. 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
  • userID
  • attrName
  • scope
 Client.deleteAttribute(), UserAccount.deleteAttribute() Asks the server to remove a client attribute from the client specified by clientID or the user account specified by userID. The clientID and userID arguments are mutually exclusive; only one or the other is allowed. 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 [RS] argValue1
  • argName2 [RS] argValue2
  • ...
  • argNamen [RS] 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 [RS] argValue1
  • argName2 [RS] argValue2
  • ...
  • argNamen [RS] 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
 AccountManager.logoff(), UserAccount.logoff() Asks the server to logoff the user 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_CLIENTLIST_SNAPSHOT u91
  • requestID
 ClientListSnapshot 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.
WATCH_FOR_CLIENTS u92 ClientManager.watchForClients() Asks the server to inform the client when clients connect or disconnect, or login or logoff. 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. Subsequent client logins trigger a u88; subsequent client logoffs trigger a u89.
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.
GET_CLIENT_SNAPSHOT u94
  • requestID
  • clientID
 ClientSnapshot Asks the server to send a snapshot for the specified client. In response, the server sends a u115 and, if the request succeeds, a u104.
OBSERVE_CLIENT 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 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_ACCOUNTLIST_SNAPSHOT u97
  • requestID
 AccountListSnapshot Asks the server to send a list of userIDs for all registered user accounts on the server. The result is sent via a u127. See also u91.
WATCH_FOR_ACCOUNTS u98 AccountManager.watchForAccounts() 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 u127. Subsequent user-account creations trigger a u111; subsequent user-account removals trigger a u112.
STOP_WATCHING_FOR_ACCOUNTS u99 AccountManager.stopWatchingForAccounts() Asks the server to stop sending user-account creation-and-removal notifications. The server sends the result of the request via a u110.
GET_ACCOUNT_SNAPSHOT u100
  • requestID
  • userID
 AccountSnapshot Asks the server to send a snapshot for the specified user account, including all persistent data stored in the user's account. In response, the server sends a u116 and, if the request succeeds, a u104.
OBSERVE_ACCOUNT u121
  • userID
 UserAccount.observe(), AccountManager.observeAccount() Asks the server to register the sender as an observer of the specified user account. In response, the server sends a u123 and, if the request succeeds, a u124. Subsequently if the specified user account's state changes, the observing client is notified in the following ways:
  • Observed account logs in: observer receives a u88
  • Observed account logs off: observer receives a u89
  • Observed account deleted: observer receives a u112
STOP_OBSERVING_ACCOUNT u122
  • userID
 UserAccount.stopObserving(), AccountManager.stopObservingAccount() Asks the server to unregister the sender as an observer of the specified user account. In response, the server sends a u125. If the request succeeds, the server also sends a u126, and stops sending updates about the specified user account.
ADD_ROLE u133
  • userID
  • role
 UserAccount.addRole(), AccountManager.addRole() Asks the server to assign the specified role to the user account with the specified userID. In response, the server sends a u134. An account's role(s) determine which actions a user is allowed to perform on Union Server. For a list of security actions and corresponding rules, see Union Server's documentation. Legal values for role are:
  • MODERATOR
REMOVE_ROLE u135
  • userID
  • role
 UserAccount.removeRole(), AccountManager.removeRole() Asks the server to remove the specified role from the user account with the specified userID. In response, the server sends a u136. Legal values for role are listed under u133.
BAN u137
  • address
  • clientID
  • duration
  • reason
 ClientManager.ban(), Client.ban() Asks the server to refuse all connection attempts made by a particular client address. A "client address" is the logical origin of a client connection, typically an IP address. If the address parameter is provided, the specified address is banned and clientID is ignored. If no address parameter is provided, then clientID must be provided, and the address of the client with the specified clientID is banned. The ban lasts for the number of seconds specified by duration. The reason parameter is an arbitrary optional string indicating the reason for the ban. The reason string is stored by the server in the banned list. The result of a ban attempt is returned via a u138. A list of current banned addresses can be retrieved via a u141 or u143.
UNBAN u139
  • address
 ClientManager.unban(), Client.unban() Asks the server to remove a banned a client address from the banned list. The result of the unban attempt is returned via a u140.
GET_BANNED_LIST_SNAPSHOT u141
  • requestID
 ClientListSnapshot Asks the server to send a list of addresses currently banned from connecting to the server. The result is sent via a u142. See also u143.
WATCH_FOR_BANNED_ADDRESSES u143 ClientManager.watchForBannedAddresses() Asks the server to inform the sending client when addresses are banned or unbanned. The server sends the result of the request via a u144. If the request was successful, the server also sends a u142. Subsequently, when an address is banned, the server sends a u147; when an address is unbanned, the server sends a u148.
STOP_WATCHING_FOR_BANNED_ADDRESSES u145 ClientManager.stopWatchingForBannedAddresses() Asks the server to stop sending banned-address notifications. The server sends the result of the request via a u146.
KICK_CLIENT u149
  • clientID
 ClientManager.kickClient(), Client.kick() Asks the server to forcibly disconnect the client with the specified clientID. The server sends the result of the request via a u150.
GET_SERVERMODULELIST_SNAPSHOT u151
  • requestID
 ServerModuleListSnapshot Asks the server to send a list of currently active server modules (not to be confused with room modules). The result is sent via a u152. By default, u151 requires administrator privileges.
CLEAR_MODULE_CACHE u153 Server.clearModuleCache() Asks the server to remove all current module class definitions from memory. Subsequently instantiated modules will use the newly loaded module class definitions, allowing module developers to update Union Server's modules at runtime without restarting the server. By default, u153 requires administrator privileges.
GET_UPC_STATS_SNAPSHOT u154 UPCStatsSnapshot Asks the server to send a list of UPC-message-processing statistics. In response, the server sends a u155 and, if the request succeeds, a u156. By default, u154 requires administrator privileges.
RESET_UPC_STATS u157 Server.resetUPCStats() Asks the server to reset server-side UPC-processing statistics. The following statistics are affected by a reset:
  • the list of the longest UPC-message-processing times
The result of a u157 request is sent via a u158. The statistics-reset is reflected in any subsequent u156 transmission. By default, u157 requires administrator privileges.
WATCH_FOR_PROCESSED_UPCS u159 Server.watchForProcessedUPCs() Asks the server to notify the sending client upon processing any UPC message. The server sends the result of the request via a u160. Notifications are transmitted via u161. By default, u159 requires administrator privileges.
STOP_WATCHING_FOR_PROCESSED_UPCS u162 Server.stopWatchingForProcessedUPCs() Asks the server to stop sending UPC-processing notifications to the sending client. The server sends the result of the request via a u163. By default, u162 requires administrator privileges.
GET_NODELIST_SNAPSHOT u165
  • requestID
 NodeListSnapshot

Asks the server to return a list of the cluster nodes currently connected to the server. The result is returned via a u166.
GET_GATEWAYS_SNAPSHOT u167
  • requestID
 GatewaysSnapshot

Asks the server to return a per-gateway summary of connection and bandwidth statistics. The result is returned via a u168. By default, access to gateway statistics requires administrator privileges.

Table 2: Server-to-Client Messages

Official Message Name Internal Message ID Arguments Corresponding Client 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
  • userID
  • attrName
  • attrVal
  • attrOptions
 AttributeEvent.UPDATE Reports a change to a client attribute.
ROOM_ATTR_UPDATE u9
  • roomID
  • clientID
  • attrName
  • attrVal
 AttributeEvent.UPDATE 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
  • PERMISSION_DENIED
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
  • PERMISSION_DENIED
CLIENTCOUNT_SNAPSHOT u34
  • requestID
  • numClients
 ClientCountSnapshot Reports the number of clients on the server.
CLIENT_ADDED_TO_ROOM u36
  • roomID
  • clientID
  • userID
  • globalAttrName1 [RS] globalAttrValue1 [RS] globalAttrOptions1 [RS] ... globalAttrNamen [RS] globalAttrValuen [RS] globalAttrOptionsn
  • roomAttrName1 [RS] roomAttrValue1 [RS] roomAttrOptions1 [RS] ... roomAttrNamen [RS] roomAttrValuen [RS] roomAttrOptionsn
 RoomEvent.ADD_OCCUPANT Reports that the specified client has joined the specified room.
CLIENT_REMOVED_FROM_ROOM u37
  • roomID
  • clientID
 RoomEvent.REMOVE_OCCUPANT Reports that the specified client has left the specified room.
ROOMLIST_SNAPSHOT u38
  • requestID
  • requestedRoomIDQualifier
  • recursive
  • roomIDQualifier1
  • roomID1 [RS] roomID2 [RS] ...roomIDn
  • roomIDQualifier2
  • roomID1 [RS] roomID2 [RS] ...roomIDn
  • ...
  • roomIDQualifiern
  • roomID1 [RS] roomID2 [RS] ...roomIDn
 RoomManagerEvent.ROOM_ADDED, RoomManagerEvent.ROOM_REMOVED Provides a list of rooms on the server. A u38 is sent in response to u21 and u26. The requestedRoomIDQualifier and recursive arguments are the original values supplied to the call that generated the room list.
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
  • recursive
  • status
 RoomManagerEvent.WATCH_FOR_ROOMS_RESULT Reports the result of a u26 request. The roomIdQualifier and recursive arguments specify the values supplied to the instigating u26 request.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • INVALID_QUALIFIER
  • ALREADY_WATCHING
  • PERMISSION_DENIED
STOP_WATCHING_FOR_ROOMS_RESULT u43
  • roomIdQualifier
  • recursive
  • status
 RoomManagerEvent.STOP_WATCHING_FOR_ROOMS_RESULT Reports the result of a u27 request. The roomIdQualifier and recursive arguments specify the values supplied to the instigating u26 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
 AccountEvent.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
 AccountManagerEvent.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
  • PERMISSION_DENIED
REMOVE_ACCOUNT_RESULT u48
  • userID
  • status
 AccountManagerEvent.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
  • PERMISSION_DENIED
LOGIN_RESULT u49
  • userID
  • status
 AccountEvent.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
  • PERMISSION_DENIED
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
  • requestID
  • roomID
  • occupantCount
  • observerCount
  • roomAttrName1[RS]roomAttrValue1 [RS] roomAttrName2[RS]roomAttrValue2 [RS] roomAttrNamen[RS]roomAttrValuen
  • client1clientID
  • client1userID
  • client1occupantObserverIndicator
  • client1GlobalAttrName1 [RS] client1GlobalAttrValue1 [RS] client1GlobalAttrOptions1 [RS]
    ...
    client1GlobalAttrNamen [RS] client1GlobalAttrValuen [RS] client1GlobalAttrOptionsn
  • client1RoomAttrName1 [RS] client1RoomAttrValue1 [RS] client1RoomAttrOptions1
    ...
    client1RoomAttrNamen [RS] client1RoomAttrValuen [RS] client1RoomAttrOptionsn
  • ...
  • clientnclientID
  • clientnuserID
  • clientnoccupantObserverIndicator
  • clientnGlobalAttrName1 [RS] clientnGlobalAttrValue1 [RS] clientnGlobalAttrOptions1 [RS]
    ...
    clientnGlobalAttrNamen [RS] clientnGlobalAttrValuen [RS] clientnGlobalAttrOptionsn
  • clientnRoomAttrName1 [RS] clientnRoomAttrValue1 [RS] clientnRoomAttrOptions1 [RS]
    ...
    clientnRoomAttrNamen [RS] clientnRoomAttrValuen [RS] clientnRoomAttrOptionsn
 RoomEvent.SYNCHRONIZE 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. The server sends u54 messages in response to either joining a room (u4), observing a room (u58), or requesting a room snapshot (u55). The "occupantObserverIndicator" parameter indicates whether the client is an occupant of the room (in which case, occupantObserverIndicator is 0) or an observer of the room (in which case, occupantObserverIndicator is 1).
OBSERVED_ROOM u59
  • roomID
 RoomEvent.OBSERVE Informs the client that it started observing the specified room.
GET_ROOM_SNAPSHOT_RESULT u60
  • requestID
  • roomID
  • status
 SnapshotEvent.STATUS Reports the result of a u55 request by the client.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • ROOM_NOT_FOUND
  • AUTHORIZATION_REQUIRED
  • AUTHORIZATION_FAILED
  • PERMISSION_DENIED
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
  • affinityAddress
  • affinityDuration
 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. The affinityAddress indicates the server's public address. When affinityAddress is provided, clients must send all communications to that address for the specified affinityDuration, which is given in minutes. Union Platform's affinity system ensures that a given client will connect to a specific Union Server node in a cluster for a specified duration, as is required in load-balanced configurations. For details, see Clustering Union Server.
JOIN_ROOM_RESULT u72
  • roomID
  • status
 RoomEvent.JOIN_RESULT 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
  • PERMISSION_DENIED
SET_CLIENT_ATTR_RESULT u73
  • roomID
  • clientID
  • userID
  • attrName
  • attrOptions
  • status
 AttributeEvent.SET_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
  • ACCOUNT_NOT_FOUND
  • IMMUTABLE
  • SERVER_ONLY
  • EVALUATION_FAILED
  • PERMISSION_DENIED
SET_ROOM_ATTR_RESULT u74
  • roomID
  • attrName
  • status
 AttributeEvent.SET_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
  • PERMISSION_DENIED
GET_CLIENTCOUNT_SNAPSHOT_RESULT u75
  • requestID
  • status
 SnapshotEvent.STATUS Reports the result of a request for the number of clients on the server.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
LEAVE_ROOM_RESULT u76
  • roomID
  • status
 RoomEvent.LEAVE_RESULT 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 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
  • PERMISSION_DENIED
STOP_OBSERVING_ROOM_RESULT u78
  • roomID
  • status
 RoomEvent.STOP_OBSERVING 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
 AttributeEvent.DELETE 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
 AttributeEvent.DELETE_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
  • PERMISSION_DENIED
CLIENT_ATTR_REMOVED u81
  • roomID
  • clientID
  • userID
  • attrName
  • attrOptions
 AttributeEvent.DELETE Reports the removal of a client attribute.
REMOVE_CLIENT_ATTR_RESULT u82
  • roomID
  • clientID
  • userID
  • attrName
  • attrOptions
  • status
 AttributeEvent.DELETE_RESULT Reports the result of a request to remove a client attribute.
  • SUCCESS
  • ERROR (An exception occurred on the server.)
  • CLIENT_NOT_FOUND
  • ACCOUNT_NOT_FOUND
  • IMMUTABLE
  • SERVER_ONLY
  • ATTR_NOT_FOUND
  • PERMISSION_DENIED
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
    		 AccountEvent.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
    • PERMISSION_DENIED
    LOGGED_IN u88
    • clientID
    • userID
    • globalAttrName1[RS]globalAttrValue1[RS]globalAttrOptions1 [RS] globalAttrNamen[RS]globalAttrValuen[RS]globalAttrOptionsn
    • roomID1
    • roomAttrName1[RS]roomAttrValue1[RS]roomAttrOptions1 [RS] roomAttrNamen[RS]roomAttrValuen[RS]roomAttrOptionsn
    • ...
    • roomIDn
    • roomAttrName1[RS]roomAttrValue1[RS]roomAttrOptions1 [RS] roomAttrNamen[RS]roomAttrValuen[RS]roomAttrOptionsn
    		 AccountEvent.LOGGED_IN Informs the recipient that the client with the specified clientID has logged into the account with the specified userID. See u14. Depending on the recipient's awareness of the logged in account, the u88 message includes the account's persistent attributes according to the following rules:
    • If the recipient is observing the client with the specified clientID (see u95): global attributes and room attributes are included
    • If the recipient is observing the account with the specified userID (see u121): global attributes are included; room attributes are not included
    • If the recipient is watching for clients (see u92): no attributes are loaded
    • If the recipient is in or observing a room that the specified client is also in or observing: global attributes and attributes scoped to that room are included in accordance with the recipient's update levels for the room
    • If the recipient is the client that is logging in: global attributes are included; room-scoped attributes are not included
    LOGGED_OFF u89
    • clientID
    • userID
    		 AccountEvent.LOGGED_OFF Informs the recipient that the client with the specified clientID has logged off of the account with the specified userID. That client will also subsequently be disconnected. See u86.
    ACCOUNT_PASSWORD_CHANGED u90 AccountEvent.ACCOUNT_PASSWORD_CHANGED Informs the receiving client that its password has been changed. See u13.
    CLIENTLIST_SNAPSHOT u101
    • requestID
    • clientID1 [RS] userID1 [RS] clientID2 [RS] userID2 [RS]...clientIDn [RS] userIDn
    		 ClientManagerEvent.CLIENT_CONNECTED, ClientManagerEvent.CLIENT_DISCONNECTED, ClientManagerEvent.SYNCHRONIZE Provides a list of all clients currently connected to the server. For all clients that are logged in, userIDs are also included. See u91.
    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
    • requestID
    • clientID
    • userID
    • occupiedRoom1 [RS] occupiedRoomID2 [RS] ...occupiedRoomIDn
    • observedRoom1 [RS] observedRoomID2 [RS] ...observedRoomIDn
    • globalAttrName1[RS]globalAttrValue1[RS]globalAttrOptions1 [RS] globalAttrNamen[RS]globalAttrValuen[RS]globalAttrOptionsn
    • roomID1
    • roomAttrName1[RS]roomAttrValue1[RS]roomAttrOptions1 [RS] roomAttrNamen[RS]roomAttrValuen[RS]roomAttrOptionsn
    • ...
    • roomIDn
    • roomAttrName1[RS]roomAttrValue1[RS]roomAttrOptions1 [RS] roomAttrNamen[RS]roomAttrValuen[RS]roomAttrOptionsn
    		 ClientEvent.SYNCHRONIZE, AccountEvent.SYNCHRONIZE Provides a manifest describing the state of the specified client (and user account, in the case of logged-in clients). See u94, u95, 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 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
    • PERMISSION_DENIED
    STOP_OBSERVING_CLIENT_RESULT u106
    • clientID
    • status
    		 ClientEvent.STOP_OBSERVING_RESULT 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_ACCOUNTS_RESULT u109
    • status
    		 AccountManagerEvent.WATCH_FOR_ACCOUNTS_RESULT Reports the result of a WATCH_FOR_ACCOUNTS (u98) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • ALREADY_WATCHING
    STOP_WATCHING_FOR_ACCOUNTS_RESULT u110
    • status
    		 AccountManagerEvent.STOP_WATCHING_FOR_ACCOUNTS_RESULT Reports the result of a STOP_WATCHING_FOR_ACCOUNTS (u99) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • NOT_WATCHING
    ACCOUNT_ADDED u111
    • userID
    		 AccountManagerEvent.ACCOUNT_ADDED Informs the recipient that a new user account with the specified userID was created. See u98.
    ACCOUNT_REMOVED u112
    • userID
    		 AccountManagerEvent.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.
    GET_CLIENT_SNAPSHOT_RESULT u115
    • requestID
    • clientID
    • status
    		 SnapshotEvent.STATUS Reports the result of a u94 request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • CLIENT_NOT_FOUND
    GET_ACCOUNT_SNAPSHOT_RESULT u116
    • requestID
    • userID
    • status
    		 SnapshotEvent.STATUS Reports the result of a u100 request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • ACCOUNT_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.
    OBSERVE_ACCOUNT_RESULT u123
    • userID
    • status
    		 AccountEvent.OBSERVE_RESULT Reports the result of a user-account observation attempt (u121) made by the recipient. If status is SUCCESS, the client is also sent a separate u124 message.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • ACCOUNT_NOT_FOUND
    • ALREADY_OBSERVING
    ACCOUNT_OBSERVED u124
    • userID
    		 AccountEvent.OBSERVE Informs the recipient that it started observing the specified user account.
    STOP_OBSERVING_ACCOUNT_RESULT u125
    • userID
    • status
    		 AccountEvent.STOP_OBSERVING_RESULT Reports the result of an attempt by the recipient to stop observing the specified user account (see u122). If status is SUCCESS, the client is also sent a separate u126 message.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • ACCOUNT_NOT_FOUND
    • NOT_OBSERVING
    STOPPED_OBSERVING_ACCOUNT u126
    • userID
    		 AccountEvent.STOP_OBSERVING Informs the recipient that it stopped observing the specified user account.
    ACCOUNTLIST_SNAPSHOT u127
    • requestID
    • userID1 [RS] userID2 [RS]...userIDn
    		 AccountManagerEvent.ACCOUNT_ADDED, AccountManagerEvent.ACCOUNT_REMOVED, AccountManagerEvent.SYNCHRONIZE Provides a list of all user accounts currently registered on the server. See u97.
    UPDATE_LEVELS_UPDATE u128
    • updateLevels
    • roomID
    		 Informs the receiving client that its update levels for a room have changed. See u64.
    CLIENT_OBSERVED_ROOM u129
    • roomID
    • clientID
    • userID
    • globalAttrName1 [RS] globalAttrValue1 [RS] globalAttrOptions1 [RS] ... globalAttrNamen [RS] globalAttrValuen [RS] globalAttrOptionsn
    • roomAttrName1 [RS] roomAttrValue1 [RS] roomAttrOptions1 [RS] ... roomAttrNamen [RS] roomAttrValuen [RS] roomAttrOptionsn
    		 RoomEvent.ADD_OBSERVER Reports that the specified client has observed the specified room.
    CLIENT_STOPPED_OBSERVING_ROOM u130
    • roomID
    • clientID
    		 RoomEvent.REMOVE_OBSERVER Reports that the specified client has stopped observing the specified room.
    ROOM_OCCUPANTCOUNT_UPDATE u131
    • roomID
    • numOccupants
    		 RoomEvent.OCCUPANT_COUNT Reports the new number of occupants in the room. u131 is sent to clients that have joined or observed a room, and have occupant-count updates enabled (see u64).
    ROOM_OBSERVERCOUNT_UPDATE u132
    • roomID
    • numObservers
    		 RoomEvent.OBSERVER_COUNT Reports the new number of observers in the room. u132 is sent to clients that have joined or observed a room, and have observer-count updates enabled (see u64).
    ADD_ROLE_RESULT u134
    • userID
    • role
    • status
    		 AccountEvent.ADD_ROLE_RESULT, AccountEvent.ROLE_ADDED Reports the result of an add-role attempt (u133) made by the recipient. If status is SUCCESS, and the specified user is logged in, then Union Server updates the _ROLES attribute on the client under which the user logged in.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • PERMISSION_DENIED
    • ACCOUNT_NOT_FOUND
    • ALREADY_ASSIGNED
    • ROLE_NOT_FOUND
    REMOVE_ROLE_RESULT u136
    • userID
    • role
    • status
    		 AccountEvent.REMOVE_ROLE_RESULT, AccountEvent.ROLE_REMOVED Reports the result of a remove-role attempt (u135) made by the recipient. If status is SUCCESS, and the specified user is logged in, then Union Server updates the _ROLES attribute on the client under which the user logged in.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • PERMISSION_DENIED
    • ACCOUNT_NOT_FOUND
    • NOT_ASSIGNED
    • ROLE_NOT_FOUND
    BAN_RESULT u138
    • address
    • clientID
    • status
    		 ClientManagerEvent.BAN_RESULT Reports the result of a ban attempt (u137) made by the recipient. If status is SUCCESS, connection attempts by any client at the specified address are refused by Union Server. If the original u137 included a clientID and no address, that clientID is returned via u138's clientID.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • PERMISSION_DENIED
    • ALREADY_BANNED
    • CLIENT_NOT_FOUND
    UNBAN_RESULT u140
    • address
    • status
    		 ClientManagerEvent.UNBAN_RESULT Reports the result of an unban attempt (u137) made by the recipient. If status is SUCCESS, any previous connection ban on the specified address is lifted.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • PERMISSION_DENIED
    • NOT_BANNED
    BANNED_LIST_SNAPSHOT u142
    • requestID
    • address1 [RS] address2 [RS] ...addressn
    		 ClientManagerEvent.SYNCHRONIZE_BANLIST Provides a list of addresses currently banned from connecting to the server. A u142 is sent in response to u141 and u143.
    WATCH_FOR_BANNED_ADDRESSES_RESULT u144
    • status
    		 ClientManagerEvent.WATCH_FOR_BANNED_ADDRESSES_RESULT Reports the result of a WATCH_FOR_BANNED_ADDRESSES (u143) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • ALREADY_WATCHING
    • PERMISSION_DENIED
    STOP_WATCHING_FOR_BANNED_ADDRESSES_RESULT u146
    • status
    		 ClientManagerEvent.STOP_WATCHING_FOR_BANNED_ADDRESSES_RESULT Reports the result of a STOP_WATCHING_FOR_BANNED_ADDRESSES (u145) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • NOT_WATCHING
    BANNED_ADDRESS_ADDED u147
    • address
    		 ClientManagerEvent.ADDRESS_BANNED Informs the recipient that the specified address has been banned from connecting to the server. See u143.
    BANNED_ADDRESS_REMOVED u148
    • address
    		 ClientManagerEvent.ADDRESS_UNBANNED Informs the recipient that the specified address has been unbanned. See u143.
    KICK_CLIENT_RESULT u150
    • status
    		 ClientManagerEvent.KICK_RESULT Reports the result of a KICK_CLIENT (u149) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • CLIENT_NOT_FOUND
    • PERMISSION_DENIED
    SERVERMODULELIST_SNAPSHOT u152
    • requestID
    • serverModuleID1 [RS] serverModuleType1 [RS] serverModuleSource1 [RS]...serverModuleIDn [RS] serverModuleTypen [RS] serverModuleSourcen
    		 SnapshotEvent.LOAD Provides a list of server modules currently active on Union Server. A u152 is sent in response to u151.
    GET_UPC_STATS_SNAPSHOT_RESULT u155
    • requestID
    • status
    		 SnapshotEvent.STATUS Reports the result of a GET_UPC_STATS_SNAPSHOT (u154) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • PERMISSION_DENIED
    UPC_STATS_SNAPSHOT u156
    • requestID
    • totalUPCsProcessed
    • numUPCsInQueue
    • lastQueueWaitTime
    • <![CDATA[ fromClientID1 [RS] fromClientUserID1 [RS] fromClientAddress1 [RS] longestUPCProcessQueuedAt1 [RS] longestUPCProcessStartedAt1 [RS] longestUPCProcessFinishedAt1 [RS] UPCSource1 ]]>
    • ...
    • <![CDATA[ fromClientIDn [RS] fromClientUserIDn [RS] fromClientAddressn [RS] longestUPCProcessQueuedAtn [RS] longestUPCProcessStartedAtn [RS] longestUPCProcessFinishedAtn [RS] UPCSourcen ]]>
    		 UPCStatsSnapshot Provides statistics about UPC messages received by Union Server. A u155 is sent in response to u154. Arguments following lastQueueWaitTime specify an unsorted list of the longest UPC message processing times since either Union Server was started or since the last UPC-statistics reset command (see u157). Any CDATA sections contained within UPCSource fields are escaped according to the rules described under "Nested CDATA".
    RESET_UPC_STATS_RESULT u158
    • status
    		 ServerEvent.RESET_UPC_STATS_RESULT Reports the result of a RESET_UPC_STATS (u157) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • PERMISSION_DENIED
    WATCH_FOR_PROCESSED_UPCS_RESULT u160
    • status
    		 ServerEvent.WATCH_FOR_PROCESSED_UPCS_RESULT Reports the result of a WATCH_FOR_PROCESSED_UPCS (u159) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • ALREADY_WATCHING
    • PERMISSION_DENIED
    PROCESSED_UPC_ADDED u161
    • fromClientID
    • fromClientUserID
    • fromClientAddress
    • UPCProcessQueuedAt
    • UPCProcessStartedAt
    • UPCProcessFinishedAt
    • <![CDATA[UPCSource]]>
    		 ServerEvent.UPC_PROCESSED Informs the recipient that the server processed the UPC message specified by UPCSource. See u160. Any CDATA sections contained within UPCSource are escaped according to the rules described under "Nested CDATA".
    STOP_WATCHING_FOR_PROCESSED_UPCS_RESULT u163
    • status
    		 ServerEvent.STOP_WATCHING_FOR_PROCESSED_UPCS_RESULT Reports the result of a STOP_WATCHING_FOR_PROCESSED_UPCS_RESULT (u162) request made by the recipient.
    • SUCCESS
    • ERROR (An exception occurred on the server.)
    • NOT_WATCHING
    • PERMISSION_DENIED
    CONNECTION_REFUSED u164
    • reason
    • description
    		 ReactorEvent.CONNECT_REFUSED Indicates that Union Server refused the requested client connection, typically because the client's address is banned. The reason argument indicates why the client connection was refused. The value of reason is either one of the following known refusal-reason codes, or an arbitrary string supplied by custom module code.
    • BANNED
    The description argument explains the cause of the refusal. The value of description is either given in one of the following known refusal-description formats, or is an arbitrary string supplied by custom module code.
    • bannedAt|banDuration|banReason
      • bannedAt
        The time at which the recipient client's address was banned by Union Server, in milliseconds-from-1970 format, UTC time, according to the server's clock.
      • banDuration
        The length of the ban, in seconds.
      • banReason
        The cause of the ban on this client's address, as an arbitrary string. For example: "You were banned for inappropriate use of language".
    NODELIST_SNAPSHOT u166
    • requestID
    • nodeID1 [RS] nodeID2 [RS] ...nodeIDn
    		 NodeListSnapshot Provides a list of IDs for the cluster nodes currently connected to the server. Each ID is an arbitrary, statistically unique string generated automatically by Union Server. A server's nodeID is guaranteed to be the same for a given server until that server shuts down. u166 is sent in response to u165.
    GATEWAYS_SNAPSHOT u168
    • requestID
    • gatewayID1
    • gatewayType1
    • NUM_CONNECTIONS_CATEGORY1 [RS] NUM_CONNECTIONS_CATEGORY1_VALUE [RS] NUM_CONNECTIONS_CATEGORY2 [RS] NUM_CONNECTIONS_CATEGORY2_VALUE [RS] NUM_CONNECTIONS_CATEGORYn [RS] NUM_CONNECTIONS_CATEGORYn_VALUE
    • NUM_CLIENTS_CLIENTTYPE1 [RS] NUM_CLIENTS_CLIENTTYPE1_VALUE [RS] NUM_CLIENTS_CLIENTTYPE2 [RS] NUM_CLIENTS_CLIENTTYPE2_VALUE [RS] NUM_CLIENTS_CLIENTTYPEn [RS] NUM_CLIENTS_CLIENTTYPEn_VALUE
    • NUM_CLIENTS_UPCVERSION1 [RS] NUM_CLIENTS_UPCVERSION1_VALUE [RS] NUM_CLIENTS_UPCVERSION2 [RS] NUM_CLIENTS_UPCVERSION2_VALUE [RS] NUM_CLIENTS_UPCVERSIONn [RS] NUM_CLIENTS_UPCVERSIONn_VALUE
    • gateway1AttrName1 [RS] gateway1AttrName1 [RS] gateway1AttrName2 [RS] gateway1AttrName2 [RS] gateway1AttrNamen [RS] gateway1AttrNamen
    • connectionsPerSecond [RS] maxConnectionsPerSecond [RS] clientsPerSecond [RS] maxClientsPerSecond
    • lifetimeRead [RS] lifetimeWritten [RS] averageRead [RS] averageWritten [RS] intervalRead [RS] intervalWritten [RS] maxIntervalRead [RS] maxIntervalWritten [RS] scheduledWrite
    • ...
    • gatewayIDn
    • gatewayTypen
    • NUM_CONNECTIONS_CATEGORY1 [RS] NUM_CONNECTIONS_CATEGORY1_VALUE [RS] NUM_CONNECTIONS_CATEGORY2 [RS] NUM_CONNECTIONS_CATEGORY2_VALUE [RS] NUM_CONNECTIONS_CATEGORYn [RS] NUM_CONNECTIONS_CATEGORYn_VALUE
    • NUM_CLIENTS_CLIENTTYPE1 [RS] NUM_CLIENTS_CLIENTTYPE1_VALUE [RS] NUM_CLIENTS_CLIENTTYPE2 [RS] NUM_CLIENTS_CLIENTTYPE2_VALUE [RS] NUM_CLIENTS_CLIENTTYPEn [RS] NUM_CLIENTS_CLIENTTYPEn_VALUE
    • NUM_CLIENTS_UPCVERSION1 [RS] NUM_CLIENTS_UPCVERSION1_VALUE [RS] NUM_CLIENTS_UPCVERSION2 [RS] NUM_CLIENTS_UPCVERSION2_VALUE [RS] NUM_CLIENTS_UPCVERSIONn [RS] NUM_CLIENTS_UPCVERSIONn_VALUE
    • gatewaynAttrName1 [RS] gatewaynAttrName1 [RS] gatewaynAttrName2 [RS] gatewaynAttrName2 [RS] gatewaynAttrNamen [RS] gatewaynAttrNamen
    • connectionsPerSecond [RS] maxConnectionsPerSecond [RS] clientsPerSecond [RS] maxClientsPerSecond
    • lifetimeRead [RS] lifetimeWritten [RS] averageRead [RS] averageWritten [RS] intervalRead [RS] intervalWritten [RS] maxIntervalRead [RS] maxIntervalWritten [RS] scheduledWrite
    		 GatewaysSnapshot

    Provides gateway statistics in response to u167.

    The list of NUM_CONNECTIONS_CATEGORYn gives the number of connections to the gateway, broken down by connection type. Connection types are determined by each gateway. For example, the built-in gateways for Adobe Flash clients include the connection types "POLICYFILE" (for Flash policy file requests) and "CLIENT" (for connections that are determined to be legitimate Union clients). For every gateway, one of the categories in the NUM_CONNECTIONS_CATEGORYn list is always guaranteed to be "TOTAL". The "TOTAL" connection category indicates the total raw number of lifetime connections to the specified gateway, including all connection types.

    The list of NUM_CLIENTS_CLIENTTYPEn gives the number of Union clients that have connected to the gateway, broken down by client type. For example, a gateway might have had 150 Reactor (Flash) client connections and 35 Orbiter (JavaScript) client connections.

    The list of NUM_CLIENTS_UPCVERSIONn gives the number of Union clients that have connected to the gateway, broken down by UPC version. For example, a gateway might have had 25 clients that used UPC version 1.4.0 and 40 clients that used UPC version 1.5.0.

    The "lifetimeRead..." argument lists the gateway's bandwidth usage. All bandwidth statistics are given in bytes. Bandwidth averages are per second. Intervals are the most recent second at the time of the request.

    Table 3: Reserved Client Attributes

    Union Server reserves the following client attributes for internal system use.
    Attribute Name Attribute Scope Attribute Description
    _CLIENT_TYPE Global The Union client type. For example, "Orbiter" or "Reactor".
    _CONNECTION_TYPE Global The type of the client's connection to the server.
    _CT Global The client's connection time in milliseconds from 1970 format.
    _GATEWAY_ID Global The ID of the server gateway to which the client is connected.
    _GATEWAY_TYPE Global The type of the server gateway to which the client is connected.
    _IP Global The client's IP address, if available.
    _ROLES Global The security roles for this client, as an integer whose bits have the following meaning when set:
    • 0 - USER: The client is logged into a user account.
    • 2 - ADMIN: The client is connected to an administration port.
    _UL Room The client's update levels for the room to which the _UL attribute is scoped. See u64.
    _UPC_VERSION Global The UPC protocol version supported by the client. For example, "1.8.2".
    _USERAGENT Global A description of the client software application being used to connect to Union. For example, "Flash Player MAC 10,1,53,38 StandAlone (debug, localTrusted); 1.0.0".

    Table 4: Reserved Account Attributes

    Union Server reserves the following account attributes for internal system use.
    Attribute Name Attribute Description
    _ROLES The security roles for this account, as an integer whose bits have the following meaning when set:
    • 1 - MODERATOR: The client is logged into a user account.

    Table 5: Reserved Room Attributes

    Union Server reserves the following room attributes for internal system use.
    Attribute Name Attribute Description
    _MAX_CLIENTS The maximum number of simultaneous occupants for the room.
    _DIE_ON_EMPTY A Boolean indicating whether the server should remove the room when it becomes empty (all its occupants leave).