Mercurial > pidgin
diff doc/PROTOCOL @ 1:2846a03bda67
[gaim-migrate @ 10]
The other missing files :)
committer: Tailor Script <tailor@pidgin.im>
author | Rob Flynn <gaim@robflynn.com> |
---|---|
date | Thu, 23 Mar 2000 03:13:54 +0000 |
parents | |
children | f90b022235fe |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/PROTOCOL Thu Mar 23 03:13:54 2000 +0000 @@ -0,0 +1,443 @@ +# Copyright (c) 1998-9 America Online, Inc. All Rights Reserved. +# +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +# Note from Jim Duchek, gaim maintainer -- this may not be the latest +# version of this document, I provide it as a service. Download a copy +# of TiK (http://www.aim.aol.com/tik/) for the latest version of this +# doc. + +Version: TOC1.0 + +This document describes the protocol between TOC and TOC clients. +The protocol is built on TCP. Framing is done by SFLAP, +described at the bottom of this document. Inside each +SFLAP frame is a TOC command. + +The TOC protocol is ASCII based, and special attention +must be placed argument separation. The separator and +the rules of separation are different for messages inbound +to TOC and outbound to the client. The rules of separation +are described in sections below. + +The TOC server is built mainly to service the TIC and TiK clients. Since +the TIC client is a Java applet, and downloadable, TOC will NOT support +multiple TOC protocol versions at the same time. Therefore, TiK +users will be forced to upgrade if the protocol version changes. +TOC sends down the protocol version it expects the client +to speak and understand. Note, the protocol version is a string. + +Important Notes +=============== +* TOC will drop the connection if a command exceeds the maximum + length, which is currently 2048 bytes. So the client needs to + spend special attention to im, chat, and config message lengths. + There is an 8k length maximum from TOC to the client. + +* No commands should be sent to TOC (besides toc_signon) before + a SIGN_ON is received. If you do send a command before SIGN_ON + the command will be ignored, and in some case the connection + will be dropped. + +* Initial permit/deny items should be sent after receiving SIGN_ON + but before sending toc_init_done, otherwise the user will flash + on peoples buddylist who the user has denied. You will probably + want to send the toc_add_buddies at this time also. + +* After TOC sends the PAUSE message to a client, all messages sent + to TOC will be ignored, and in some cases the connection will + be dropped. Another SIGN_ON message will be sent to the client + when it is online again. The buddy list and permit/deny items must + be sent again, followed by the toc_init_done. In most cases the + SIGN_ON message will be sent between 1-2 seconds after the + PAUSE message. Therefore a client could choose to ignore the + PAUSE message and hope nothing bad happens. + + +Client -> TOC +============== +The commands and the arguments are usually separated by whitespaces. Arguments +with whitespace characters should be enclosed in quotes. Dollar signs, +curly brackets, square brackets, parentheses, quotes, and backslashes +must all be backslashed whether in quotes or not. It is usually +a good idea just to use quotes no matter what. All user names from clients +to TOC should be normalized (spaces removed and lowercased), and therefore +are the one exception to the always use quotes rule. + +When sending commands to the server you will not get a response +back confirming that the command format was correct or not! However +in some cases if the command format was incorrect the connection +will be dropped. + + +RoastingString="Tic/Toc" + +toc_signon <authorizer host> <authorizer port> <User Name> <Password> + <language> <version> + The password needs to be roasted with the Roasting String if + coming over a FLAP connection, CP connections don't use + roasted passwords. The language specified will be used + when generating web pages, such as the get info pages. + Currently the only supported language is "english". + If the language sent isn't found, the default "english" + language will be used. The version string will be used + for the client identity, and must be less then 50 + characters. + + Passwords are roasted when sent to the host. This is done so they + aren't sent in "clear text" over the wire, although they are still + trivial to decode. Roasting is performed by first xoring each byte + in the password with the equivalent modulo byte in the roasting + string. The result is then converted to ascii hex, and prepended + with "0x". So for example the password "password" roasts to + "0x2408105c23001130" + +toc_init_done + Tells TOC that we are ready to go online. TOC clients should first + send TOC the buddy list and any permit/deny lists. However toc_init_done + must be called within 30 seconds after toc_signon, or the connection + will be dropped. Remember, it can't be called until after the SIGN_ON + message is received. Calling this before or multiple times after a + SIGN_ON will cause the connection to be dropped. + +toc_send_im <Destination User> <Message> [auto] + Send a message to a remote user. Remember to quote and encode the + message. If the optional string "auto" is the last argument, then the + auto response flag will be turned on for the im. + +toc_add_buddy <Buddy User 1> [<Buddy User2> [<Buddy User 3> [...]]] + Add buddies to your buddy list. This does not change your + saved config. + +toc_remove_buddy <Buddy User 1> [<Buddy User2> [<Buddy User 3> [...]]] + Remove buddies from your buddy list. This does not change your + saved config. + +toc_set_config <Config Info> + Set the config information for this user. The config information + is line oriented with the first character being the item type, + followed by a space, with the rest of the line being the item + value. Only letters, numbers, and spaces should be used. Remember + you will have to enclose the entire config in quotes. + + Item Types: + g - Buddy Group (All Buddies until the next g or the end of config + are in this group.) + b - A Buddy + p - Person on permit list + d - Person on deny list + m - Permit/Deny Mode. Possible values are + 1 - Permit All + 2 - Deny All + 3 - Permit Some + 4 - Deny Some + +toc_evil <User> <norm|anon> + Evil/Warn someone else. The 2nd argument is either the string + "norm" for a normal warning, or "anon" for an anonymous + warning. You can only evil people who have recently sent you + ims. The higher someones evil level, the slower they can + send message. + +toc_add_permit [ <User 1> [<User 2> [...]]] + ADD the following people to your permit mode. If + you are in deny mode it will switch you to permit + mode first. With no arguments and in deny mode + this will switch you to permit none. If already + in permit mode, no arguments does nothing + and your permit list remains the same. + +toc_add_deny [ <User 1> [<User 2> [... ]]] + ADD the following people to your deny mode. If + you are in permit mode it will switch you to + deny mode first. With no arguments and in permit + mode, this will switch you to deny none. If + already in deny mode, no arguments does nothing + and your deny list remains unchanged. + +toc_chat_join <Exchange> <Chat Room Name> + Join a chat room in the given exchange. Exchange is + an integer that represents a group of chat rooms. + Different exchanges have different properties. For + example some exchanges might have room replication (ie + a room never fills up, there are just multiple + instances.) and some exchanges might have navigational + information, and some exchanges might have ... Currently + exchange should always be 4, however this may + change in the future. You will either + receive an ERROR if the room couldn't be joined + or a CHAT_JOIN message. The Chat Room Name + is case insensitive and consecutive spaces + are removed. + +toc_chat_send <Chat Room ID> <Message> + Send a message in a chat room using the chat room + id from CHAT_JOIN. Since reflection is always on in + TOC, you do not need to add the message to your chat UI, + since you will get a CHAT_IN with the message. + Remember to quote and encode the message. + +toc_chat_whisper <Chat Room ID> <dst_user> <Message> + Send a message in a chat room using the chat room + id from CHAT_JOIN. This message is directed at + only one person. (Currently you DO need to add this to + your UI.) Remember to quote and encode the message. + Chat whispering is different from IMs since it is linked + to a chat room, and should usually be displayed in the chat + room UI. + +toc_chat_evil <Chat Room ID> <User> <norm|anon> + Evil/Warn someone else inside a chat room. The 3rd argument is either + the string "norm" for a normal warning, or "anon" for an anonymous + warning. Currently chat evil is not turned on in the chat complex. + +toc_chat_invite <Chat Room ID> <Invite Msg> <buddy1> [<buddy2> [<buddy3> [...]]] + Once you are inside a chat room you can invite other people into + that room. Remember to quote and encode the invite message. + +toc_chat_leave <Chat Room ID> + Leave the chat room. + +toc_chat_accept <Chat Room ID> + Accept a CHAT_INVITE message from TOC. The server will send a + CHAT_JOIN in response. + +toc_get_info <username> + Gets a user's info a GOTO_URL or ERROR message will be sent back to the + client. + +toc_set_info <info information> + Set the LOCATE user information. This is basic HTML. + Remember to encode the info. + +toc_set_away [<away message>] + if the away message is present, then the unavailable + status flag is set for the user. If the away message + is not present, then the unavailable status flag is + unset. The away message is basic HTML, remember to + encode the information. + +toc_get_dir <username> + Gets a user's dir info a GOTO_URL or ERROR message will be sent back to the + client. + +toc_set_dir <info information> + Set the DIR user information. This is a colon separated fields as in: + "first name":"middle name":"last name":"maiden name":"city":"state":"country":"email":"allow web searches" + Should return a DIR_STATUS msg. Having anything in the "allow web searches" + field allows people to use web-searches to find your directory info. + Otherwise, they'd have to use the client. + +toc_dir_search <info information> + Perform a search of the Oscar Directory, using colon separated fields as in: + "first name":"middle name":"last name":"maiden name":"city":"state":"country":"email" + Returns either a GOTO_URL or ERROR msg. + +toc_set_idle <idle secs> + Set idle information. If <idle secs> is 0 then the user isn't idle at all. + If <idle secs> is greater then 0 then the user has already been idle + for <idle secs> number of seconds. The server will automatically + keep incrementing this number, so do not repeatedly call with new + idle times. + + +TOC -> Client +============== +All user names from TOC to client are NOT normalized, and are +sent as they should be displayed. String are NOT encoded, instead +we use colons as separators. So that you can have colons inside +of messages, everything after the colon before :<Message> should +be considered part of the message (ie don't just "split" on colons, +instead split with a max number of results.) + + +SIGN_ON:<Client Version Supported> + This is sent after a successful toc_signon command is sent to TOC. + If the command was unsuccessful either the FLAP connection will + be dropped or you will receive a ERROR message. + +CONFIG:<config> + A user's config. Config can be empty in which case the host was not able to + retrieve it, or a config didn't exist for the user. See toc_set_config + above for the format. + +NICK:<Nickname> + Tells you your correct nickname (ie how it should be capitalized and + spacing) + +IM_IN:<Source User>:<Auto Response T/F?>:<Message> + Receive an IM from some one. Everything after the third colon is + the incoming message, including other colons. + +UPDATE_BUDDY:<Buddy User>:<Online? T/F>:<Evil Amount>:<Signon Time>:<IdleTime>:<UC> + This one command handles arrival/depart/updates. Evil Amount is + a percentage, Signon Time is UNIX epoc, idle time is in minutes, UC (User Class) + is a two/three character string. + uc[0]: + ' ' - Ignore + 'A' - On AOL + uc[1] + ' ' - Ignore + 'A' - Oscar Admin + 'U' - Oscar Unconfirmed + 'O' - Oscar Normal + uc[2] + '\0' - Ignore + ' ' - Ignore + 'U' - The user has set their unavailable flag. + + + +ERROR:<Error Code>:Var args + * General Errors * + 901 - $1 not currently available + 902 - Warning of $1 not currently available + 903 - A message has been dropped, you are exceeding + the server speed limit + * Chat Errors * + 950 - Chat in $1 is unavailable. + + * IM & Info Errors * + 960 - You are sending message too fast to $1 + 961 - You missed an im from $1 because it was too big. + 962 - You missed an im from $1 because it was sent too fast. + + * Dir Errors * + 970 - Failure + 971 - Too many matches + 972 - Need more qualifiers + 973 - Dir service temporarily unavailable + 974 - Email lookup restricted + 975 - Keyword Ignored + 976 - No Keywords + 977 - Language not supported + 978 - Country not supported + 979 - Failure unknown $1 + + * Auth errors * + 980 - Incorrect nickname or password. + 981 - The service is temporarily unavailable. + 982 - Your warning level is currently too high to sign on. + 983 - You have been connecting and + disconnecting too frequently. Wait 10 minutes and try again. + If you continue to try, you will need to wait even longer. + 989 - An unknown signon error has occurred $1 + + +EVILED:<new evil>:<name of eviler, blank if anonymous> + The user was just eviled. + +CHAT_JOIN:<Chat Room Id>:<Chat Room Name> + We were able to join this chat room. The Chat Room Id is + internal to TOC. + +CHAT_IN:<Chat Room Id>:<Source User>:<Whisper? T/F>:<Message> + A chat message was sent in a chat room. + +CHAT_UPDATE_BUDDY:<Chat Room Id>:<Inside? T/F>:<User 1>:<User 2>... + This one command handles arrival/departs from a chat room. The + very first message of this type for each chat room contains the + users already in the room. + +CHAT_INVITE:<Chat Room Name>:<Chat Room Id>:<Invite Sender>:<Message> + We are being invited to a chat room. + +CHAT_LEFT:<Chat Room Id> + Tells tic connection to chat room has been dropped + +GOTO_URL:<Window Name>:<Url> + Goto a URL. Window Name is the suggested internal name of the window + to use. (Java supports this.) + +DIR_STATUS:<Return Code> + + +PAUSE + Tells TIC to pause so we can do migration + +Typical Signon Process +====================== +Except for the section marked optional this is an sequential +process. Each line MUST occur before the following line. + +* Client connects to TOC +* Client sends "FLAPON\r\n\r\n" +* TOC sends Client FLAP SIGNON +* Client sends TOC FLAP SIGNON +* Client sends TOC "toc_signon" message +* if login fails TOC drops client's connection + else TOC sends client SIGN_ON reply +* if Client doesn't support version it drops the connection + +[BEGIN OPTIONAL] + * TOC sends Client CONFIG + * Client sends TOC permit/deny stuff + * Client sends TOC toc_add_buddy message +[END OPTIONAL] + +* Client sends TOC toc_init_done message + + +SFLAP Documentation +=================== +SFLAP is pretty much a FLAP connection except the DATA frame payload is a null +terminated string when traveling from client to host, it is NOT null +terminated when traveling from host to client. The FLAP Header is binary +data, and is in network byte order. The data portion is at offset 6, after the +header. The sequence number is sequential in each direction. So +packets from the server to client have one sequence number, while +the packets from the client to server have an independent +increasing number. + +FLAP Header (6 bytes) +----------- +Offset Size Type +0 1 ASTERISK (literal ASCII '*') +1 1 Frame Type +2 2 Sequence Number +4 2 Data Length + + +Valid Frame Type Values +----------------------- +1 SIGNON +2 DATA +3 ERROR (Not used by TOC) +4 SIGNOFF (Not used by TOC) +5 KEEP_ALIVE + + +TOC SIGNON FRAME TYPE +--------------------- +Sequence Number contains the initial sequence number used in each direction. +Data Length contains the payload length, with the payload described +below. The payload area is NOT null terminated. + +Host To Client: + 4 byte FLAP version (1) + +Client To Host: + 4 byte FLAP version (1) + 2 byte TLV Tag (1) + 2 byte Normalized User Name Length + N byte Normalized User Name (NOT null terminated) + + +TOC DATA FRAME TYPE +------------------- +Sequence Number contains the next sequence number. +Data Length is the length of the payload, including the null termination +from client to host. +