A simple MFString Based Multi-User Protocol ------------------------------------------- Multi-user capabilities are added to the browser by use of a native script in a script node. The VRML scene interacts with the script node my sending MFString eventIn network request to the script and receiving the answer as MFString eventOut values. A: Event Interface of the Network Script ---------------------------------------- 1. field MFString serverUrl for setting the address of the server to be contacted by the script. TBD: should this be replaced by a eventIn MFString? Eg: field MFString serverUrl [ "udp://localhost:3000", "tcp://localhost:3000", "http://localhost:80/cgi-bin/httptunnel" ] Note: Depending of the implementation of the native script node and the server, different protocols might be use. 2. eventIn MFString send for setting the actual request to be sent over the network. Eg: field MFString buffer [] buffer[ 0 ] = '1'; buffer[ 1 ] = 'PING'; send = buffer; 4. eventIn SFTime timer for polling the network periodically in order to received packets from the server Eg: DEF POLLBEAT TimeSensor { cycleInterval 0.1 loop TRUE } ROUTE POLLBEAT.cycleTime TO NET.timer 5. eventOut MFString receive for receiving the answers from the network. 6. other optional eventOuts for TRACES and ERROR messages can be defined. B: Events that can be sent to the eventIn send ---------------------------------------------- General Event Format: - More than one network request can be set in one send or receive event. In order to make this possible the first string of each event has to be the number of strings following for the single request. The number of strings has to be given as a decimal number string. Eg: buffer[ 0 ] = '1'; // one string argument will follow buffer[ 1 ] = 'PING'; // the single argument buffer[ 2 ] = '1'; // starts another request with one argument buffer[ 3 ] = 'PING'; // the argument of the second request send = buffer; - All values sent to and received from the server are given as argumentname / argument value pairs. argument names can be arbitrary words, the following rules apply. 1. Reserved argument names are all in UPPER case, future protocol enhancements might need more names. The currently reserved argument names are: NNM, PWD, SCN, SCU, VER, CLID, SCID, NPP, NSN, UID, PEID, CHID, AVU, POS, ORI, TXT 2. Application defined argument names should be short, as they are transfered over the network frequently. Use of short 3 letter tags is recommended, e.g. use 'Col' instead of 'Colorvalue' for color value. 3. Changes of arguments who's names start with an uppercase character are forwarded immediately by the server to all other clients in the same scene. Arguments with a lowercase first character are only stored at the server for explicit retrieval by peer clients. Eg: SET Col 1,0,0 Set the attribute called "Col" and have the server forward the value immediately. SET choice red Set the attribute called "choice", the other users have to retrieve the value in order to find out. 1. PING request This is a generic request, that can be sent at any time to find out whether the server is reachable. The server answers with a PONG request. Syntax: PING Eg: field MFString buffer [] buffer[ 0 ] = '1'; buffer[ 1 ] = 'PING'; send = buffer; 2. ENTER request This request is used in order to enter a specific VRML scene at the server. User specific attributes can also be set with the request. Syntax: ENTER NNM SCU VER AVU UID PWD SCN POS ORI arg1 val1 ... argn valn NNM: The nickname to be used by the client, required SCU: The url of the vrml file of the scene to enter, required SCN: Display name of the scene to enter, optional VER: The protocol version the client understands, required, send '1' for now AVU: The url of the avatar to be used by the client, optional POS: The postion of the avatar, optional Positions are sent as comma seperated triples of floats precision is 0.001 units. Trailing 0s can be ommitted. Eg: 1.0,1.6,0.0 ORI: The orientation of the avatar used by the client, optional Orientations are set as comma seperated quadruples of floats precision is 0.001 units. Trailing 0s can be ommitted. Eg: 0.000,1.000,0.000,1.570 UID: User id of the client, might be required for log in TXT: A text to be sent for the user PWD: Password, might be required for log in arg1 val1 ... argn valn: Optional additional attributes to be set for the client. Eg: 'Tit' 'Grandmaster' 'int' 'Chess and checkers' Set some attribute called 'Tit' which is to be forwarded by the server and some other attribute called 'int' only to be stored at the server. 3. SET request This request is used in to set attributes of the user or the scene at the server. Syntax: SET [CLID,SCID] [clid/scid] PEID peid arg1 val1 ... argn valn CLID clid: The client id of the client, returned by the server in the HI answer. SCID scid: Scene id of the scene the client is in, returned by the server in the HI answer. PEID peid: a client ID of a peer the data is to be forwarded to if this parameter is set, only the peers who's IDs are listed are informed about the update. arg1 val1 ... argn valn: Attributes to be set for the client or the scene. Eg: SET TXT 'Hello, how are you?' - client sends a text SET POS '21,1.6,12' ORI '0,1,0,0' - client sends a position 4. GET request This request is used in to query attributes of users or the scene from the server. Syntax: GET [CLID,SCID] [clid/scid] arg1 ... argn CLID: The client id of the peer client the values are to be retrieved for, sent by the server in the ENTER forward. SCID: Scene id of the scene the client is in, returned by the server in the HI answer. arg1 ... argn: Attributes to be queried of the client or the scene. Eg: int col 5. LST request This request is used in to list attributes of the users of the scene. Syntax: LST arg1 ... argn arg1 ... argn: Attributes to be queried of the clients. Eg: AVU POS ORI NNM list avatarurl, position, orientation and NNM of all users in the scene. 6. SCL request This request is used in to list attributes of the scenes. Syntax: SCL SCN SCU NPP NSN SCN: scene name of the scene SCU: scene url of the scene NPP: Number of people in the scene NSN: Total number of scenes known at the server 7. BYE request This request is used when a client leaves a scene. Syntax: BYE CLID clid C: Events that have to be expected at the eventOut receive ---------------------------------------------------------- 1. BAD event This event is sent when an error occures Syntax: BAD arg .... The following error arguments are defined at the moment. CLID clid: a client an attribute was requested for does not exist anymore. SCID scid: a scene an attribute was requested for does not exist anymore. CID cid: the connection ID of the client is bad, the client has to reconnect!!!! ?: the client sent some data the server did not understand SIZEOVERFLOW RESULT: the resulting answer can not be sent in one request 2. HI event Sent by the server as an answer to the ENTER request Syntax: HI CLID clid SCID scid VER ver SCN NPP NSN CHID chid CLID clid: the client ID of the client, to be used in subsequent SET and GET requests and the BYE request. SCID scid: the scene ID of the scene, to be used in subsequent SET and GET requests of scene attributes. VER ver: protocol version of the server SCN : Display name of the scene. NPP : Number of people in the scene, a decimal string CHID chid: Change counter of the scene, used to detect old events that are out of date. NSN : Number of scenes, a decimal string 3. ENTER event This event is sent by the server when a new peer enters the scene. Syntax: ENTER CLID clid NNM VER ver NPP n NSN n CHID chid arg1 val1 ... argn valn CLID clid: the client ID of the new client NNM : Nickname of new client VER ver: protocol version of the new client NPP : Number of people in the scene, a decimal string NSN : Number of scenes, a decimal string CHID chid: Change counter of the scene, used to detect old events that are out of date. NPP and NSN are not valid anymore if an event with a higher chid has been received for the scene already arg1 val1 ... argn valn: List of attributes and values the client set in it's ENTER request 4. SET event: Sent by the server when an attribute of a peer or the scene has been changed, or as an answer to a LST or SCL request. Syntax: SET [CLID,SCID] [clid/scid] CHID chid arg1 val1 ... argn valn CLID: The client id of the client who's attributes are updated. SCID: The scene id of the scene who's attributes are updated. CHID: Change counter of the client, used to detect old events that are out of date. Attributes set are out of date if an event with a higher chid has been received for the client already However, some attributes, like TXT do not use this logic. arg1 val1 ... argn valn: List of attributes and values updated. 5. BYE event Forwarded when a client is leaving the scene Syntax: BYE CLID clid 6. PONG event Reply of the server to a PING request. Syntax: PONG 7. PING event Sent by the server in order to request a PING answer. Syntax: PING 8. OK Sent from the server as answer to SET request that went ok. Syntax: OK