OL Instant Messenger (AIM) is well known as one of the top four IM clients used today. Popular with both home users and businesses, AIM allows you to send instant messages (IMs) to other people who have a handle on the AIM network. However, you may not be aware that the protocol underlying AIM, called TOC2, is the gateway through which you can create a lot of customized AIM-based applications. AOL provides an API that anybody can use to connect to TOC2 and AOL's network. In this article I'll give you a brief history of the TOC2 protocol and then show you how to create your own custom chat application using the TOC2 API.

There are many different reasons to integrate instant messaging into an application. Obviously, you can create your own chat client, with whatever features you like. However, the real power lies in creating applications that you can "chat" with, just like you do a human. Want to know the status of your servers? Just fire up your instant messenger and ask your server for some information.

There are many different ways that you can integrate instant message technology into applications. To make use of AOL's chat network you will have to use their protocol, called TOC. Around August 10, 2005 AOL upgraded from the TOC protocol to the TOC2 protocol. The changes were minor, but unfortunately the upgrade broke every existing software connection to the TOC protocol. AOL's action left many users thinking that AOL had blocked third-party applications from accessing its network. This is not the case, but it does mean that all third-party AIM software must be upgraded to support TOC2.

I learned this the hard way. Back in 2001 I wrote a simple Java class that accesses AIM using TOC. My class broke, along with everything else, back in August. I have since upgraded it, and I am releasing the new version with this article.

Author's Note: The original AIM chat client and the updated version in this article are released under the LGPL license. Readers are free to use it, but credit must be given to the author, Jeff Heaton.

TOC Servers
To use TOC you simply use the sockets API available with Java. Special packets will then be exchanged with the server. These packets, called FLAPs, contain a single line of ASCII text that describes the TOC command that you wish to execute. The FLAP packet is relatively simple, and has the following format.

Byte 0: Marker (must be 0x2a)
Byte 1: Packet Type
Bytes 2,3: Sequence Number
Bytes 4,5: Length of Data
Bytes 6- : Packet Data

All communication with the TOC server will be in the form of these FLAP packets. This includes both packets that the TOC server sends to you, as well as packets that you send the TOC server.

As you will notice above, bytes 2,3 and 4,5 both go together. These two-byte pairs are called "words." Words are always sent as big-endian numbers. The following method is provided to write a word to the socket output string.

   protected void writeWord(short word)
   throws IOException
   {
     os.write((byte) ((word >> 8) & 0xff) );
     os.write( (byte) (word & 0xff) );
   }

A sendFlap method is also provided, which makes use of the writeWord method.

   protected void sendFlap(int type,String str)
   throws IOException
   {
     int length = str.length()+1;
     sequence++;
     os.write((byte)'*');
     os.write((byte)type);
     writeWord(sequence);
     writeWord((short)length);
     os.write(str.getBytes());
     os.write(0);
     os.flush();
   }

All FLAP packets start with the "*" character. Next the sequence number is incremented. The length of the string and the string itself are then transmitted. With the exception of the signon packet, all FLAP packets will be sent using this method. The flap signon is sent using the sendFlapSignon method. This is done because the signon packet has a slightly different format.

Likewise, a getFlap method is provided. This method will read a FLAP packet from the remote computer and return a String that holds the data that was in that packet:

   protected String getFlap()
   throws IOException
   {
     if ( is.read()!='*' )
       return null;
     is.read();
     is.read();
     is.read();
     int length = (is.read()*0x100)+is.read();
     byte b[] = new byte[length];
     is.read(b);
     

As you can see, this method reads a FLAP packet, and as before, the first character is an "*" as required. The sequence number and other fields are ignored. Only the length is used so that the correct number of characters for the packet are read.

You open a connection to the TOC server and exchange messages with it. There are actually two servers you will deal with. The first is the TOC server, which is at toc.oscar.aol.com, port 9898. The second is the login server, which is at login.oscar.aol.com, port 5190.

To communicate with AIM you open a connection to the TOC server. You then exchange login information and begin your AIM session.