Protocols/TOC/1.0

TOC Protocol

Introduction • Terms • Clients

Basic

TOC 1.0 • TOC 2.0

Tutorials

Sign On

TOC (Talk to OsCar) is a protocol, and a server which connects to the AIM service. At its core, the TOC protocol is string-based, and incapsulated in a FLAP packet. As the data transmitted is string-based, it is referred to as SFLAP.

Compared to OSCAR, TOC is more simple, however it is not as flexible and doesn't contain all the features of OSCAR. It does, however, contain the essential features to communicate with the AIM service: IMs, Chat rooms, Warnings, and Privacy Management.

Protocol

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 flas 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

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.

Commands

toc_signon

Command Syntax: 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".

The Roasting String is Tic/Toc.

toc_init_done

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: toc_chat_leave <Chat Room ID>

Leave the chat room.

toc_chat_accept

Command Syntax: 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

Command Syntax: 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

Command Syntax: toc_set_info <info information>

Set the LOCATE user information. This is basic HTML. Remember to encode the info.

toc_set_away

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: toc_rvous_propose

Syntax unknown, or not implemented.

toc_rvous_accept

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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

Command Syntax: 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_get_status

Command Syntax: toc_get_status <usernme>

Returns either UPDATE_BUDDY with a user's information if online, ERROR if not online.

Server

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

Commands

SIGN_ON

Command Syntax: 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

Command Syntax: 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

Command Syntax: NICK:<Nickname>

Tells you your correct nickname (ie how it should be capitalized and spacing)

IM_IN

Command Syntax: 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

Command Syntax: 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

Command Syntax: ERROR:<Error Code>:Var args

Check the full list of Error Codes.

EVILED

Command Syntax: EVILED:<new evil>:<name of eviler, blank if anonymous>

The user was just eviled.

CHAT_JOIN

Command Syntax: 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

Command Syntax: CHAT_IN:<Chat Room Id>:<Source User>:<Whisper? T/F>:<Message>

A chat message was sent in a chat room.

CHAT_UPDATE_BUDDY

Command Syntax: 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

Command Syntax: CHAT_INVITE:<Chat Room Name>:<Chat Room Id>:<Invite Sender>:<Message>

We are being invited to a chat room.

CHAT_LEFT

Command Syntax: CHAT_LEFT:<Chat Room Id>

Tells tic connection to chat room has been dropped

GOTO_URL

Command Syntax: 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

Command Syntax: DIR_STATUS:<Return Code>:<Optional args>

<Return Code> is always 0 for success status.

ADMIN_NICK_STATUS

Command Syntax: ADMIN_NICK_STATUS:<Return Code>:<Optional args>

<Return Code> is always 0 for success status.

PAUSE

Command Syntax: PAUSE

<Return Code> is always 0 for success status. Tells TIC to pause so we can do migration

RVOUS_PROPOSE

Command Syntax: 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.

Error Codes

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

Typical Sign-on 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. If not, 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

Sign-On 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)

FAQ

This FAQ was originally created by AOL, and is written verbatim. The NINA team has added some notes at the bottom of each answer.

What does TOC stand for?

TOC, pronounced /talk/, currently stands for TOC to OsCar for lack of a better acronym. Really it just has to do with the members of the TicToc project obsession with useless 3 letter meaningless words. Since TOC is just a proxy protocol, it kind of makes sense.

Note: TOC means "Talk to OSCAR", not "TOC to OSCAR".

How does the TOC protocol differ from the OSCAR protocol?

The TOC and the OSCAR protocol are very different. The TOC protocol is a high level abstraction of the OSCAR protocol. The TOC protocol is entirely string based while the OSCAR protocol is binary based. Since the TOC protocol is entirely string based there are NO network byte ordering problems, while the OSCAR protocol will require careful packaging of data. (This is excluding the 6 byte FLAP transport layer header, used by both TOC and OSCAR, and will require network byte ordering.) Finally, the TOC protocol is currently the only one officially released and documented.

At the protocol level currently there is nothing in TOC that isn't in OSCAR. However there are things in the OSCAR protocol that are not in TOC. For example TOC will probably never support directory look up, password changing, or other non "core" features. Obviously this translates to the TIC/TiK clients vs AIM clients.

Are there benefits to the TOC protocol vs OSCAR protocol? Well not really, except TOC is extremely easy to work with, and it is at least public. Once you create your OSCAR/TOC independent FLAP layer you don't have to worry about network byte ordering with TOC, which makes portability much simpler. String termination can still lead to memory issues, but a good split routine will solve that problem.

Note: Ironically enough, TOC does support directory look up and password changing.

What is FLAP?

FLAP is a low-level communications protocol that facilitates the development of higher-level, record-oriented, communications layers. It is used on the TCP connection between all clients and servers. TOC adds a few extra requirements to TOC which are documented in the PROTOCOL file.

Note: Check FLAP for more thorough information.

Where can I get more information on the TOC Protocol?

Download TiK and look in the PROTOCOL file included. TiK should always contain the latest PROTOCOL file, since the maintainer of TiK also maintains the PROTOCOL document. Most of the protocol and the ordering of messages is documented in this file. For support send your questions to the tictoc-users mailing list.

But strings in C are ...?

Many folks think working with strings in C is hard, inefficient, cpu intensive, buggy. While there are some gotchas to worry about, in most cases this is simply not true.

Working with the TOC protocol in C is only slightly harder then in a language that treats strings as first class object. Just create yourself some nice split and join routines like in perl. An even better method is to just link your application with perl or tcl, and use their routines to splits the strings into parts. The TOC server is written in C, for those of you who are curious.