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.8 by tdb, Tue Feb 27 18:45:15 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 <                                      
147 >                                      
148               <---------- {filter}       Returns a semi-colon
149                                          separated list of
150                                          FQDN hostname, UDP
# Line 153 | Line 162 | Host         (direction) Server         Comment
162                                          server that the host
163                                          has finished an will
164                                          disconnect
165 <            
165 >          
166               <---------- [OK|ERROR]     Indicates that the
167                                          server is either ok
168                                          or that it thought
169                                          there was an error
170   ------------------------------------------------------------
171 <      
171 >      
172   Host Heartbeat Protocol
173   -----------------------
174   When a host is configured after it has connected it should
# Line 177 | Line 186 | Host            (direction) Server      Comment
186   [HEARTBEAT]     ---------->             Starts the
187                                          heartbeat protocol
188                                          off
189 <                                      
189 >                                      
190                  <---------- [OK|ERROR]  Indicates that the
191                                          server is ok or not
192  
# Line 240 | Line 249 | Host            (direction) Server      Comment
249                                          server that the host
250                                          has finished an will
251                                          disconnect
252 <              
252 >              
253                  <---------- [OK|ERROR]  Indicates that the
254                                          server is either ok
255                                          or that it thought
# Line 261 | Line 270 | Client Control Protocol
270   The client control protocol channel is opened by the client
271   and allows a variety of actions to be carried out by the
272   client at anytime.  Unlike previous protocols, this is NOT
273 < sequential, all of the requests can be carried out in
273 > sequential, all of the requests can be carried out in
274   any order.
275  
276   All client protocols are backwards compatible, and the
# Line 287 | Line 296 | v1.0 - Protocol identifier: "PROTOCOL 1.0" (without qu
296   Host         (direction) Server         Comment
297   ------------------------------------------------------------
298   <initialise>
290 [CONNECT]    ---------->                Starts off the
291                                        client protocol
292            
299               <---------- [{protocol}]   The server sends the
300                                          protocol identifier
301 <                                        
301 >                                      
302   [{name}]     ---------->                The client sends its
303                                          "name".  This name
304                                          is used to identify
# Line 300 | Line 306 | Host         (direction) Server         Comment
306                                          to the system and
307                                          obtain its config
308                                          eg, Conient
309 <            
309 >            
310               <---------- [OK]           Indicates the server
311                                          is ok to proceed
312 <                        
312 >                      
313  
314   <command #1> (allows client to obtain its configuration)
315   [STARTCONFIG]---------->                Tell the server we
316                                          want to start this
317                                          command
318 <            
318 >            
319               <---------- [OK]           Indicates the server
320                                          is ok to proceed
321 <            
321 >            
322               ********** LOOP START **********
323               This loop reads configuration
324               properties from the config
# Line 323 | Line 329 | Host         (direction) Server         Comment
329                                          config file
330                                          Clients can obtain
331                                          host information
332 <                                        eg,
332 >                                        eg,
333                                          Host.UDPUpdateTime
334                                          Otherwise it must
335                                          prefix requests
# Line 331 | Line 337 | Host         (direction) Server         Comment
337                                          All other requests
338                                          will be ignored as
339                                          if it was unable to
340 <                                        retieve the property
341 <                                        
340 >                                        retrieve the
341 >                                        property
342 >                                      
343               <---------- [{value}|ERROR]Returns the value of
344                                          the requested config
345                                          property
346                                          eg, 120
347                                          If it is unable to
348 <                                        find the requested
348 >                                        find the requested
349                                          property it returns
350                                          ERROR to indicate
351                                          that fact
352 <                                        
352 >                                      
353               ********** LOOP UNTIL **********
354               The loop continues until the client
355               sends the following message
356 <            
357 < [ENDCONFIG]  ---------->                Indicates that the
356 >            
357 > [ENDCONFIG]  ---------->                Indicates that the
358                                          client requires no
359                                          more config
360 <            
360 >            
361               ********** LOOP  END **********
362               Communication continues
363 <            
363 >            
364               <---------- [OK]           Indicates that the
365                                          server is ready to
366                                          proceed
# Line 362 | Line 369 | Host         (direction) Server         Comment
369   [STARTDATA]  ---------->                Tell the server we
370                                          want to start this
371                                          command
372 <            
372 >          
373               <---------- [{portnumber}  The server then sets
374                           |ERROR]        itself listening for
375                                          a connection on its
# Line 372 | Line 379 | Host         (direction) Server         Comment
379                                          that it is listening
380                                          on eg, 12367
381                                          If the data link is
382 <                                        yet to be started
383 <                                        the server will
384 <                                        return ERROR
385 <            
386 <             <---------- [OK]           Indicates the server
387 <                                        is ok to proceed and
388 <                                        the client can
389 <                                        then connect its
383 <                                        data link
382 >                                        already started the
383 >                                        server will return
384 >                                        ERROR
385 >            
386 >             <---------- [OK]           Indicates the client
387 >                                        has successfully
388 >                                        connected to the
389 >                                        data socket.
390  
391   <command #3> (tells the server to stop the data link)
392   [STOPDATA]   ---------->                Tell the server we
393                                          want to start this
394                                          command
395                                          The server then
396 <                                        shuts down the
396 >                                        shuts down the
397                                          data link to the
398                                          client
399  
# Line 403 | Line 409 | Host         (direction) Server         Comment
409                                          client wants to
410                                          close the control
411                                          link
412 <                                        
412 >                                      
413               <---------- [OK]           The last word from
414                                          the server, it will
415 <                                        disappear after this
415 >                                        disappear after
416 >                                        this, and close the
417 >                                        data link if
418 >                                        required
419   ------------------------------------------------------------
420  
421   v1.1 - Protocol identifier: "PROTOCOL 1.1" (without quotes)
# Line 420 | Line 429 | Host         (direction) Server         Comment
429   [SETHOSTLIST]---------->                Tell the server we
430                                          want to start this
431                                          command
432 <            
432 >            
433               <---------- [OK|ERROR]     The server will
434                                          return an ERROR if
435                                          the data link is
436                                          open, as a host list
437 <                                        must ONLY be set
437 >                                        must ONLY be set
438                                          if the data link is
439                                          closed
440                                          If the server is
# Line 440 | Line 449 | Host         (direction) Server         Comment
449                                          recieve data from
450                                          eg,
451          raptor.ukc.ac.uk;killigrew.ukc.ac.uk;chalk.ukc.ac.uk
452 <                                        
452 >                                      
453                                          If the list is sent
454                                          blank (or if no list
455                                          is set at all) then
456                                          data from ALL hosts
457                                          will be sent to the
458 <                                        client
459 <                                        
458 >                                        client (this is the
459 >                                        default if no
460 >                                        SETHOSTLIST is not
461 >                                        run by the client
462 >                                      
463               <---------- [OK]           Indicates the server
464                                          is ok to proceed and
465 <                                        the host list has
465 >                                        the host list has
466                                          been accepted
467   ------------------------------------------------------------
468  
469   Client Data Protocol
470   --------------------
471   Once the data link has been opened by the control link, the
472 < server will send XML formated data packets seperated by the
473 < \n (newline) character.  For information on the format of
472 > server will send XML formatted data packets separated by the
473 > \n (newline) character.  For information on the format of
474   this data see the XML via UDP specification document at:
475  
476   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