--- projects/cms/documentation/specification/protocols.txt 2001/01/28 20:16:19 1.4 +++ projects/cms/documentation/specification/protocols.txt 2004/08/01 10:39:55 1.11 @@ -12,7 +12,6 @@ Contents - Client Control Protocol - Client Data Protocol - Conventions ----------- All protocols in this document assume a valid connection of @@ -26,7 +25,7 @@ is a variety of options they will be separated with th character. For example: [OK|ERROR] - + Indicates that the message "OK" OR the message "ERROR" will be sent depending on the result of the last action. @@ -36,13 +35,12 @@ of data that will be returned. For example: {lastmodified} -Indicates that data for use as 'last modified' will be -returned. +Indicates that data for use as 'last modified' will be +returned. -If [ERROR] is sent back at any time, this indicates that all +If [ERROR] is sent back at any time, this indicates that all communication is over. EXCEPT where otherwise specified! - Host Connection Protocol ------------------------ The initial connection of a host to the i-scream server is @@ -58,7 +56,7 @@ Host (direction) Server Comment [STARTCONFIG]----------> Requests to start receiving config information - + <---------- [OK|ERROR] If the server ok's the request or not @@ -67,11 +65,18 @@ Host (direction) Server Comment (used when checking if the config has changed) - + <---------- [{lastmodified}Returns a long int |ERROR] time since epoch eg, 123456789 - + To indicate what + format this is in, + I quote from the + Java 1.3 JDK API + "measured in milli + -seconds since the + epoch" + [FILELIST] ----------> Asks the server for the list of files that were used to @@ -79,13 +84,24 @@ Host (direction) Server Comment (used when checking if the config has changed) - + <---------- [{filelist} Returns a semi-colon |ERROR] separated list of filenames eg, a.conf;b.conf;c.conf +[FQDN] ----------> Asks the server to + send the FQDN (fully + qualified domain + name) of the + connecting host. + + <---------- [{fqdn} Returns the FQDN of + |ERROR] the connected host, + or error if it can't + be looked up. + ********** LOOP START ********** This loop reads configuration properties from the config @@ -95,7 +111,7 @@ Host (direction) Server Comment retrieved from the config file eg, UDPUpdateTime - + <---------- [{value}|ERROR]Returns the value of the requested config property @@ -104,32 +120,32 @@ Host (direction) Server Comment find the requested property it returns ERROR to indicate - that fact, but - communication still + that fact, but + communication still proceeds - + ********** LOOP UNTIL ********** The loop continues until the host sends the following message - + [ENDCONFIG] ----------> Indicates that the host requires no more config - + ********** LOOP END ********** Communication continues - + <---------- [OK] Indicates that the server is ready to proceed - + [FILTER] ----------> Asks the server to send it the host information of a filter that it should connect to - - <---------- {filter} Returns a semi-colon + + <---------- {filter}|ERROR Returns a semi-colon separated list of FQDN hostname, UDP port number and TCP @@ -141,22 +157,21 @@ Host (direction) Server Comment eg, raptor.ukc.ac.uk; 1234;5678 + or ERROR if none of + configured Filter's + could be found. [END] ----------> Indicates to the server that the host has finished an will disconnect - + <---------- [OK|ERROR] Indicates that the server is either ok or that it thought there was an error -<<<<<<< protocols.txt ------------------------------------------------------------ - -======= - ->>>>>>> 1.2 + Host Heartbeat Protocol ----------------------- When a host is configured after it has connected it should @@ -174,7 +189,7 @@ Host (direction) Server Comment [HEARTBEAT] ----------> Starts the heartbeat protocol off - + <---------- [OK|ERROR] Indicates that the server is ok or not @@ -205,6 +220,13 @@ Host (direction) Server Comment identical to the one received in the connection protocol + To indicate what + format this is in, + I quote from the + Java 1.3 JDK API + "measured in milli + -seconds since the + epoch" <---------- [OK|ERROR] The server then checks all the files @@ -230,7 +252,7 @@ Host (direction) Server Comment server that the host has finished an will disconnect - + <---------- [OK|ERROR] Indicates that the server is either ok or that it thought @@ -243,7 +265,7 @@ The UDP data packets that are sent by the host contain simply XML data. For information on the format of this data see the XML via UDP specification document at: -http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt +http://www.i-scream.org/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt Client Control Protocol ----------------------- @@ -251,7 +273,7 @@ Client Control Protocol The client control protocol channel is opened by the client and allows a variety of actions to be carried out by the client at anytime. Unlike previous protocols, this is NOT -sequential, all of the requests can be carried out in +sequential, all of the requests can be carried out in any order. All client protocols are backwards compatible, and the @@ -277,12 +299,9 @@ v1.0 - Protocol identifier: "PROTOCOL 1.0" (without qu Host (direction) Server Comment ------------------------------------------------------------ -[CONNECT] ----------> Starts off the - client protocol - <---------- [{protocol}] The server sends the protocol identifier - + [{name}] ----------> The client sends its "name". This name is used to identify @@ -290,30 +309,31 @@ Host (direction) Server Comment to the system and obtain its config eg, Conient - + <---------- [OK] Indicates the server is ok to proceed - + (allows client to obtain its configuration) [STARTCONFIG]----------> Tell the server we want to start this command - + <---------- [OK] Indicates the server is ok to proceed - + ********** LOOP START ********** This loop reads configuration properties from the config -[{property}] ----------> Sends the name of a +[{config};{property}] ----------> Sends the name of a + configuration and property to be retrieved from the config file Clients can obtain host information - eg, + eg, Host.UDPUpdateTime Otherwise it must prefix requests @@ -321,29 +341,30 @@ Host (direction) Server Comment All other requests will be ignored as if it was unable to - retieve the property - + retrieve the + property + <---------- [{value}|ERROR]Returns the value of the requested config property eg, 120 If it is unable to - find the requested + find the requested property it returns ERROR to indicate that fact - + ********** LOOP UNTIL ********** The loop continues until the client sends the following message - -[ENDCONFIG] ----------> Indicates that the + +[ENDCONFIG] ----------> Indicates that the client requires no more config - + ********** LOOP END ********** Communication continues - + <---------- [OK] Indicates that the server is ready to proceed @@ -352,7 +373,7 @@ Host (direction) Server Comment [STARTDATA] ----------> Tell the server we want to start this command - + <---------- [{portnumber} The server then sets |ERROR] itself listening for a connection on its @@ -362,22 +383,21 @@ Host (direction) Server Comment that it is listening on eg, 12367 If the data link is - yet to be started - the server will - return ERROR - - <---------- [OK] Indicates the server - is ok to proceed and - the client can - then connect its - data link + already started the + server will return + ERROR + + <---------- [OK] Indicates the client + has successfully + connected to the + data socket. (tells the server to stop the data link) [STOPDATA] ----------> Tell the server we want to start this command The server then - shuts down the + shuts down the data link to the client @@ -393,10 +413,13 @@ Host (direction) Server Comment client wants to close the control link - + <---------- [OK] The last word from the server, it will - disappear after this + disappear after + this, and close the + data link if + required ------------------------------------------------------------ v1.1 - Protocol identifier: "PROTOCOL 1.1" (without quotes) @@ -410,12 +433,12 @@ Host (direction) Server Comment [SETHOSTLIST]----------> Tell the server we want to start this command - + <---------- [OK|ERROR] The server will return an ERROR if the data link is open, as a host list - must ONLY be set + must ONLY be set if the data link is closed If the server is @@ -430,34 +453,37 @@ Host (direction) Server Comment recieve data from eg, raptor.ukc.ac.uk;killigrew.ukc.ac.uk;chalk.ukc.ac.uk - + If the list is sent blank (or if no list is set at all) then data from ALL hosts will be sent to the - client - + client (this is the + default if no + SETHOSTLIST is not + run by the client + <---------- [OK] Indicates the server is ok to proceed and - the host list has + the host list has been accepted ------------------------------------------------------------ Client Data Protocol -------------------- Once the data link has been opened by the control link, the -server will send XML formated data packets seperated by the -\n (newline) character. For information on the format of +server will send XML formatted data packets separated by the +\n (newline) character. For information on the format of this data see the XML via UDP specification document at: -http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt +http://www.i-scream.org/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt About ----- -This document was written by AJ Moore [ajm4@ukc.ac.uk] for +This document was written by AJ Moore [ajm@i-scream.org] for use by the team working on a 3rd year Computer Science project called "i-scream". More details can be found on the project website; -http://www.i-scream.org.uk +http://www.i-scream.org