ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/cms/documentation/specification/protocols.txt
Revision: 1.2
Committed: Sun Jan 28 18:50:44 2001 UTC (23 years, 9 months ago) by tdb
Content type: text/plain
Branch: MAIN
Changes since 1.1: +47 -42 lines
Log Message: 
Proof read. Just corrected a few spelling mistakes.

File Contents

# Content
1 i-scream Protocols
2 ==================
3
4 Contents
5 --------
6 - Conventions
7
8 - Host Connection Protocol
9 - Host Heartbeat Protocol
10 - Host Data Protocol
11
12 - Client Control Protocol
13 - Client Data Protocol
14
15
16 Conventions
17 -----------
18 All protocols in this document assume a valid connection of
19 the appropriate type has been made, and that data streams
20 are already available. All strings should, and will be,
21 terminated with a \n (newline character) to indicate the end
22 of the message. All messages are sent as ASCII Strings.
23
24 Fixed protocol messages will appear in [] brackets, if there
25 is a variety of options they will be separated with the |
26 character. For example:
27
28 [OK|ERROR]
29
30 Indicates that the message "OK" OR the message "ERROR" will
31 be sent depending on the result of the last action.
32
33 Data messages will appear in {} brackets, where the name in
34 the brackets indicates the type (as in kind, not data type)
35 of data that will be returned. For example:
36
37 {lastmodified}
38
39 Indicates that data for use as 'last modified' will be
40 returned.
41
42 If [ERROR] is sent back at any time, this indicates that all
43 communication is over. EXCEPT where otherwise specified!
44
45
46 Host Connection Protocol
47 ------------------------
48 The initial connection of a host to the i-scream server is
49 through the FilterManager. A Host gets its configuration
50 and then gets assigned a Filter to connect to and start
51 sending data.
52
53 The port number of the FilterManager is fully configurable,
54 however the default at this time is 4567.
55
56 Host (direction) Server Comment
57 ------------------------------------------------------------
58 [STARTCONFIG]----------> Requests to start
59 receiving config
60 information
61
62 <---------- [OK|ERROR] If the server ok's
63 the request or not
64
65 [LASTMODIFIED]----------> Asks when the config
66 was last modified
67 (used when checking
68 if the config has
69 changed)
70
71 <---------- [{lastmodified}Returns a long int
72 |ERROR] time since epoch
73 eg, 123456789
74
75 [FILELIST] ----------> Asks the server for
76 the list of files
77 that were used to
78 build the config
79 (used when checking
80 if the config has
81 changed)
82
83 <---------- [{filelist} Returns a semi-colon
84 |ERROR] separated list of
85 filenames
86 eg,
87 a.conf;b.conf;c.conf
88
89 ********** LOOP START **********
90 This loop reads configuration
91 properties from the config
92
93 [{property}] ----------> Sends the name of a
94 property to be
95 retrieved from the
96 config file
97 eg, UDPUpdateTime
98
99 <---------- [{value}|ERROR]Returns the value of
100 the requested config
101 property
102 eg, 120
103 If it is unable to
104 find the requested
105 property it returns
106 ERROR to indicate
107 that fact, but
108 communication still
109 proceeds
110
111 ********** LOOP UNTIL **********
112 The loop continues until the host
113 sends the following message
114
115 [ENDCONFIG] ----------> Indicates that the
116 host requires no
117 more config
118
119 ********** LOOP END **********
120 Communication continues
121
122 <---------- [OK] Indicates that the
123 server is ready to
124 proceed
125
126 [FILTER] ----------> Asks the server to
127 send it the host
128 information of a
129 filter that it
130 should connect to
131
132 <---------- {filter} Returns a semi-colon
133 separated list of
134 FQDN hostname, UDP
135 port number and TCP
136 port number that a
137 configured Filter is
138 running on and
139 assigned to the
140 calling host
141 eg,
142 raptor.ukc.ac.uk;
143 1234;5678
144
145 [END] ----------> Indicates to the
146 server that the host
147 has finished an will
148 disconnect
149
150 <---------- [OK|ERROR] Indicates that the
151 server is either ok
152 or that it thought
153 there was an error
154
155 Host Heartbeat Protocol
156 -----------------------
157 When a host is configured after it has connected it should
158 obtain a property TCPUpdateTime. This indicates how often
159 a host should send a "Heart Beat", which is a pro-active
160 connection to the server by the host to indicate that it is
161 still alive. This "Heart Beat" also allows a host to see
162 its configuration has changed and act accordingly. In a
163 well written host this should just be a case of dropping out
164 of a loop and heading back to the start (connecting to the
165 filter manager).
166
167 Host (direction) Server Comment
168 ------------------------------------------------------------
169 [HEARTBEAT] ----------> Starts the
170 heartbeat protocol
171 off
172
173 <---------- [OK|ERROR] Indicates that the
174 server is ok or not
175
176 [CONFIG] ----------> Indicates that the
177 host wants to check
178 its config
179
180 <---------- [OK|ERROR] Indicates that the
181 server is ok or not
182
183 [{filelist}] ----------> Send a semi-colon
184 separated list of
185 filenames
186 eg,
187 a.conf;b.conf;c.conf
188 This should be
189 identical to the one
190 received in the
191 connection protocol
192
193 <---------- [OK] Indicates that the
194 server is ok
195
196 [{lastmodified}]----------> Returns a long int
197 time since epoch
198 eg, 123456789
199 This should be
200 identical to the one
201 received in the
202 connection protocol
203
204 <---------- [OK|ERROR] The server then
205 checks all the files
206 in the file list to
207 see if they have
208 been modified more
209 recently than the
210 lastmodified value.
211 If they HAVE that
212 indicates that the
213 configuration has
214 changed and the host
215 should re-configure,
216 thus it sends ERROR.
217 If the files remain
218 unchanged the server
219 will return OK to
220 indicate the host
221 should continue as
222 before
223
224 [ENDHEARTBEAT] ----------> Indicates to the
225 server that the host
226 has finished an will
227 disconnect
228
229 <---------- [OK|ERROR] Indicates that the
230 server is either ok
231 or that it thought
232 there was an error
233
234 Host Data Protocol
235 ------------------
236 The UDP data packets that are sent by the host contain
237 simply XML data. For information on the format of this
238 data see the XML via UDP specification document at:
239
240 http://www.i-scream.org.uk/cgi-bin/docs.cgi?doc=specificatio
241 n/xml_via_udp.txt
242
243 Client Control Protocol
244 -----------------------
245
246 <TODO>
247
248 Client Data Protocol
249 --------------------
250
251 <TODO>
252
253 About
254 -----
255 This document was written by AJ Moore [ajm4@ukc.ac.uk] for
256 use by the team working on a 3rd year Computer Science
257 project called "i-scream". More details can be found on the
258 project website;
259
260 http://www.i-scream.org.uk