--- projects/cms/documentation/specification/protocols.txt 2001/01/28 18:35:31 1.1 +++ projects/cms/documentation/specification/protocols.txt 2001/01/28 18:50:44 1.2 @@ -12,20 +12,21 @@ Contents - Client Control Protocol - Client Data Protocol + Conventions ----------- All protocols in this document assume a valid connection of the appropriate type has been made, and that data streams -already available. All strings should and will be +are already available. All strings should, and will be, terminated with a \n (newline character) to indicate the end of the message. All messages are sent as ASCII Strings. Fixed protocol messages will appear in [] brackets, if there -is a variety of options they will be seperated with the | +is a variety of options they will be separated with the | 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. @@ -35,20 +36,21 @@ of data that will be returned. For example: {lastmodified} -Indicates that data indicating for use as last modified will -be returned. +Indicates that data for use as 'last modified' will be +returned. -If ever [ERROR] is sent back at any time, this indicates -that all communication is over. EXCEPT where specified! +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 through the FilterManager. A Host gets its configuration -and then gets assigned a filter to connect to and start +and then gets assigned a Filter to connect to and start sending data. -The port number of the filter manager is fully configurable, +The port number of the FilterManager is fully configurable, however the default at this time is 4567. Host (direction) Server Comment @@ -56,18 +58,18 @@ Host (direction) Server Comment [STARTCONFIG]----------> Requests to start receiving config information - + <---------- [OK|ERROR] If the server ok's the request or not [LASTMODIFIED]----------> Asks when the config was last modified (used when checking - if the config has + if the config has changed) - + <---------- [{lastmodified}Returns a long int - |ERROR] time since epoc + |ERROR] time since epoch eg, 123456789 [FILELIST] ----------> Asks the server for @@ -77,9 +79,9 @@ Host (direction) Server Comment (used when checking if the config has changed) - + <---------- [{filelist} Returns a semi-colon - |ERROR] seperated list of + |ERROR] separated list of filenames eg, a.conf;b.conf;c.conf @@ -93,46 +95,48 @@ Host (direction) Server Comment retrieved from the config file eg, UDPUpdateTime - + <---------- [{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 - + that fact, but + communication still + proceeds + ********** LOOP UNTIL ********** The loop continues until the host sends the following message - -[ENDCONFIG] ----------> Indicates that the + +[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 + information of a filter that it should connect to - + <---------- {filter} Returns a semi-colon - seperated list of + separated list of FQDN hostname, UDP port number and TCP - port number that a + port number that a configured Filter is running on and - assigned to the + assigned to the calling host eg, raptor.ukc.ac.uk; @@ -142,20 +146,20 @@ 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 obtain a property TCPUpdateTime. This indicates how often -a host should send a "Heart Beat" which is a pro-active +a host should send a "Heart Beat", which is a pro-active connection to the server by the host to indicate that it is still alive. This "Heart Beat" also allows a host to see -its configuration has changed and act accordingly. In a +its configuration has changed and act accordingly. In a well written host this should just be a case of dropping out of a loop and heading back to the start (connecting to the filter manager). @@ -165,7 +169,7 @@ Host (direction) Server Comment [HEARTBEAT] ----------> Starts the heartbeat protocol off - + <---------- [OK|ERROR] Indicates that the server is ok or not @@ -177,24 +181,24 @@ Host (direction) Server Comment server is ok or not [{filelist}] ----------> Send a semi-colon - seperated list of + separated list of filenames eg, a.conf;b.conf;c.conf This should be identical to the one - recieved in the + received in the connection protocol <---------- [OK] Indicates that the server is ok [{lastmodified}]----------> Returns a long int - time since epoc + time since epoch eg, 123456789 This should be identical to the one - recieved in the + received in the connection protocol <---------- [OK|ERROR] The server then @@ -203,8 +207,8 @@ Host (direction) Server Comment see if they have been modified more recently than the - lastmodified value - if they HAVE that + lastmodified value. + If they HAVE that indicates that the configuration has changed and the host @@ -221,7 +225,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 @@ -233,7 +237,8 @@ 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.uk/cgi-bin/docs.cgi?doc=specificatio +n/xml_via_udp.txt Client Control Protocol -----------------------