Add existing source + chat invite handling

1 files changed, 489 insertions, 0 deletions

diff --git a/doc/toc.txt b/doc/toc.txt
new file mode 100644
index 0000000..5641f68
--- /dev/null
+++ b/doc/toc.txt
@@ -0,0 +1,489 @@
+# 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.

+

+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_set_caps [ <Capability 1> [<Capability 2> [...]]]

+    Set my capabilities.  All capabilities that we support need to

+    be sent at the same time.  Capabilities are represented by

+    UUIDs.  

+

+toc_rvous_propose  - Not Implemented Yet

+

+toc_rvous_accept <nick> <cookie> <service> <tlvlist>

+    Accept a rendezvous proposal from the user <nick>.

+    <cookie> is the cookie from the RVOUS_PROPOSE

+    message.  <service> is the UUID the proposal was

+    for. <tlvlist> contains a list of tlv tags followed by

+    base64 encoded values.

+

+toc_rvous_cancel <nick> <cookie> <service> <tlvlist>

+    Cancel a rendezvous proposal from the user <nick>.

+    <cookie> is the cookie from the RVOUS_PROPOSE

+    message.  <service> is the UUID the proposal was

+    for. <tlvlist> contains a list of tlv tags followed by

+    base64 encoded values.

+

+toc_format_nickname <new_format>

+    Reformat a user's nickname.  An ADMIN_NICK_STATUS or ERROR message will 

+    be sent back to the client.

+

+toc_change_passwd <existing_passwd new_passwd>

+    Change a user's password.  An ADMIN_PASSWD_STATUS or ERROR message will 

+    be sent back to the client.

+

+

+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

+

+   * Admin Errors  *

+   911   - Error validating input

+   912   - Invalid account

+   913   - Error encountered while processing request

+   914   - Service unavailable

+

+   * 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>:<Optional args>

+   <Return Code> is always 0 for success status.

+

+ADMIN_NICK_STATUS:<Return Code>:<Optional args>

+   <Return Code> is always 0 for success status.

+

+ADMIN_PASSWD_STATUS:<Return Code>:<Optional args>

+   <Return Code> is always 0 for success status.

+   

+

+PAUSE

+   Tells TIC to pause so we can do migration

+

+RVOUS_PROPOSE:<user>:<uuid>:<cookie>:<seq>:<rip>:<pip>:<vip>:<port>

+              [:tlv tag1:tlv value1[:tlv tag2:tlv value2[:...]]]

+   Another user has proposed that we rendezvous with them to

+   perform the service specified by <uuid>.  They want us

+   to connect to them, we have their rendezvous ip, their 

+   proposer_ip, and their verified_ip. The tlv values are 

+   base64 encoded.

+

+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.

+