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.5 by ajm, Sun Jan 28 20:29:32 2001 UTC vs.
Revision 1.9 by tdb, Wed Mar 14 13:14:57 2001 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
# Line 78 | Line 76 | Host         (direction) Server         Comment
76                                          "measured in milli
77                                          -seconds since the
78                                          epoch"
79 <                                        
79 >                                      
80   [FILELIST]   ---------->                Asks the server for
81                                          the list of files
82                                          that were used to
# Line 86 | 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 102 | 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 111 | 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 148 | 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
173   ------------------------------------------------------------
174 <      
174 >      
175   Host Heartbeat Protocol
176   -----------------------
177   When a host is configured after it has connected it should
# Line 177 | 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 240 | 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 261 | 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 287 | Line 299 | v1.0 - Protocol identifier: "PROTOCOL 1.0" (without qu
299   Host         (direction) Server         Comment
300   ------------------------------------------------------------
301   <initialise>
290 [CONNECT]    ---------->                Starts off the
291                                        client protocol
292            
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 300 | 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
# Line 323 | Line 332 | Host         (direction) Server         Comment
332                                          config file
333                                          Clients can obtain
334                                          host information
335 <                                        eg,
335 >                                        eg,
336                                          Host.UDPUpdateTime
337                                          Otherwise it must
338                                          prefix requests
# Line 331 | Line 340 | Host         (direction) Server         Comment
340                                          All other requests
341                                          will be ignored as
342                                          if it was unable to
343 <                                        retieve the property
344 <                                        
343 >                                        retrieve the
344 >                                        property
345 >                                      
346               <---------- [{value}|ERROR]Returns the value of
347                                          the requested config
348                                          property
349                                          eg, 120
350                                          If it is unable to
351 <                                        find the requested
351 >                                        find the requested
352                                          property it returns
353                                          ERROR to indicate
354                                          that fact
355 <                                        
355 >                                      
356               ********** LOOP UNTIL **********
357               The loop continues until the client
358               sends the following message
359 <            
360 < [ENDCONFIG]  ---------->                Indicates that the
359 >            
360 > [ENDCONFIG]  ---------->                Indicates that the
361                                          client requires no
362                                          more config
363 <            
363 >            
364               ********** LOOP  END **********
365               Communication continues
366 <            
366 >            
367               <---------- [OK]           Indicates that the
368                                          server is ready to
369                                          proceed
# Line 362 | Line 372 | Host         (direction) Server         Comment
372   [STARTDATA]  ---------->                Tell the server we
373                                          want to start this
374                                          command
375 <            
375 >          
376               <---------- [{portnumber}  The server then sets
377                           |ERROR]        itself listening for
378                                          a connection on its
# Line 372 | Line 382 | Host         (direction) Server         Comment
382                                          that it is listening
383                                          on eg, 12367
384                                          If the data link is
385 <                                        yet to be started
386 <                                        the server will
387 <                                        return ERROR
388 <            
389 <             <---------- [OK]           Indicates the server
390 <                                        is ok to proceed and
391 <                                        the client can
392 <                                        then connect its
383 <                                        data link
385 >                                        already started the
386 >                                        server will return
387 >                                        ERROR
388 >            
389 >             <---------- [OK]           Indicates the client
390 >                                        has successfully
391 >                                        connected to the
392 >                                        data socket.
393  
394   <command #3> (tells the server to stop the data link)
395   [STOPDATA]   ---------->                Tell the server we
396                                          want to start this
397                                          command
398                                          The server then
399 <                                        shuts down the
399 >                                        shuts down the
400                                          data link to the
401                                          client
402  
# Line 403 | Line 412 | Host         (direction) Server         Comment
412                                          client wants to
413                                          close the control
414                                          link
415 <                                        
415 >                                      
416               <---------- [OK]           The last word from
417                                          the server, it will
418 <                                        disappear after this
418 >                                        disappear after
419 >                                        this, and close the
420 >                                        data link if
421 >                                        required
422   ------------------------------------------------------------
423  
424   v1.1 - Protocol identifier: "PROTOCOL 1.1" (without quotes)
# Line 420 | Line 432 | Host         (direction) Server         Comment
432   [SETHOSTLIST]---------->                Tell the server we
433                                          want to start this
434                                          command
435 <            
435 >            
436               <---------- [OK|ERROR]     The server will
437                                          return an ERROR if
438                                          the data link is
439                                          open, as a host list
440 <                                        must ONLY be set
440 >                                        must ONLY be set
441                                          if the data link is
442                                          closed
443                                          If the server is
# Line 440 | Line 452 | Host         (direction) Server         Comment
452                                          recieve data from
453                                          eg,
454          raptor.ukc.ac.uk;killigrew.ukc.ac.uk;chalk.ukc.ac.uk
455 <                                        
455 >                                      
456                                          If the list is sent
457                                          blank (or if no list
458                                          is set at all) then
459                                          data from ALL hosts
460                                          will be sent to the
461 <                                        client
462 <                                        
461 >                                        client (this is the
462 >                                        default if no
463 >                                        SETHOSTLIST is not
464 >                                        run by the client
465 >                                      
466               <---------- [OK]           Indicates the server
467                                          is ok to proceed and
468 <                                        the host list has
468 >                                        the host list has
469                                          been accepted
470   ------------------------------------------------------------
471  
472   Client Data Protocol
473   --------------------
474   Once the data link has been opened by the control link, the
475 < server will send XML formated data packets seperated by the
476 < \n (newline) character.  For information on the format of
475 > server will send XML formatted data packets separated by the
476 > \n (newline) character.  For information on the format of
477   this data see the XML via UDP specification document at:
478  
479   http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specification/xml_via_udp.txt

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines