|
1
|
1 # Copyright (c) 1998-9 America Online, Inc. All Rights Reserved.
|
|
|
2 #
|
|
|
3 # This program is free software; you can redistribute it and/or
|
|
|
4 # modify it under the terms of the GNU General Public License
|
|
|
5 # as published by the Free Software Foundation; either version 2
|
|
|
6 # of the License, or (at your option) any later version.
|
|
|
7 #
|
|
|
8 # This program is distributed in the hope that it will be useful,
|
|
|
9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
11 # GNU General Public License for more details.
|
|
|
12 #
|
|
|
13 # You should have received a copy of the GNU General Public License
|
|
|
14 # along with this program; if not, write to the Free Software
|
|
|
15 # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
|
|
|
16
|
|
|
17 # Note from Jim Duchek, gaim maintainer -- this may not be the latest
|
|
|
18 # version of this document, I provide it as a service. Download a copy
|
|
|
19 # of TiK (http://www.aim.aol.com/tik/) for the latest version of this
|
|
|
20 # doc.
|
|
|
21
|
|
|
22 Version: TOC1.0
|
|
|
23
|
|
|
24 This document describes the protocol between TOC and TOC clients.
|
|
|
25 The protocol is built on TCP. Framing is done by SFLAP,
|
|
|
26 described at the bottom of this document. Inside each
|
|
|
27 SFLAP frame is a TOC command.
|
|
|
28
|
|
|
29 The TOC protocol is ASCII based, and special attention
|
|
|
30 must be placed argument separation. The separator and
|
|
|
31 the rules of separation are different for messages inbound
|
|
|
32 to TOC and outbound to the client. The rules of separation
|
|
|
33 are described in sections below.
|
|
|
34
|
|
|
35 The TOC server is built mainly to service the TIC and TiK clients. Since
|
|
|
36 the TIC client is a Java applet, and downloadable, TOC will NOT support
|
|
|
37 multiple TOC protocol versions at the same time. Therefore, TiK
|
|
|
38 users will be forced to upgrade if the protocol version changes.
|
|
|
39 TOC sends down the protocol version it expects the client
|
|
|
40 to speak and understand. Note, the protocol version is a string.
|
|
|
41
|
|
|
42 Important Notes
|
|
|
43 ===============
|
|
|
44 * TOC will drop the connection if a command exceeds the maximum
|
|
|
45 length, which is currently 2048 bytes. So the client needs to
|
|
|
46 spend special attention to im, chat, and config message lengths.
|
|
|
47 There is an 8k length maximum from TOC to the client.
|
|
|
48
|
|
|
49 * No commands should be sent to TOC (besides toc_signon) before
|
|
|
50 a SIGN_ON is received. If you do send a command before SIGN_ON
|
|
|
51 the command will be ignored, and in some case the connection
|
|
|
52 will be dropped.
|
|
|
53
|
|
|
54 * Initial permit/deny items should be sent after receiving SIGN_ON
|
|
|
55 but before sending toc_init_done, otherwise the user will flash
|
|
|
56 on peoples buddylist who the user has denied. You will probably
|
|
|
57 want to send the toc_add_buddies at this time also.
|
|
|
58
|
|
|
59 * After TOC sends the PAUSE message to a client, all messages sent
|
|
|
60 to TOC will be ignored, and in some cases the connection will
|
|
|
61 be dropped. Another SIGN_ON message will be sent to the client
|
|
|
62 when it is online again. The buddy list and permit/deny items must
|
|
|
63 be sent again, followed by the toc_init_done. In most cases the
|
|
|
64 SIGN_ON message will be sent between 1-2 seconds after the
|
|
|
65 PAUSE message. Therefore a client could choose to ignore the
|
|
|
66 PAUSE message and hope nothing bad happens.
|
|
|
67
|
|
|
68
|
|
|
69 Client -> TOC
|
|
|
70 ==============
|
|
|
71 The commands and the arguments are usually separated by whitespaces. Arguments
|
|
|
72 with whitespace characters should be enclosed in quotes. Dollar signs,
|
|
|
73 curly brackets, square brackets, parentheses, quotes, and backslashes
|
|
|
74 must all be backslashed whether in quotes or not. It is usually
|
|
|
75 a good idea just to use quotes no matter what. All user names from clients
|
|
|
76 to TOC should be normalized (spaces removed and lowercased), and therefore
|
|
|
77 are the one exception to the always use quotes rule.
|
|
|
78
|
|
|
79 When sending commands to the server you will not get a response
|
|
|
80 back confirming that the command format was correct or not! However
|
|
|
81 in some cases if the command format was incorrect the connection
|
|
|
82 will be dropped.
|
|
|
83
|
|
|
84
|
|
|
85 RoastingString="Tic/Toc"
|
|
|
86
|
|
|
87 toc_signon <authorizer host> <authorizer port> <User Name> <Password>
|
|
|
88 <language> <version>
|
|
|
89 The password needs to be roasted with the Roasting String if
|
|
|
90 coming over a FLAP connection, CP connections don't use
|
|
|
91 roasted passwords. The language specified will be used
|
|
|
92 when generating web pages, such as the get info pages.
|
|
|
93 Currently the only supported language is "english".
|
|
|
94 If the language sent isn't found, the default "english"
|
|
|
95 language will be used. The version string will be used
|
|
|
96 for the client identity, and must be less then 50
|
|
|
97 characters.
|
|
|
98
|
|
|
99 Passwords are roasted when sent to the host. This is done so they
|
|
|
100 aren't sent in "clear text" over the wire, although they are still
|
|
|
101 trivial to decode. Roasting is performed by first xoring each byte
|
|
|
102 in the password with the equivalent modulo byte in the roasting
|
|
|
103 string. The result is then converted to ascii hex, and prepended
|
|
|
104 with "0x". So for example the password "password" roasts to
|
|
|
105 "0x2408105c23001130"
|
|
|
106
|
|
|
107 toc_init_done
|
|
|
108 Tells TOC that we are ready to go online. TOC clients should first
|
|
|
109 send TOC the buddy list and any permit/deny lists. However toc_init_done
|
|
|
110 must be called within 30 seconds after toc_signon, or the connection
|
|
|
111 will be dropped. Remember, it can't be called until after the SIGN_ON
|
|
|
112 message is received. Calling this before or multiple times after a
|
|
|
113 SIGN_ON will cause the connection to be dropped.
|
|
|
114
|
|
|
115 toc_send_im <Destination User> <Message> [auto]
|
|
|
116 Send a message to a remote user. Remember to quote and encode the
|
|
|
117 message. If the optional string "auto" is the last argument, then the
|
|
|
118 auto response flag will be turned on for the im.
|
|
|
119
|
|
|
120 toc_add_buddy <Buddy User 1> [<Buddy User2> [<Buddy User 3> [...]]]
|
|
|
121 Add buddies to your buddy list. This does not change your
|
|
|
122 saved config.
|
|
|
123
|
|
|
124 toc_remove_buddy <Buddy User 1> [<Buddy User2> [<Buddy User 3> [...]]]
|
|
|
125 Remove buddies from your buddy list. This does not change your
|
|
|
126 saved config.
|
|
|
127
|
|
|
128 toc_set_config <Config Info>
|
|
|
129 Set the config information for this user. The config information
|
|
|
130 is line oriented with the first character being the item type,
|
|
|
131 followed by a space, with the rest of the line being the item
|
|
|
132 value. Only letters, numbers, and spaces should be used. Remember
|
|
|
133 you will have to enclose the entire config in quotes.
|
|
|
134
|
|
|
135 Item Types:
|
|
|
136 g - Buddy Group (All Buddies until the next g or the end of config
|
|
|
137 are in this group.)
|
|
|
138 b - A Buddy
|
|
|
139 p - Person on permit list
|
|
|
140 d - Person on deny list
|
|
|
141 m - Permit/Deny Mode. Possible values are
|
|
|
142 1 - Permit All
|
|
|
143 2 - Deny All
|
|
|
144 3 - Permit Some
|
|
|
145 4 - Deny Some
|
|
|
146
|
|
|
147 toc_evil <User> <norm|anon>
|
|
|
148 Evil/Warn someone else. The 2nd argument is either the string
|
|
|
149 "norm" for a normal warning, or "anon" for an anonymous
|
|
|
150 warning. You can only evil people who have recently sent you
|
|
|
151 ims. The higher someones evil level, the slower they can
|
|
|
152 send message.
|
|
|
153
|
|
|
154 toc_add_permit [ <User 1> [<User 2> [...]]]
|
|
|
155 ADD the following people to your permit mode. If
|
|
|
156 you are in deny mode it will switch you to permit
|
|
|
157 mode first. With no arguments and in deny mode
|
|
|
158 this will switch you to permit none. If already
|
|
|
159 in permit mode, no arguments does nothing
|
|
|
160 and your permit list remains the same.
|
|
|
161
|
|
|
162 toc_add_deny [ <User 1> [<User 2> [... ]]]
|
|
|
163 ADD the following people to your deny mode. If
|
|
|
164 you are in permit mode it will switch you to
|
|
|
165 deny mode first. With no arguments and in permit
|
|
|
166 mode, this will switch you to deny none. If
|
|
|
167 already in deny mode, no arguments does nothing
|
|
|
168 and your deny list remains unchanged.
|
|
|
169
|
|
|
170 toc_chat_join <Exchange> <Chat Room Name>
|
|
|
171 Join a chat room in the given exchange. Exchange is
|
|
|
172 an integer that represents a group of chat rooms.
|
|
|
173 Different exchanges have different properties. For
|
|
|
174 example some exchanges might have room replication (ie
|
|
|
175 a room never fills up, there are just multiple
|
|
|
176 instances.) and some exchanges might have navigational
|
|
|
177 information, and some exchanges might have ... Currently
|
|
|
178 exchange should always be 4, however this may
|
|
|
179 change in the future. You will either
|
|
|
180 receive an ERROR if the room couldn't be joined
|
|
|
181 or a CHAT_JOIN message. The Chat Room Name
|
|
|
182 is case insensitive and consecutive spaces
|
|
|
183 are removed.
|
|
|
184
|
|
|
185 toc_chat_send <Chat Room ID> <Message>
|
|
|
186 Send a message in a chat room using the chat room
|
|
|
187 id from CHAT_JOIN. Since reflection is always on in
|
|
|
188 TOC, you do not need to add the message to your chat UI,
|
|
|
189 since you will get a CHAT_IN with the message.
|
|
|
190 Remember to quote and encode the message.
|
|
|
191
|
|
|
192 toc_chat_whisper <Chat Room ID> <dst_user> <Message>
|
|
|
193 Send a message in a chat room using the chat room
|
|
|
194 id from CHAT_JOIN. This message is directed at
|
|
|
195 only one person. (Currently you DO need to add this to
|
|
|
196 your UI.) Remember to quote and encode the message.
|
|
|
197 Chat whispering is different from IMs since it is linked
|
|
|
198 to a chat room, and should usually be displayed in the chat
|
|
|
199 room UI.
|
|
|
200
|
|
|
201 toc_chat_evil <Chat Room ID> <User> <norm|anon>
|
|
|
202 Evil/Warn someone else inside a chat room. The 3rd argument is either
|
|
|
203 the string "norm" for a normal warning, or "anon" for an anonymous
|
|
|
204 warning. Currently chat evil is not turned on in the chat complex.
|
|
|
205
|
|
|
206 toc_chat_invite <Chat Room ID> <Invite Msg> <buddy1> [<buddy2> [<buddy3> [...]]]
|
|
|
207 Once you are inside a chat room you can invite other people into
|
|
|
208 that room. Remember to quote and encode the invite message.
|
|
|
209
|
|
|
210 toc_chat_leave <Chat Room ID>
|
|
|
211 Leave the chat room.
|
|
|
212
|
|
|
213 toc_chat_accept <Chat Room ID>
|
|
|
214 Accept a CHAT_INVITE message from TOC. The server will send a
|
|
|
215 CHAT_JOIN in response.
|
|
|
216
|
|
|
217 toc_get_info <username>
|
|
|
218 Gets a user's info a GOTO_URL or ERROR message will be sent back to the
|
|
|
219 client.
|
|
|
220
|
|
|
221 toc_set_info <info information>
|
|
|
222 Set the LOCATE user information. This is basic HTML.
|
|
|
223 Remember to encode the info.
|
|
|
224
|
|
|
225 toc_set_away [<away message>]
|
|
|
226 if the away message is present, then the unavailable
|
|
|
227 status flag is set for the user. If the away message
|
|
|
228 is not present, then the unavailable status flag is
|
|
|
229 unset. The away message is basic HTML, remember to
|
|
|
230 encode the information.
|
|
|
231
|
|
|
232 toc_get_dir <username>
|
|
|
233 Gets a user's dir info a GOTO_URL or ERROR message will be sent back to the
|
|
|
234 client.
|
|
|
235
|
|
|
236 toc_set_dir <info information>
|
|
|
237 Set the DIR user information. This is a colon separated fields as in:
|
|
|
238 "first name":"middle name":"last name":"maiden name":"city":"state":"country":"email":"allow web searches"
|
|
|
239 Should return a DIR_STATUS msg. Having anything in the "allow web searches"
|
|
|
240 field allows people to use web-searches to find your directory info.
|
|
|
241 Otherwise, they'd have to use the client.
|
|
|
242
|
|
|
243 toc_dir_search <info information>
|
|
|
244 Perform a search of the Oscar Directory, using colon separated fields as in:
|
|
|
245 "first name":"middle name":"last name":"maiden name":"city":"state":"country":"email"
|
|
|
246 Returns either a GOTO_URL or ERROR msg.
|
|
|
247
|
|
|
248 toc_set_idle <idle secs>
|
|
|
249 Set idle information. If <idle secs> is 0 then the user isn't idle at all.
|
|
|
250 If <idle secs> is greater then 0 then the user has already been idle
|
|
|
251 for <idle secs> number of seconds. The server will automatically
|
|
|
252 keep incrementing this number, so do not repeatedly call with new
|
|
|
253 idle times.
|
|
|
254
|
|
|
255
|
|
|
256 TOC -> Client
|
|
|
257 ==============
|
|
|
258 All user names from TOC to client are NOT normalized, and are
|
|
|
259 sent as they should be displayed. String are NOT encoded, instead
|
|
|
260 we use colons as separators. So that you can have colons inside
|
|
|
261 of messages, everything after the colon before :<Message> should
|
|
|
262 be considered part of the message (ie don't just "split" on colons,
|
|
|
263 instead split with a max number of results.)
|
|
|
264
|
|
|
265
|
|
|
266 SIGN_ON:<Client Version Supported>
|
|
|
267 This is sent after a successful toc_signon command is sent to TOC.
|
|
|
268 If the command was unsuccessful either the FLAP connection will
|
|
|
269 be dropped or you will receive a ERROR message.
|
|
|
270
|
|
|
271 CONFIG:<config>
|
|
|
272 A user's config. Config can be empty in which case the host was not able to
|
|
|
273 retrieve it, or a config didn't exist for the user. See toc_set_config
|
|
|
274 above for the format.
|
|
|
275
|
|
|
276 NICK:<Nickname>
|
|
|
277 Tells you your correct nickname (ie how it should be capitalized and
|
|
|
278 spacing)
|
|
|
279
|
|
|
280 IM_IN:<Source User>:<Auto Response T/F?>:<Message>
|
|
|
281 Receive an IM from some one. Everything after the third colon is
|
|
|
282 the incoming message, including other colons.
|
|
|
283
|
|
|
284 UPDATE_BUDDY:<Buddy User>:<Online? T/F>:<Evil Amount>:<Signon Time>:<IdleTime>:<UC>
|
|
|
285 This one command handles arrival/depart/updates. Evil Amount is
|
|
|
286 a percentage, Signon Time is UNIX epoc, idle time is in minutes, UC (User Class)
|
|
|
287 is a two/three character string.
|
|
|
288 uc[0]:
|
|
|
289 ' ' - Ignore
|
|
|
290 'A' - On AOL
|
|
|
291 uc[1]
|
|
|
292 ' ' - Ignore
|
|
|
293 'A' - Oscar Admin
|
|
|
294 'U' - Oscar Unconfirmed
|
|
|
295 'O' - Oscar Normal
|
|
|
296 uc[2]
|
|
|
297 '\0' - Ignore
|
|
|
298 ' ' - Ignore
|
|
|
299 'U' - The user has set their unavailable flag.
|
|
|
300
|
|
|
301
|
|
|
302
|
|
|
303 ERROR:<Error Code>:Var args
|
|
|
304 * General Errors *
|
|
|
305 901 - $1 not currently available
|
|
|
306 902 - Warning of $1 not currently available
|
|
|
307 903 - A message has been dropped, you are exceeding
|
|
|
308 the server speed limit
|
|
|
309 * Chat Errors *
|
|
|
310 950 - Chat in $1 is unavailable.
|
|
|
311
|
|
|
312 * IM & Info Errors *
|
|
|
313 960 - You are sending message too fast to $1
|
|
|
314 961 - You missed an im from $1 because it was too big.
|
|
|
315 962 - You missed an im from $1 because it was sent too fast.
|
|
|
316
|
|
|
317 * Dir Errors *
|
|
|
318 970 - Failure
|
|
|
319 971 - Too many matches
|
|
|
320 972 - Need more qualifiers
|
|
|
321 973 - Dir service temporarily unavailable
|
|
|
322 974 - Email lookup restricted
|
|
|
323 975 - Keyword Ignored
|
|
|
324 976 - No Keywords
|
|
|
325 977 - Language not supported
|
|
|
326 978 - Country not supported
|
|
|
327 979 - Failure unknown $1
|
|
|
328
|
|
|
329 * Auth errors *
|
|
|
330 980 - Incorrect nickname or password.
|
|
|
331 981 - The service is temporarily unavailable.
|
|
|
332 982 - Your warning level is currently too high to sign on.
|
|
|
333 983 - You have been connecting and
|
|
|
334 disconnecting too frequently. Wait 10 minutes and try again.
|
|
|
335 If you continue to try, you will need to wait even longer.
|
|
|
336 989 - An unknown signon error has occurred $1
|
|
|
337
|
|
|
338
|
|
|
339 EVILED:<new evil>:<name of eviler, blank if anonymous>
|
|
|
340 The user was just eviled.
|
|
|
341
|
|
|
342 CHAT_JOIN:<Chat Room Id>:<Chat Room Name>
|
|
|
343 We were able to join this chat room. The Chat Room Id is
|
|
|
344 internal to TOC.
|
|
|
345
|
|
|
346 CHAT_IN:<Chat Room Id>:<Source User>:<Whisper? T/F>:<Message>
|
|
|
347 A chat message was sent in a chat room.
|
|
|
348
|
|
|
349 CHAT_UPDATE_BUDDY:<Chat Room Id>:<Inside? T/F>:<User 1>:<User 2>...
|
|
|
350 This one command handles arrival/departs from a chat room. The
|
|
|
351 very first message of this type for each chat room contains the
|
|
|
352 users already in the room.
|
|
|
353
|
|
|
354 CHAT_INVITE:<Chat Room Name>:<Chat Room Id>:<Invite Sender>:<Message>
|
|
|
355 We are being invited to a chat room.
|
|
|
356
|
|
|
357 CHAT_LEFT:<Chat Room Id>
|
|
|
358 Tells tic connection to chat room has been dropped
|
|
|
359
|
|
|
360 GOTO_URL:<Window Name>:<Url>
|
|
|
361 Goto a URL. Window Name is the suggested internal name of the window
|
|
|
362 to use. (Java supports this.)
|
|
|
363
|
|
|
364 DIR_STATUS:<Return Code>
|
|
|
365
|
|
|
366
|
|
|
367 PAUSE
|
|
|
368 Tells TIC to pause so we can do migration
|
|
|
369
|
|
|
370 Typical Signon Process
|
|
|
371 ======================
|
|
|
372 Except for the section marked optional this is an sequential
|
|
|
373 process. Each line MUST occur before the following line.
|
|
|
374
|
|
|
375 * Client connects to TOC
|
|
|
376 * Client sends "FLAPON\r\n\r\n"
|
|
|
377 * TOC sends Client FLAP SIGNON
|
|
|
378 * Client sends TOC FLAP SIGNON
|
|
|
379 * Client sends TOC "toc_signon" message
|
|
|
380 * if login fails TOC drops client's connection
|
|
|
381 else TOC sends client SIGN_ON reply
|
|
|
382 * if Client doesn't support version it drops the connection
|
|
|
383
|
|
|
384 [BEGIN OPTIONAL]
|
|
|
385 * TOC sends Client CONFIG
|
|
|
386 * Client sends TOC permit/deny stuff
|
|
|
387 * Client sends TOC toc_add_buddy message
|
|
|
388 [END OPTIONAL]
|
|
|
389
|
|
|
390 * Client sends TOC toc_init_done message
|
|
|
391
|
|
|
392
|
|
|
393 SFLAP Documentation
|
|
|
394 ===================
|
|
|
395 SFLAP is pretty much a FLAP connection except the DATA frame payload is a null
|
|
|
396 terminated string when traveling from client to host, it is NOT null
|
|
|
397 terminated when traveling from host to client. The FLAP Header is binary
|
|
|
398 data, and is in network byte order. The data portion is at offset 6, after the
|
|
|
399 header. The sequence number is sequential in each direction. So
|
|
|
400 packets from the server to client have one sequence number, while
|
|
|
401 the packets from the client to server have an independent
|
|
|
402 increasing number.
|
|
|
403
|
|
|
404 FLAP Header (6 bytes)
|
|
|
405 -----------
|
|
|
406 Offset Size Type
|
|
|
407 0 1 ASTERISK (literal ASCII '*')
|
|
|
408 1 1 Frame Type
|
|
|
409 2 2 Sequence Number
|
|
|
410 4 2 Data Length
|
|
|
411
|
|
|
412
|
|
|
413 Valid Frame Type Values
|
|
|
414 -----------------------
|
|
|
415 1 SIGNON
|
|
|
416 2 DATA
|
|
|
417 3 ERROR (Not used by TOC)
|
|
|
418 4 SIGNOFF (Not used by TOC)
|
|
|
419 5 KEEP_ALIVE
|
|
|
420
|
|
|
421
|
|
|
422 TOC SIGNON FRAME TYPE
|
|
|
423 ---------------------
|
|
|
424 Sequence Number contains the initial sequence number used in each direction.
|
|
|
425 Data Length contains the payload length, with the payload described
|
|
|
426 below. The payload area is NOT null terminated.
|
|
|
427
|
|
|
428 Host To Client:
|
|
|
429 4 byte FLAP version (1)
|
|
|
430
|
|
|
431 Client To Host:
|
|
|
432 4 byte FLAP version (1)
|
|
|
433 2 byte TLV Tag (1)
|
|
|
434 2 byte Normalized User Name Length
|
|
|
435 N byte Normalized User Name (NOT null terminated)
|
|
|
436
|
|
|
437
|
|
|
438 TOC DATA FRAME TYPE
|
|
|
439 -------------------
|
|
|
440 Sequence Number contains the next sequence number.
|
|
|
441 Data Length is the length of the payload, including the null termination
|
|
|
442 from client to host.
|
|
|
443
|
