Instant messaging has become very popular in recent years, earning it a deserved spot with the "killer apps" - browsing and e-mail. Most of the Internet's killer apps have spawned a host of accessories to be used in conjunction with the app. Instant messaging is just starting this process.

Many clients are appearing that can often send messages over various protocols. But do other models exist, besides simply sending instant messages between human users?

Several companies are already putting computers on the receiving end of instant messaging. One such company, ActiveBuddy (http://www.smarterchild.com/), put several "screen names" online that allow users to ask "virtual buddies" about such things as movies, weather, and stock quotes. Programs such as this require intimate knowledge of how the instant messaging system works.

This article shows you how to communicate with America Online's (AOL) Instant Messenger, known as AIM, by creating a reusable class that allows access to the AIM network, which you can use to create an instant messaging application.

AOL Protocols
There are many instant message clients that can talk to the AOL network, for example, programs such as Trillian, Jabber, and GAIM. In the past few months these programs have come under fire from America Online as AOL tries to keep unauthorized programs off their network. Why does AOL try to stop some clients and allow others to continue? The answer has to do with what protocol the instant messaging client uses.

When America Online first allowed Internet users to access the AIM network, they had to provide a protocol that would allow the Internet version of AIM to communicate back to the AOL network. This protocol is called OSCAR - Open System for Communication in Realtime - a misnomer. OSCAR is not an open system, or at least not "open" in the sense of GNU-style licensing.

OSCAR is a closed protocol, as AOL has never published its specification. Any large-scale use of the OSCAR protocol has always been vigilantly blocked, but this has not stopped programmers. A great deal of information is available on the Internet about the OSCAR protocol and many third-party instant message clients are based on it. I wrote an OSCAR client in Java that communicates with AOL using this protocol. However, if this client runs longer than 5-10 minutes, AOL sends me the following instant message just before their network disconnects my client.

You have been disconnected from the AOL Instant Message Service for accessing the AOL network using unauthorized software. You can download a FREE, fully featured, and authorized client here, http://www.aim.com/index.adp.

This article is not about how to use the OSCAR protocol. If you're interested in OSCAR, you can download my client from www.jeffheaton.com/im. If you use the OSCAR protocol for a large-scale project, you'll be playing "cat and mouse" with AOL. AOL's actions indicate that they do not want third parties using it. Products such as Trillian use the OSCAR protocol, and, as a result, users must frequently upgrade to a new version of Trillian that thwarts AOL's latest attempt to block them.

This article focuses on another AOL protocol named TOC (Talk to Oscar). TOC was created by America Online to allow open access to their instant message network; it was created prior to their merger with Time Warner. One of the conditions for this merger, set out by the U.S. government, was for AOL to open its instant messaging protocol. So AOL in essence created a wrapper. The TOC protocol sits on top of the OSCAR protocol and allows third-party applications to access the AIM network. AOL also released an open source, instant message client that's capable of using the TOC. The structure of the AOL network is shown in Figure 1.

As you can see from this figure, AOL subscribers connect directly to the AOL internal network. The AOL AIM clients go directly to the authentication and BOS (used for load balancing) servers, and the TOC clients connect through the TOC server. This results in three connection classes that can all communicate with each other.

The open source AIM client released by AOL was written in Tcl, and was called TiC (TOC is Cool). AOL no longer officially supports the TiC client, so it can't be downloaded from the AOL site. TiC is now maintained as an open source client on Source Forge (http://www.sourceforge.com/).

Clients that use the TOC protocol do not face the same blocks that OSCAR clients face. Unfortunately, there aren't any popular clients available for the Windows platform that make use of the TOC protocol. Trillian, for example, uses only the OSCAR protocol. Perhaps the most common client that supports the TOC protocol is GAIM. Unfortunately, it's written in C and supports only the UNIX platform. There's not much open Java source code for using the TOC protocol, which is why I wrote JavaTOC as an example for this article. Using the JavaTOC class, you can communicate with both the TOC protocol and the AIM network. This article presents a sample AIM-compatible client (see Figure 2), and the complete source code is available on the JDJ Web site, www.sys-con. com/java/sourcec.cfm.

If TOC is the protocol that AOL wants developers to use, why do most third-party programs use OSCAR? There are several reasons for this. First, OSCAR was available long before TOC. Many third-party programs were already written when TOC was released. Second, AOL has not been that good about adding all the latest features to TOC. To be able to send files and access the advanced "broadband" streaming content that AIM now contains, you must use the OSCAR protocol, since such features have not been added to TOC. However, for basic instant messaging and chat, TOC has all the necessary features.

Logging into TOC
The complete source code for my implementation of the TOC protocol can be found in the files "JavaTOC.java" and "Chatable.java". These two files can easily be added to any project that requires the use of instant messaging. To see how the JavaTOC class was constructed, you must first see how the TOC protocol works.

To log in to AIM you must have a screen name and password. If you don't have an AIM screen name, you can easily obtain one for free from http://aim.aol.com/. The JavaTOC class defines a method called "login" that accepts a screen name and password. When you call login, it begins the login process.

To log in to TOC you're required to send and receive data using FLAP, a special packet type. (It's unknown what FLAP stands for, as AOL has always used this name.) FLAP also forms the foundation of the OSCAR protocol. A FLAP packet consists of a header of six bytes followed by a variable length data packet (see Figure 3). The first byte of a FLAP packet is always the asterisk (*), which is hex code 0x2b. Following the identity byte is the frame type. TOC uses two frame types. One frame type indicates a "sign-on" packet, and the other a normal "data" packet. Most packets are data packets.

Following the first two bytes is a word representing the sequence number. Why AOL needed a sequence number on a protocol that uses TCP/IP is unknown. However, you must always provide an ever-increasing sequence number or your client will be abruptly disconnected. Sequence numbers can begin with any number and must always increase by one. The sequence numbers used by the client are completely separate from the sequence numbers sent to you by AOL. Following the sequence number is a word that specifies the length of the data section only and does not take into account the size of the FLAP header.

Both the length and sequence numbers are stored as little endian numbers, which means the last byte is the least significant. For example, the value 1024 would be stored as the byte 0x04 followed by 0x00, not the other way around. For more information on little and big endian numbers, see my article "A Class for Reading Binary Files" (JDJ, Vol. 6, issue 7). To allow these words to be written correctly, JavaTOC contains a method called "writeWord" that will write a word to an "InputStream" in a format that's correct for TOC.

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

The JavaTOC class also contains a useful method for writing FLAP packets to a socket. This handles the sequence number and lengths for you. Simply pass the string the writeFLAP method you'd like transmitted and the frame type (signon or data).

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(length);
os.write(str.getBytes());
os.write(0);
os.flush();
}

All the TOC commands are strings. The only part of the TOC protocol that's binary is the FLAP packets that enclose the TOC commands. Now, with the FLAP packet defined, we can log into TOC. The first step is to open a socket to the TOC server. The host name for the server is "toc.oscar.aol.com", and the port is 9898. Once a socket connection has been opened, the string "FLAPON\r\n\r\n" must be sent to the TOC server. Upon receiving this, the TOC server will reply with a FLAP pack containing the data bytes 0x00, 0x00, 0x00, and 0x01. This is the current version of FLAP being used, version one.

Next a FLAP signon packet must be sent. This is a normal FLAP packet with a data section that contains the following: first, the version numbers 0x00, 0x00, 0x00, and 0x01, then a word of 0x0001. This indicates that a user name will follow. The next word represents the length of the screen name. Following the length is the normalized representation of the screen name - all spaces are removed and the entire name is converted to lowercase.

Once the FLAP signon packet has been sent, the first TOC command must be sent. This is the "toc_signon" command. The exact syntax for this is:

toc_signon <authorizer host>
<authorizer port> <User Name> <Password> <language> <version>

Some of these fields will require a description to understand their use. First the authentication host and authorizer port refer to the authorization server shown in Figure 1. These values are always sent as "login.oscar.aol.com" and "5190", respectively. This specifies which OSCAR authentication server to use. The user name is simply the normalized user name.

The password is sent in a format that AOL refers to as roasted, so it's not transmitted as "clear text" over the wire. Still, roasted passwords are trivial to decode. The OSCAR protocol uses a more advanced MD5 challenge system. The process of roasting is performed by first xoring each byte in the password with the equivalent modulo byte in the roasting string, which is "Tic/Toc". The result is then converted to ASCII hex with a leading "0x". For example, the password "password" roasts to "0x2408105c23001130".

TOC currently supports only English; as a result "english" is the only value that should ever be sent as a language. The version field specifies which client is logging in and can be any value. If the login is successful, TOC server will respond with "SIGN_ON:version". If a failure happens, an "ERROR:error number" response is returned.

At this point the user is not signed in yet. To complete the login process the user's client must send the "toc_init_done" within 30 seconds of beginning the login process. Before the login method sends the "toc_init_done" command, a few configuration items are taken care of. First the "toc_add_buddy" command is sent to specify the user who's logging in as a buddy. Then the "toc_init_done" command is sent to complete the signon process.

After signon, a few configuration settings must be sent. The "toc_set_caps 09461343-4C7F-11D1-8222-444553540000 09461348-4C7F-11D1-8222-444553540000" command is sent. The two GUIDs specify the ability to send messages and buddy support. Finally, the permit and deny lists are cleared by sending the "toc_add_permit" and "toc_add_deny". These are lists that allow you to include or exclude certain people. With this complete, the client may now send and receive instant messages.

Logging out of TOC is easy. Simply breaking the socket connection by using the "close" method of the "Socket" class is sufficient.

Sending and Receiving Instant Messages
Sending and receiving instant messages with TOC is fairly easy. To send, the send method of the JavaTOC class should be called:

public void send(String to,String msg)
{
try {
this.sendFlap(DATA,"toc_send_im " + normalize(to) + "\"" + encode(msg) + "\"");
}
catch(java.io.IOException e){
}
}

This method accepts two parameters that specify who the message is going to and what the actual message is. The target's screen name is normalized, as previously defined. The message is encoded to fit inside quotes. Encoding the message involves setting any carriage returns to HTML <br> commands and putting a \ in front of characters such as quotes. AIM messages may contain HTML code.

Receiving an instant message is accomplished by the event loop contained in "JavaTOC". Because events can be received at any time from the TOC server, the program must be ready to handle them. The JavaTOC class contains a method, processTOCEvents, to do this:

public void processTOCEvents()
throws IOException
{
for(;;)
{
String str = this.getFlap();
if(str==null)
continue;
if(str.toUpperCase().startsWith("IM_IN:")) {
handleIM(str);
}
else if(str.toUpperCase().startsWith("ERROR:")){
handleError(str);
}
else{
owner.unknown(str);
}
}
}

As you can see, this code is an endless loop. This method is intended to be run as a background thread. This is the approach taken by the example client presented with this article. As instant messages come in through the TOC "IM_IN:" command, they're routed back to another class that's waiting for them. This class must implement the "Chatable" interface. These interfaces specify the TOC events that will be sent to a class that's using the JavaTOC class. This interface is shown here.

interface Chatable
{
public void unknown(String str);
public void error(String str,String var);
public void im(String from,String message);
}

As messages are received, they're routed to the "error" method if the event is a notification of an error. If the event is an instant message, it's sent to the "im" method. All other event types are sent to the "unknown" method. There are many other event types, and the "toc.txt" file contained with the source code defines them all. For example, this program currently doesn't work with buddy lists. Buddy list support would require the addition of buddy events.

The Example Client
An example program is provided to show how to use the JavaTOC class. It implements a simple AIM-compatible client that doesn't support buddy lists. To start the program you must start the main class "ChatBuddies" using the command "java ChatBuddies". A JAR file named "JavaTOC.jar" is included and can be executed in order to see the example. Some computer systems allow you to simply double-click this file to execute the example.

The example program (shown in Figure 2) is implemented using three Swing "JFrame"-derived objects. The main frame used is the "ChatBuddies" class. This class would normally be where a buddy list would be. Instead, it displays an input field that allows you to specify the screen name of the person you're sending the message to. Clicking OK will launch the "ChatWindow" frame, which is the typical instant messenger-type chat window. If you're talking to more than one person at a time, multiple windows are displayed.

The "ChatBuddies" class contains the background thread that processes all TOC events by calling the "processTOCEvents" method of the "JavaTOC". The "run" method of this thread is shown here.

public void run()
{
try {
if(toc.login(login.userID.getText(),login.password.getText())){
this.setVisible(true);
this.setTitle("Logged in: " + login.userID.getText());
login.setVisible(false);
}
else
return;
toc.processTOCEvents();
}
catch(Exception e)
{
}
}

First the user is logged in. If the login fails, a TOC error event will occur and be displayed by the "processTOCEvents" method. This background thread handles all incoming messages.

Conclusion
A lot can be done with instant messaging technology. By using the Java code provided in this article, you can write instant messaging-enabled programs. This code implemented a client. It's also possible to write server type applications that wait for connections and provide data. An example of this would be a program that sends an instant message to indicate something failed on a server.

The example program provided here is not a complete instant message application. Adding such features as a buddy list, HTML, and saved configurations would greatly enhance its usability. Yet, despite these limitations, it shows the fundamentals of how to work with AOL's instant message architecture.

References