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