Protocols/OSCAR/SNAC/BUDDY ARRIVED

OSCAR Protocol

Introduction • Terms • Clients

Basic

Datatypes • FLAP • SNAC • TLV

UUIDs • Errors • Tool IDs

Host Interaction

Rate Limits • Migration • Messages

Other Services

ADMIN • ADVERT • ALERT

BART • BOS • BUCP • CHAT

CHAT_NAV

Tutorials

Sign On • BART • Rendezvous

ICBM • Locate • Buddies

Foodgroups

OSERVICE (0x0001)

LOCATE (0x0002)

BUDDY (0x0003)

ICBM (0x0004)

ADVERT (0x0005)

INVITE (0x0006)

ADMIN (0x0007)

POPUP (0x0008)

PD (0x0009)

USER_LOOKUP (0x000A)

STATS (0x000B)

TRANSLATE (0x000C)

CHAT_NAV (0x000D)

CHAT (0x000E)

ODIR (0x000F)

BART (0x0010)

FEEDBAG (0x0013)

ICQ (0x0015)

BUCP (0x0017)

ALERT (0x0018)

PLUGIN (0x0022)

UNNAMED_FG_24 (0x0024)

MDIR (0x0025)

ARS (0x044A)

ID	Origin	Name	Foodgroup	Service	Status	Version
0x0003, 0x000B	Host	BUDDY__ARRIVED	Unspecified	BOS	Active	1.10

This notification, potentially batched, indicates that one or more users on the client's Buddy List has signed on or updated their information.

Due to nature of the host architecture, expect redundant arrived notifications for a given user which may, or may not contain updated information. Also, offline users with status messages or BART items may be sent as "arrived", so always check the USER_FLAGS to see if the user is online; USER_FLAGS will be zero if offline.

SNAC Header

Foodgroup	uint16 (word)	00 03
Subgroup	uint16 (word)	00 0B
Flags	uint16 (word)	00 00
Request ID	uint32 (dword)	00 00 00 00

SNAC Data

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.

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:

Position	Length	Data
1	Word	0x0003
3	Word	0x000b
5	Word	0x0000
7	DWord	32-bits of seeminly gibberish
11	Byte	Oncoming Screen Name Length
12	ASCII String	Oncoming Screen Name (NOT null terminated)
13	Word	Unsigned Int containing current Warning Level of Oncoming SN
15	Word	Class (0x0004 for Free, 0x0003 for AOL)
17	Word	0x0001
19	Word	0x0002
21	Word	Class Part Two (0x0010 for Free, 0x0004 for AOL)
23	Word	0x0002
25	Word	0x0004
27	DWord	Unsigned Long (32bit) containing "Member Since" date
31	Word	0x0003
33	Word	0x0004
35	DWord	Unsigned Long (32bit) containing "On Since" date
39*	Word	0x0004
41*	Word	0x0002
43*	Word	0x0000
*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.

Name	Type	Notes
arrivedInfos	Rest of SNAC array of OSERVICE__USERINFO	User's state being updated

From Aleksandr Shutko: SNAC(03,0B) user moved online

SNAC(03,0B)  BUDDY__ARRIVED

Server sends this snac when user from your contact list goes online. Also you'll receive this snac on user status change (in this case snac doesn't contain TLV(0xC)). See also additional information about online userinfo block. 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. It's 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).  00 03   word   SNAC family  00 0B   word   SNAC subtype  00 00   word   SNAC flags  xx xx xx xx   dword   SNAC request-id   Following user info may be repeated more then once  xx   char   uin string length  xx ..   string   uin string  xx xx   word   warning level (unused in ICQ)  xx xx   word   Number of TLV in info-tlvlist  00 01   word   TLV.Type(0x01) - user class  xx xx   word   TLV.Length  xx xx   word   User class  00 0C   word   TLV.Type(0x0C) - dc info (optional)  00 25   word   TLV.Length  xx xx xx xx   dword   DC internal ip address  xx xx xx xx   dword   DC tcp port  xx   byte   DC type  xx xx   word   DC protocol version  xx xx xx xx   dword   DC auth cookie  xx xx xx xx   dword   Web front port  00 00 00 03   dword   Client futures  xx xx xx xx   dword   (id=1) last info update time (unix time_t)  xx xx xx xx   dword   (id=2) last ext info update time (i.e. icqphone status)  xx xx xx xx   dword   (id=3) last ext status update time (i.e. phonebook)  xx xx   word   unknown  00 0A   word   TLV.Type(0x0A) - external ip address  xx xx   word   TLV.Length  xx xx xx xx   dword   External client ip address  00 06   word   TLV.Type(0x06) - user status  xx xx   word   TLV.Length  xx xx xx xx   dword   User status  00 0D   word   TLV.Type(0x0D) - user capabilities  xx xx   word   TLV.Length  xx ..... xx   CLSIDs   Client capabilities list  00 0F   word   TLV.Type(0x0F) - online time  xx xx   word   TLV.Length  xx xx xx xx   dword   Client online time (in seconds)  00 03   word   TLV.Type(0x03) - signon time  xx xx   word   TLV.Length  xx xx xx xx   dword   Time when client gone online (unix time_t)  00 05   word   TLV.Type(0x05) - member since  xx xx   word   TLV.Length  xx xx xx xx   dword   Time when this account was registered  00 11   word   TLV.Type(0x11) - times updated  xx xx   word   TLV.Length  xx   byte   updated time id (1,2,3) - see above in TLV(0xC)  xx xx xx xx   dword   updated time value  ...   ...   ...  xx   byte   updated time id (1,2,3)  xx xx xx xx   dword   updated time value  00 19   word   TLV.Type(0x19) - new-style capabilities list  xx xx   word   TLV.Length  New AIM clients replacement for TLV(0x0D). Here is format description  00 1D   word   TLV.Type(0x1D) - user icon id & hash  xx xx   word   TLV.Length  xx xx   word   User icon (avatar) id  xx   byte   User icon (avatar) flags  xx   byte   User icon hash length (allways 16)  xx .. xx   array   User icon md5 hash

Example SNAC dumps with flap header:

2A 02 3E 17 00 A9 00 03 00 0B 00 00 82 95 E9 1B *.>............. 07 33 34 31 33 39 35 30 00 00 00 07 00 01 00 02 .3413950........ 00 50 00 0C 00 25 3E 4C CF 2D 00 00 4A 68 04 00 .P...%>L.-..Jh.. 08 70 7B D5 5B 00 00 00 50 00 00 00 03 3B FF E8 .p..[...P....;.. 8A 3D CF 01 51 3D CE F8 61 00 00 00 0A 00 04 3E .=..Q=..a......> 4C CF 2D 00 06 00 04 20 12 00 00 00 0D 00 40 09 L.-.... ......@. 46 13 49 4C 7F 11 D1 82 22 44 45 53 54 00 00 09 F.IL...."DEST... 46 13 4E 4C 7F 11 D1 82 22 44 45 53 54 00 00 97 F.NL...."DEST... B1 27 51 24 3C 43 34 AD 22 D6 AB F7 3F 14 92 09 .'Q$.C4."...?... 46 13 44 4C 7F 11 D1 82 22 44 45 53 54 00 00 00 F.DL...."DEST... 0F 00 04 00 00 88 B4 00 03 00 04 3D D4 42 7F ...........=.B. And one more packet with TLV(0x1D) 2A 02 26 12 00 7F 00 03 00 0B 00 00 C8 4D E4 6F *.&..........M.o 09 33 34 38 39 33 34 37 37 34 00 00 00 07 00 01 .348934774...... 00 02 00 50 00 0C 00 25 00 00 00 00 00 00 00 00 ...P...%........ 04 00 09 CD A9 3C 4C 00 00 7C 0F 00 00 00 01 00 .....<L..|...... 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0A 00 ................ 04 00 00 00 00 00 06 00 04 10 00 00 00 00 0F 00 ................ 04 00 00 03 F6 00 1D 00 14 00 01 01 10 51 BD 67 .............Q.g 50 54 3B D5 CE 72 88 14 1D A9 05 0D 70 00 03 00 PT;..r......p... 04 41 EC 78 5A .A.xZ

BUDDY SNACs

SNAC List

Subgroup Origin Name 0x0001 Any BUDDY__ERR This is the error SNAC for the BUDDY foodgroup. 0x0002 Client BUDDY__RIGHTS_QUERY This SNAC is optionally sent by the client to discover the client's and user's rights. 0x0003 Host BUDDY__RIGHTS_REPLY This is the response the host sends to a BUDDY__RIGHTS_QUERY SNAC. 0x0004 Client BUDDY__ADD_BUDDIES Add buddy or buddies to Buddy List. 0x0005 Client BUDDY__DEL_BUDDIES Remove buddy or buddies from Buddy List. 0x0006 Client BUDDY__WATCHER_LIST_QUERY Query for other users who have current user listed. 0x0007 Host BUDDY__WATCHER_LIST_RESPONSE Response to BUDDY__WATCHER_LIST_QUERY. 0x0008 Client BUDDY__WATCHER_SUB_REQUEST Watcher sub request. 0x0009 Host BUDDY__WATCHER_NOTIFICATION Watcher sub notification. 0x000A Host BUDDY__REJECT_NOTIFICATION This is sent in the event that one or more of the users specified in the user's Buddy List are overloaded with watchers. 0x000B Host BUDDY__ARRIVED This notification, potentially batched, indicates that one or more users on the client's Buddy List has signed on or updated their information. 0x000C Host BUDDY__DEPARTED This potentially batched notification indicates that one or more users on the client's Buddy List has signed off. 0x000F Client BUDDY__ADD_TEMP_BUDDIES This SNAC adds one or more users to the client's temporary Buddy List. 0x0010 Client BUDDY__DEL_TEMP_BUDDIES This SNAC deletes one or more users from the client's temporary Buddy List.