protocol

Linux下的多协议即时通讯程序源代码

# 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, former libpurple 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.

# Note from Eric Warmenhoven, random guy -- this appears to be the last
# published version of the protocol, and AOL has stopped hosting the TiK
# program. TiK is still being maintained and is hosted on sourceforge.net;
# this appears to be the same version of the protocol they're using.

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"