ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/cms/documentation/specification/protocols.txt
(Generate patch)

Comparing projects/cms/documentation/specification/protocols.txt (file contents):
Revision 1.3 by ajm, Sun Jan 28 20:05:35 2001 UTC vs.
Revision 1.12 by tdb, Wed Jul 16 14:54:47 2008 UTC

# Line 12 | Line 12 | Contents
12   - Client Control Protocol
13   - Client Data Protocol
14  
15
15   Conventions
16   -----------
17   All protocols in this document assume a valid connection of
# Line 26 | Line 25 | is a variety of options they will be separated with th
25   character.  For example:
26  
27      [OK|ERROR]
28 <  
28 >  
29   Indicates that the message "OK" OR the message "ERROR" will
30   be sent depending on the result of the last action.
31  
# Line 36 | Line 35 | of data that will be returned.  For example:
35  
36      {lastmodified}
37  
38 < Indicates that data for use as 'last modified' will be
39 < returned.  
38 > Indicates that data for use as 'last modified' will be
39 > returned.  
40  
41 < If [ERROR] is sent back at any time, this indicates that all
41 > If [ERROR] is sent back at any time, this indicates that all
42   communication is over. EXCEPT where otherwise specified!
43  
45
44   Host Connection Protocol
45   ------------------------
46   The initial connection of a host to the i-scream server is
# Line 58 | Line 56 | Host         (direction) Server         Comment
56   [STARTCONFIG]---------->                Requests to start
57                                          receiving config
58                                          information
59 <            
59 >          
60               <---------- [OK|ERROR]     If the server ok's
61                                          the request or not
62  
# Line 67 | Line 65 | Host         (direction) Server         Comment
65                                          (used when checking
66                                          if the config has
67                                          changed)
68 <            
68 >          
69               <---------- [{lastmodified}Returns a long int
70                           |ERROR]        time since epoch
71                                          eg, 123456789
72 <
72 >                                        To indicate what
73 >                                        format this is in,
74 >                                        I quote from the
75 >                                        Java 1.3 JDK API
76 >                                        "measured in milli
77 >                                        -seconds since the
78 >                                        epoch"
79 >                                      
80   [FILELIST]   ---------->                Asks the server for
81                                          the list of files
82                                          that were used to
# Line 79 | Line 84 | Host         (direction) Server         Comment
84                                          (used when checking
85                                          if the config has
86                                          changed)
87 <      
87 >      
88               <---------- [{filelist}    Returns a semi-colon
89                           |ERROR]        separated list of
90                                          filenames
91                                          eg,
92                                          a.conf;b.conf;c.conf
93  
94 + [FQDN]       ---------->                Asks the server to
95 +                                        send the FQDN (fully
96 +                                        qualified domain
97 +                                        name) of the
98 +                                        connecting host.
99 +                                        
100 +             <---------- [{fqdn}        Returns the FQDN of
101 +                         |ERROR]        the connected host,
102 +                                        or error if it can't
103 +                                        be looked up.
104 +
105               ********** LOOP START **********
106               This loop reads configuration
107               properties from the config
# Line 95 | Line 111 | Host         (direction) Server         Comment
111                                          retrieved from the
112                                          config file
113                                          eg, UDPUpdateTime
114 <            
114 >          
115               <---------- [{value}|ERROR]Returns the value of
116                                          the requested config
117                                          property
# Line 104 | Line 120 | Host         (direction) Server         Comment
120                                          find the requested
121                                          property it returns
122                                          ERROR to indicate
123 <                                        that fact, but
124 <                                        communication still
123 >                                        that fact, but
124 >                                        communication still
125                                          proceeds
126 <                                      
126 >                                      
127               ********** LOOP UNTIL **********
128               The loop continues until the host
129               sends the following message
130 <            
130 >          
131   [ENDCONFIG]  ---------->                Indicates that the
132                                          host requires no
133                                          more config
134 <            
134 >          
135               ********** LOOP  END **********
136               Communication continues
137 <            
137 >          
138               <---------- [OK]           Indicates that the
139                                          server is ready to
140                                          proceed
141 <                                      
141 >                                      
142   [FILTER]     ---------->                Asks the server to
143                                          send it the host
144                                          information of a
145                                          filter that it
146                                          should connect to
147 <                                      
148 <             <---------- {filter}       Returns a semi-colon
147 >                                      
148 >             <---------- {filter}|ERROR Returns a semi-colon
149                                          separated list of
150                                          FQDN hostname, UDP
151                                          port number and TCP
# Line 141 | Line 157 | Host         (direction) Server         Comment
157                                          eg,
158                                          raptor.ukc.ac.uk;
159                                          1234;5678
160 +                                        or ERROR if none of
161 +                                        configured Filter's
162 +                                        could be found.
163  
164   [END]        ---------->                Indicates to the
165                                          server that the host
166                                          has finished an will
167                                          disconnect
168 <            
168 >          
169               <---------- [OK|ERROR]     Indicates that the
170                                          server is either ok
171                                          or that it thought
172                                          there was an error
154 <<<<<<< protocols.txt
173   ------------------------------------------------------------
174 <
157 < =======
158 <      
159 < >>>>>>> 1.2
174 >      
175   Host Heartbeat Protocol
176   -----------------------
177   When a host is configured after it has connected it should
# Line 174 | Line 189 | Host            (direction) Server      Comment
189   [HEARTBEAT]     ---------->             Starts the
190                                          heartbeat protocol
191                                          off
192 <                                      
192 >                                      
193                  <---------- [OK|ERROR]  Indicates that the
194                                          server is ok or not
195  
# Line 205 | Line 220 | Host            (direction) Server      Comment
220                                          identical to the one
221                                          received in the
222                                          connection protocol
223 +                                        To indicate what
224 +                                        format this is in,
225 +                                        I quote from the
226 +                                        Java 1.3 JDK API
227 +                                        "measured in milli
228 +                                        -seconds since the
229 +                                        epoch"
230  
231                  <---------- [OK|ERROR]  The server then
232                                          checks all the files
# Line 230 | Line 252 | Host            (direction) Server      Comment
252                                          server that the host
253                                          has finished an will
254                                          disconnect
255 <              
255 >              
256                  <---------- [OK|ERROR]  Indicates that the
257                                          server is either ok
258                                          or that it thought
# Line 243 | Line 265 | The UDP data packets that are sent by the host contain
265   simply XML data.  For information on the format of this
266   data see the XML via UDP specification document at:
267  
268 < http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specificatio
247 < n/xml_via_udp.txt
268 > http://www.i-scream.org/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt
269  
270   Client Control Protocol
271   -----------------------
# Line 252 | Line 273 | Client Control Protocol
273   The client control protocol channel is opened by the client
274   and allows a variety of actions to be carried out by the
275   client at anytime.  Unlike previous protocols, this is NOT
276 < sequential, all of the requests can be carried out in
276 > sequential, all of the requests can be carried out in
277   any order.
278  
279   All client protocols are backwards compatible, and the
# Line 278 | Line 299 | v1.0 - Protocol identifier: "PROTOCOL 1.0" (without qu
299   Host         (direction) Server         Comment
300   ------------------------------------------------------------
301   <initialise>
281 [CONNECT]    ---------->                Starts off the
282                                        client protocol
283            
302               <---------- [{protocol}]   The server sends the
303                                          protocol identifier
304 <                                        
304 >                                      
305   [{name}]     ---------->                The client sends its
306                                          "name".  This name
307                                          is used to identify
# Line 291 | Line 309 | Host         (direction) Server         Comment
309                                          to the system and
310                                          obtain its config
311                                          eg, Conient
312 <            
312 >            
313               <---------- [OK]           Indicates the server
314                                          is ok to proceed
315 <                        
315 >                      
316  
317   <command #1> (allows client to obtain its configuration)
318   [STARTCONFIG]---------->                Tell the server we
319                                          want to start this
320                                          command
321 <            
321 >            
322               <---------- [OK]           Indicates the server
323                                          is ok to proceed
324 <            
324 >            
325               ********** LOOP START **********
326               This loop reads configuration
327               properties from the config
328  
329 < [{property}] ---------->                Sends the name of a
329 > [{config};{property}] ---------->       Sends the name of a
330 >                                        configuration and
331                                          property to be
332                                          retrieved from the
333                                          config file
334                                          Clients can obtain
335                                          host information
336 <                                        eg,
336 >                                        eg,
337                                          Host.UDPUpdateTime
338                                          Otherwise it must
339                                          prefix requests
# Line 322 | Line 341 | Host         (direction) Server         Comment
341                                          All other requests
342                                          will be ignored as
343                                          if it was unable to
344 <                                        retieve the property
345 <                                        
344 >                                        retrieve the
345 >                                        property
346 >                                      
347               <---------- [{value}|ERROR]Returns the value of
348                                          the requested config
349                                          property
350                                          eg, 120
351                                          If it is unable to
352 <                                        find the requested
352 >                                        find the requested
353                                          property it returns
354                                          ERROR to indicate
355                                          that fact
356 <                                        
356 >                                      
357               ********** LOOP UNTIL **********
358               The loop continues until the client
359               sends the following message
360 <            
361 < [ENDCONFIG]  ---------->                Indicates that the
360 >            
361 > [ENDCONFIG]  ---------->                Indicates that the
362                                          client requires no
363                                          more config
364 <            
364 >            
365               ********** LOOP  END **********
366               Communication continues
367 <            
367 >            
368               <---------- [OK]           Indicates that the
369                                          server is ready to
370                                          proceed
# Line 353 | Line 373 | Host         (direction) Server         Comment
373   [STARTDATA]  ---------->                Tell the server we
374                                          want to start this
375                                          command
376 <            
376 >          
377               <---------- [{portnumber}  The server then sets
378                           |ERROR]        itself listening for
379                                          a connection on its
# Line 363 | Line 383 | Host         (direction) Server         Comment
383                                          that it is listening
384                                          on eg, 12367
385                                          If the data link is
386 <                                        yet to be started
387 <                                        the server will
388 <                                        return ERROR
389 <            
390 <             <---------- [OK]           Indicates the server
391 <                                        is ok to proceed and
392 <                                        the client can
393 <                                        then connect its
374 <                                        data link
386 >                                        already started the
387 >                                        server will return
388 >                                        ERROR
389 >            
390 >             <---------- [OK]           Indicates the client
391 >                                        has successfully
392 >                                        connected to the
393 >                                        data socket.
394  
395   <command #3> (tells the server to stop the data link)
396   [STOPDATA]   ---------->                Tell the server we
397                                          want to start this
398                                          command
399                                          The server then
400 <                                        shuts down the
400 >                                        shuts down the
401                                          data link to the
402                                          client
403  
# Line 394 | Line 413 | Host         (direction) Server         Comment
413                                          client wants to
414                                          close the control
415                                          link
416 <                                        
416 >                                      
417               <---------- [OK]           The last word from
418                                          the server, it will
419 <                                        disappear after this
419 >                                        disappear after
420 >                                        this, and close the
421 >                                        data link if
422 >                                        required
423   ------------------------------------------------------------
424  
425   v1.1 - Protocol identifier: "PROTOCOL 1.1" (without quotes)
# Line 411 | Line 433 | Host         (direction) Server         Comment
433   [SETHOSTLIST]---------->                Tell the server we
434                                          want to start this
435                                          command
436 <            
436 >            
437               <---------- [OK|ERROR]     The server will
438                                          return an ERROR if
439                                          the data link is
440                                          open, as a host list
441 <                                        must ONLY be set
441 >                                        must ONLY be set
442                                          if the data link is
443                                          closed
444                                          If the server is
# Line 431 | Line 453 | Host         (direction) Server         Comment
453                                          recieve data from
454                                          eg,
455          raptor.ukc.ac.uk;killigrew.ukc.ac.uk;chalk.ukc.ac.uk
456 <                                        
456 >                                      
457                                          If the list is sent
458                                          blank (or if no list
459                                          is set at all) then
460                                          data from ALL hosts
461                                          will be sent to the
462 <                                        client
463 <                                        
462 >                                        client (this is the
463 >                                        default if no
464 >                                        SETHOSTLIST is not
465 >                                        run by the client
466 >                                      
467               <---------- [OK]           Indicates the server
468                                          is ok to proceed and
469 <                                        the host list has
469 >                                        the host list has
470                                          been accepted
471   ------------------------------------------------------------
472  
473   Client Data Protocol
474   --------------------
475   Once the data link has been opened by the control link, the
476 < server will send XML formated data packets seperated by the
477 < \n (newline) character.  For information on the format of
476 > server will send XML formatted data packets separated by the
477 > \n (newline) character.  For information on the format of
478   this data see the XML via UDP specification document at:
479  
480 < http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specificatio
456 < n/xml_via_udp.txt
480 > http://www.i-scream.org/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt
481  
482   About
483   -----
484 < This document was written by AJ Moore [ajm4@ukc.ac.uk] for
485 < use by the team working on a 3rd year Computer Science
486 < project called "i-scream". More details can be found on the
463 < project website;
484 > This document was written by AJ Moore for use by the team working on a
485 > 3rd year Computer Science project called "i-scream". More details can
486 > be found on the project website;
487  
488 < http://www.i-scream.org.uk
488 > http://www.i-scream.org

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines