TechNote (Archived)

Shockwave Multiuser protocol description

This document describes the binary protocol used between the Shockwave Multiuser Server and Xtra.

Note:The content of this TechNote is for advanced developers who wish to communicate with the Shockwave Multiuser Xtra. Any issues that may arise using this information will not be supported by Macromedia Technical Support.

Basics
When the multiuser xtra connects to the multiuser server, it first establishes the TCP/IP connection. When that succeeds, the client and server exchange messages to let the server authenticate the logon and send back a reply.

If the client and server are configured for UDP, there is additional information set to the server in the logon packet, and an additional packet sent from the server to the client with UDP addressing information.

Data sent between client and server can consist of multiple TCP/IP blocks. All data is sent in network (not Intel) byte order.

Message Structure
Messages passed between the client and server, or between peer clients, all have the same format:

Element	Size in bytes	Description
Header tag	2	"r" plus a null byte
Message Size	4	Full message byte size
Error code	4	Integer error code
Time stamp	4	Integer millisecond time stamp of when the server handled the message
Subject string	variable	Message subject string
Sender ID	variable	Message sender's user ID string
Recipient String List	variable	List of recipients
Contents	variable	Message content value

All integers (such as the error code and time stamp) are 32 bits, stored in network (not Intel) format.

The <subject string>, <sender ID>, and strings in general, are encoded as:

<data size>	4 bytes for string length
<string data>	N bytes of string data, not null terminated, but padded to an even byte boundary

The <recipient string list>, and other string lists, are encoded as:

<number of strings>	4 bytes with number of strings in the list
<string data>	N strings

For both sending and recieving, the <content> section is a binary stream that is one encoded lingo value. This value, however, may be a list, prop list, etc. that contains several values. The values are encoded differently depending on their types, but each value begins with a tag for the value type. Variable byte length sections are padded to even byte boundaries.

Value Encoding
Lingo values are encoded with a two byte type identifier followed by different types of data. The type identifier is in network byte order. The following table shows the type and data used:

Type C++ identifier (mmtypes.h)	Value	Data
kMoaMmValueType_Void	0	No encoded data or additional bytes
kMoaMmValueType_Integer	1	4 bytes in network (not Intel) order
kMoaMmValueType_Symbol	2	4 bytes with string length, then N bytes of string data, not null terminated,but padded to an even byte boundary
kMoaMmValueType_String	3	4 bytes with string length, then N bytes of string data, not null terminated,but padded to an even byte boundary
kMoaMmValueType_Picture	5	4 bytes with data length, then N bytes of binary picture data, padded to an even byte boundary
kMoaMmValueType_Float	6	8 bytes in network (not Intel) order
kMoaMmValueType_List	7	4 bytes with the number of elements in the list, then N values
kMoaMmValueType_Point	8	2 numeric values, each may be either an integer or float. First is X, then Y
kMoaMmValueType_Rect	9	4 numeric values, each may be either an integer or float. First is top, left, bottom, then right
kMoaMmValueType_PropList	10	4 bytes with the number of elements in the list, then N pairs of values. The first of each pair is a symbol, then the corresponding value
kMoaMmValueType_Color	18	4 bytes of binary data
kMoaMmValueType_Date	19	16 bytes of binary data
kMoaMmValueType_Media	20	4 bytes with the data length, then N bytes of binary media data, padded to an even byte boundary
kMoaMmValueType_3dVector	22	3 floats (8 bytes each, 24 total) in network order
kMoaMmValueType_3dTransform	23	16 floats (8 bytes each, 128 total) in network order

Logon sequence
The logon sequence is a special exchange between the client and server (or peer host) to establish the connection. After the TCP/IP connection has been accepted, the client sends a message to the server. The server then sends a reply back to the client. After this message is received from the server, the client xtra sends a"ConnectToNetServer" message to Lingo.

The logon message sent to the server can be in two different formats. The first was used by the original multiuser xtra, while the second was developed as more features were added in a later version.

The content portion of the logon packet will be encoded. See theEncryption section below.

Message Structure
If the client and server are set up for UDP traffic, and the user's logon is accepted, the server will send a message to the client with information about server's UDP configuration. This message tells the client where to send UDP packets. This message is sent before the server confirms the logon has succeeded. The client xtra processes this message; it is never seen by the Lingo programmer.

This message contains:

Message component	Data
errorCode	0
subject string	Will be"udp"
content	Contains a list with two strings

Content List Item	Data
First item	A string with the UDP address and port that the client sends UDP packets to. Something like "123.45.67.89:1743"
Second item	UDP cookie - a string representation of an integer that the client sends with each UDP packet

Logon Reply
The server or peer host will reply to a logon message with a message containing the following information:

Message component	Description
errorCode	Contains the result of the logon request, 0 for no error
subject string	Will be"Logon"
recipient string list	Will be the user's ID
content	Will be a single string containing the movie name

When the client xtra receives this packet, it sends a"ConnectToNetServer" message back to the Lingo script indicating the connection attempt has finished.

Token-based Logons
Token-based logon support is a minor tweak to the logon sequence that was added for version 1.0.2. This is to support token-based indentification when switching between movies.

The token is supplied to the Director movie via an HTML embed tag. The movie then does the logon (calls ConnectToNetServer()) with a userID of "#token" (a string) and the password as a string containing the token. This is passed without alteration to the server.

The server will reply to the logon, but the xtra will change its userID to the recipient of the incoming message if it did a token-based logon. Thus the server informs the xtra of it's real user name. The movie author must also recognize the user name from the recipient of the "ConnectToNetServer" reply message.

The token-based logon sequence does not change the protocol or the logon sequence, except that xtra and movie switch their userID to match the server's reply in the logon sequence.

Message Encryption
The logon packet sent from the client to the server contains the contents encrypted. The data is encrypted using the Blowfish algorithm, with a default key of "IPAddress resolution".

If the special encryption key "#NoEncryption" is used, the logon packet will not be encrypted.

If the encryption key specified by the user starts with "#All", all packets will be encrypted. In this case, the key will be the key supplied by the user with the "#All" prefix removed.

If the user supplies an encryption key less than 20 bytes long, the user's key is appended with the string "IPAddress resolution" and used as the full Blowfish key.

UDP Messages
UDP messages have the same structure as TCP/IP messages.

When the client sends a UDP packet to the server, it must be sent using the address and port that was exchanged with the server during the logon process. The client must also put the "UDP cookie" into the timestamp slot of the message. This cookie was also sent from the server to the client during the logon exchange.