Line data Source code
1 0 : /*
2 :
3 : OODebugTCPConsoleProtocol.h
4 :
5 : Definitions used in Oolite remote debug console protocol.
6 :
7 :
8 : Oolite Debug Support
9 :
10 : Copyright (C) 2007-2013 Jens Ayton
11 :
12 : Permission is hereby granted, free of charge, to any person obtaining a copy
13 : of this software and associated documentation files (the "Software"), to deal
14 : in the Software without restriction, including without limitation the rights
15 : to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
16 : copies of the Software, and to permit persons to whom the Software is
17 : furnished to do so, subject to the following conditions:
18 :
19 : The above copyright notice and this permission notice shall be included in all
20 : copies or substantial portions of the Software.
21 :
22 : THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23 : IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24 : FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
25 : AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26 : LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
27 : OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
28 : SOFTWARE.
29 :
30 : */
31 :
32 :
33 : #ifndef OOALSTR
34 : #ifdef __OBJC__
35 : #import <Foundation/Foundation.h>
36 : #define OOALSTR(x) @""x
37 : #else // C
38 : #include <CoreFoundation/CoreFoundation.h>
39 0 : #define OOALSTR(x) CFSTR(x)
40 : #endif
41 : #endif
42 :
43 :
44 0 : enum
45 : {
46 : kOOTCPConsolePort = 0x002173 /* = 8563 */
47 : };
48 :
49 :
50 : /* PROTOCOL OVERVIEW
51 :
52 : The basic unit of the protocol is property lists. Property lists originate
53 : with OpenStep and are thus defined in Cocoa and GNUstep, but they're also
54 : implemented in CoreFoundation (Mac OS X) and CFLite (cross-platform), with
55 : a C interface.
56 :
57 : The protocol uses a TCP stream in each direction. Each stream consists of
58 : a series of property lists in the Apple XML encoding. Each property list
59 : is framed in the simplest possible way: it is preceeded by an unsigned
60 : 32-bit length, in network-endian order. Each length + property list
61 : combination is referred to as a packet.
62 :
63 : Every packet's property list must have a dictionary as its root element.
64 : The dictionary must contain a kOOTCPConsolePacketType key, whose value
65 : determines the meaning of the rest of the dictionary.
66 : */
67 :
68 :
69 :
70 :
71 : /* *** Packet types *** */
72 : /* kOOTCPPacket_RequestConnection
73 : client --> server
74 : Message sent from client (Oolite) to server (console) to request a cosole
75 : connection.
76 :
77 : Required values:
78 : kOOTCPProtocolVersion
79 : kOOTCPOoliteVersion
80 : Expected responses:
81 : kOOTCPPacket_ApproveConnection
82 : OR
83 : kOOTCPPacket_RejectConnection
84 : */
85 0 : #define kOOTCPPacket_RequestConnection OOALSTR("Request Connection")
86 :
87 : /* kOOTCPPacket_ApproveConnection
88 : client <-- server
89 : Message sent in response to kOOTCPPacket_RequestConnection if connection is
90 : established successfully.
91 :
92 : Optional values:
93 : kOOTCPConsoleIdentity
94 : */
95 0 : #define kOOTCPPacket_ApproveConnection OOALSTR("Approve Connection")
96 :
97 : /* kOOTCPPacket_RejectConnection
98 : client <-- server
99 : Message sent in response to kOOTCPPacket_RequestConnection if connection is
100 : not established successfully. After this message is sent, the connection
101 : is closed with no further traffic.
102 :
103 : Optional values:
104 : kOOTCPMessage
105 : Expected responses:
106 : None permitted.
107 : */
108 0 : #define kOOTCPPacket_RejectConnection OOALSTR("Reject Connection")
109 :
110 : /* kOOTCPPacket_CloseConnection
111 : client <-> server
112 : Message sent by either party to cleanly close connection.
113 :
114 : Optional values:
115 : kOOTCPMessage
116 : Expected responses:
117 : None permitted.
118 : */
119 0 : #define kOOTCPPacket_CloseConnection OOALSTR("Close Connection")
120 :
121 : /* kOOTCPPacket_ConsoleOutput
122 : client --> server
123 : Message sent by Oolite to print text to console.
124 :
125 : Required values:
126 : kOOTCPMessage
127 : kOOTCPColorKey
128 : Optional values:
129 : kOOTCPEmphasisRanges
130 : */
131 0 : #define kOOTCPPacket_ConsoleOutput OOALSTR("Console Output")
132 :
133 : /* kOOTCPPacket_ClearConsole
134 : client --> server
135 : Message sent by Oolite to clear console output.
136 : */
137 0 : #define kOOTCPPacket_ClearConsole OOALSTR("Clear Console")
138 :
139 : /* kOOTCPPacket_ShowConsole
140 : client --> server
141 : Message sent by Oolite to request that the cosole makes itself visible and
142 : active.
143 : */
144 0 : #define kOOTCPPacket_ShowConsole OOALSTR("Show Console")
145 :
146 : /* kOOTCPPacket_NoteConfiguration
147 : client --> server
148 : Message sent by Oolite to appraise the console of the contents of the
149 : configuration dictionary. Sent once after the initial handshake.
150 :
151 : Required values:
152 : kOOTCPConfiguration
153 : */
154 0 : #define kOOTCPPacket_NoteConfiguration OOALSTR("Note Configuration")
155 :
156 : /* kOOTCPPacket_NoteConfigurationChange
157 : client <-> server
158 : Message sent by Oolite when the contents of the configuration dictionary
159 : change, or by console to change the configuration dictionary (in which
160 : case a confirmation will be returned in form of one or more
161 : kOOTCPPacket_NoteConfigurationChange messages). For this message,
162 : kOOTCPConfiguration is a delta -- keys not contained in it are not to be
163 : removed, they are simply unchanged. Deletions are handled with
164 : kOOTCPRemovedConfigurationKeys.
165 :
166 : This key is also sent in response to a kOOTCPPacket_RequestConfigurationValue
167 : message, even if no configuration value has changed.
168 :
169 : Required values (at least one of):
170 : kOOTCPConfiguration
171 : kOOTCPRemovedConfigurationKeys
172 : */
173 0 : #define kOOTCPPacket_NoteConfigurationChange OOALSTR("Note Configuration Change")
174 :
175 : /* kOOTCPPacket_PerformCommand
176 : client <-- server
177 : Message sent by console to issue a command.
178 :
179 : Required values:
180 : kOOTCPMessage
181 : */
182 0 : #define kOOTCPPacket_PerformCommand OOALSTR("Perform Command")
183 :
184 : /* kOOTCPPacket_RequestConfigurationValue
185 : client <-- server
186 : Message sent by console to request a configuration value. This will result
187 : in a kOOTCPPacket_NoteConfigurationChange message being sent. If the value
188 : is nil, the response will contain a kOOTCPRemovedConfigurationKeys value.
189 :
190 : Required values:
191 : kOOTCPConfigurationKey
192 : Expected response:
193 : kOOTCPPacket_NoteConfigurationChange
194 : */
195 0 : #define kOOTCPPacket_RequestConfigurationValue OOALSTR("Request Configuration Value")
196 :
197 : /* kOOTCPPacket_Ping
198 : client <-> server
199 : Must be responded to with a kOOTCPPacket_Pong message containing the same
200 : kOOTCPMessage, if any.
201 :
202 : Optional values:
203 : kOOTCPMessage
204 : Expected response:
205 : kOOTCPPacket_Pong
206 : */
207 0 : #define kOOTCPPacket_Ping OOALSTR("Ping")
208 :
209 : /* kOOTCPPacket_Pong
210 : client <-> server
211 : Must be sent in response to kOOTCPPacket_Ping. If the kOOTCPPacket_Ping
212 : packet had a kOOTCPMessage, the same kOOTCPMessage value must be attached
213 : to the kOOTCPPacket_Pong.
214 :
215 : Optional values:
216 : kOOTCPMessage (required if included in ping)
217 : */
218 0 : #define kOOTCPPacket_Pong OOALSTR("Pong")
219 :
220 :
221 :
222 :
223 : /* *** Value keys *** */
224 : /* kOOTCPPacketType
225 : String indicating packet type. See above under
226 :
227 : See constants below under *** Packet types ***.
228 : */
229 0 : #define kOOTCPPacketType OOALSTR("packet type")
230 :
231 : /* kOOTCPProtocolVersion
232 : Number indicating version of debug console TCP protocol. Sent with
233 : kOOTCPPacket_RequestConnection.
234 :
235 : See constants below under *** Version constants ***.
236 : */
237 0 : #define kOOTCPProtocolVersion OOALSTR("protocol version")
238 :
239 : /* kOOTCPOoliteVersion
240 : String indicating the version of Oolite, for example "1.70" or "1.71.1 b2".
241 : Consists of two or more integers separated by .s, optionally followed by
242 : a space and additional information in unspecified format. Sent with
243 : kOOTCPPacket_RequestConnection.
244 : */
245 0 : #define kOOTCPOoliteVersion OOALSTR("Oolite version")
246 :
247 : /* kOOTCPMessage
248 : Textual message sent with various packet types. No specified format.
249 : */
250 0 : #define kOOTCPMessage OOALSTR("message")
251 :
252 : /* kOOTCPConsoleIdentity
253 : String identifying console software. No specified format.
254 : */
255 0 : #define kOOTCPConsoleIdentity OOALSTR("console identity")
256 :
257 : /* kOOTCPColorKey
258 : String identifying colour/formatting to be used. The configuration
259 : dictionary contains keys of the form foo-foreground-color and
260 : foo-background-color to be used. If no colour is specified for the
261 : specified key, the key "general" should be tried. The colour values are
262 : specified as arrays of three numbers in the range 0-1, specifying RGB
263 : colours.
264 :
265 : For example, if the configuration key contains:
266 : {
267 : general-background-color = (1,1,1);
268 : general-foreground-color = (0,0,0);
269 : foo-background-color = (1,0,0);
270 : }
271 : the colour key "foo" maps to the background colour (1,0,0) and the
272 : foreground color (0,0,0). Sent with kOOTCPPacket_ConsoleOutput.
273 : */
274 0 : #define kOOTCPColorKey OOALSTR("color key")
275 :
276 : /* kOOTCPEmphasisRanges
277 : An array containing an even number of integers. Each pair of integers
278 : specifies a range (in the form offset, length) which should be emphasized.
279 : Sent with kOOTCPPacket_ConsoleOutput.
280 : */
281 0 : #define kOOTCPEmphasisRanges OOALSTR("emphasis ranges")
282 :
283 : /* kOOTCPConfiguration
284 : A dictionary of key/value pairs to add/set in the configuration
285 : dictionary. Sent with kOOTCPPacket_NoteConfiguration and
286 : kOOTCPPacket_NoteConfiguration.
287 : */
288 0 : #define kOOTCPConfiguration OOALSTR("configuration")
289 :
290 : /* kOOTCPConfiguration
291 : An array of keys to remove from the configuration dictionary. Sent with
292 : kOOTCPPacket_NoteConfiguration.
293 : */
294 0 : #define kOOTCPRemovedConfigurationKeys OOALSTR("removed configuration keys")
295 :
296 : /* kOOTCPConfigurationKey
297 : A string specifying the configuration key for which a value is requested.
298 : Sent with kOOTCPPacket_RequestConfigurationValue.
299 : */
300 0 : #define kOOTCPConfigurationKey OOALSTR("configuration key")
301 :
302 :
303 :
304 : /* *** Version constants *** */
305 : /* Version constants have three components: format, major and minor. The
306 : format version will change if the framing mechanism is changed, that is,
307 : if we switch from the property-list basted protocol in use. The major
308 : version will be changed to indicate compatibility-breaking changes. The
309 : minor version will be changed when new non-critical packets are added.
310 : */
311 :
312 0 : #define OOTCP_ENCODE_VERSION(f, mj, mi) \
313 : ((((f) << 16) & kOOTCPProtocolVersionFormatMask) | \
314 : (((f) << 8) & kOOTCPProtocolVersionMajorMask) | \
315 : ((mi) & kOOTCPProtocolVersionMinorMask))
316 :
317 0 : #define OOTCP_VERSION_FORMAT(v) (((v) & kOOTCPProtocolVersionFormatMask) >> 16)
318 0 : #define OOTCP_VERSION_MAJOR(v) (((v) & kOOTCPProtocolVersionMajorMask) >> 8)
319 0 : #define OOTCP_VERSION_MINOR(v) ((v) & kOOTCPProtocolVersionMinorMask)
320 :
321 0 : enum
322 : {
323 : kOOTCPProtocolVersionFormatMask = 0x00FF0000,
324 : kOOTCPProtocolVersionMajorMask = 0x0000FF00,
325 : kOOTCPProtocolVersionMinorMask = 0x000000FF,
326 :
327 : kOOTCPProtocolVersionPListFormat = 1,
328 :
329 : // 1:1.0, first version.
330 : kOOTCPProtocolVersion_1_1_0 = OOTCP_ENCODE_VERSION(kOOTCPProtocolVersionPListFormat, 1, 0)
331 : };
|
