--- projects/cms/documentation/specification/protocols.txt 2001/01/28 18:50:44 1.2 +++ projects/cms/documentation/specification/protocols.txt 2001/01/29 10:03:14 1.7 @@ -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,7 +84,7 @@ Host (direction) Server Comment (used when checking if the config has changed) - + <---------- [{filelist} Returns a semi-colon |ERROR] separated list of filenames @@ -95,7 +100,7 @@ Host (direction) Server Comment retrieved from the config file eg, UDPUpdateTime - + <---------- [{value}|ERROR]Returns the value of the requested config property @@ -104,31 +109,31 @@ 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 separated list of FQDN hostname, UDP @@ -146,12 +151,13 @@ 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 there was an error - +------------------------------------------------------------ + Host Heartbeat Protocol ----------------------- When a host is configured after it has connected it should @@ -169,7 +175,7 @@ Host (direction) Server Comment [HEARTBEAT] ----------> Starts the heartbeat protocol off - + <---------- [OK|ERROR] Indicates that the server is ok or not @@ -200,6 +206,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 @@ -225,11 +238,12 @@ 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 there was an error +------------------------------------------------------------ Host Data Protocol ------------------ @@ -237,18 +251,218 @@ 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=specificatio -n/xml_via_udp.txt +http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt 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 +any order. +All client protocols are backwards compatible, and the +version is shown by the protocol identifier. + +There are three sections to this protocol. + +1) Initialise (sent only at start) +2) Send command(s) - unlimited number in any order +3) Disconnect (sent only at end) + +If at anytime the client sends something the server does +not understand, an [ERROR] will be sent + +All are indicated with <> brackets. + +v1.0 - Protocol identifier: "PROTOCOL 1.0" (without quotes) + Supported commands: + STARTCONFIG + STARTDATA + STOPDATA + +Host (direction) Server Comment +------------------------------------------------------------ + + <---------- [{protocol}] The server sends the + protocol identifier + +[{name}] ----------> The client sends its + "name". This name + is used to identify + the type of client + 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 + property to be + retrieved from the + config file + Clients can obtain + host information + eg, + Host.UDPUpdateTime + Otherwise it must + prefix requests + with "Client." + All other requests + will be ignored as + if it was unable to + retrieve the + property + + <---------- [{value}|ERROR]Returns the value of + the requested config + property + eg, 120 + If it is unable to + 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 + client requires no + more config + + ********** LOOP END ********** + Communication continues + + <---------- [OK] Indicates that the + server is ready to + proceed + + (tells the server to start the data link) +[STARTDATA] ----------> Tell the server we + want to start this + command + + <---------- [{portnumber} The server then sets + |ERROR] itself listening for + a connection on its + data link socket for + this client. It + returns the port no. + that it is listening + on eg, 12367 + If the data link is + 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 + data link to the + client + + <---------- [OK|ERROR] Returns OK is the + server is ready to + proceed, or ERROR + if the data link + was not open in the + first place + + +[DISCONNECT] ----------> Tells the server the + client wants to + close the control + link + + <---------- [OK] The last word from + the server, it will + disappear after + this, and close the + data link if + required +------------------------------------------------------------ + +v1.1 - Protocol identifier: "PROTOCOL 1.1" (without quotes) + Supported commands: + SETHOSTLIST + +Host (direction) Server Comment +------------------------------------------------------------ + (indicates to the server which hosts the client + wants data from) +[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 + if the data link is + closed + If the server is + ok to proceed with + the command it says + [OK] + +[{hostlist}] ----------> This is a semi-colon + seperated list of + FQDN hostnames that + the client wishes to + 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 (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 + been accepted +------------------------------------------------------------ + Client Data Protocol -------------------- +Once the data link has been opened by the control link, the +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 About -----