AIM/Oscar Protocol Specification: Section 5: Buddy List Management

5.0 Buddy List Management

One of the main AIM features is this function called the "Buddy List". It's analogous to the "Contacts" in ICQ terminology. Basically, at login, you send a list of screen names (supposedly, they're suppose to be the names of your friends, but that's certainly not a requirement) to the message server. These names get watched for login/logoff events, and you will get notified when these things happen.

The client has no requirements on how it needs to handle these things. You could easily send up an empty buddy list and ignore the feature entirely, but it's there, so you might as well use it. The AIM client has it's own client-side divisions of "groups". You classify your buddies into groups and it lists them on the buddy list window in that order. If they're on the list, they're online. If they're not, they're not. These divisions are truely client-side and the server only sees one unified list, that the AIM client sorts out when it gets notifications.

You get notified only on enter (oncoming) and exit (offgoing) of buddies, plus the initial "who's on" list after you send up your buddy list.

5.1 Oncoming Buddies

The "oncoming buddy" command can occur at three different times during the lifecycle of an AIM session. The first, is at the end of the login process, just after the AIM message server is notified of the contents of your buddy list (Phase 3D, Command HI). The second is if/when one of the buddies in that list comes online who wasnt' before, and the third occurs at a regular interval while the connection is otherwise idle. This third case is used for updating your buddy list to make sure you didn't miss anything before. The command syntax for all three cases is exactly the same:

Fig 5.1.1 Oncoming Buddy SNAC
7DWord32-bits of seeminly gibberish
11ByteOncoming Screen Name Length
12ASCII StringOncoming Screen Name (NOT null terminated)
13WordUnsigned Int containing current Warning Level of Oncoming SN
15WordClass (0x0004 for Free, 0x0003 for AOL)
21WordClass Part Two (0x0010 for Free, 0x0004 for AOL)
27DWordUnsigned Long (32bit) containing "Member Since" date
35DWordUnsigned Long (32bit) containing "On Since" date
*Only existant for members of the "Free" or "Trial" classes

A note about classes: Every AIM Screen Name is associated with a class. AOL members (who are really just using the AOLIM?AIM Bridge) are in the "AOL" class. Members who are using the AIM-only service are under the "Free" class. And, "Free" members who have had thier account less than thirty days or so, are in the "Trial" class.

For those who don't know what "UNIX time_t format" is, it's the format used to represent times as unsigned long's in UNIX and some DOS-based libc's. I't simply the number of seconds elapsed from the 01 January 1970 00:00:00 UTC. (This is often referred to as "the UNIX epoch".) Both of the times in this command (at positions 27 and 35) are stored in this format (and yes, these will fail because of the y2.048k bug).

Note, that there's also an "Idle for" field in this command somewhere. It may very well be the last word of the command (since I don't think you can get the idle time of an AOL member anyway). Since I've found no good way to "be idle", I can't really figure out exactly where it is.


Adam Fritzler
Last modified: Fri Jul 24 14:16:28 MST 1998