comparison libpurple/protocols/toc/PROTOCOL @ 15373:5fe8042783c1

Rename gtk/ and libgaim/ to pidgin/ and libpurple/
author Sean Egan <seanegan@gmail.com>
date Sat, 20 Jan 2007 02:32:10 +0000
parents
children 05404736d5e3
comparison
equal deleted inserted replaced
15372:f79e0f4df793 15373:5fe8042783c1
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