Protocols/OSCAR/Foodgroups/ICBM
| 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 | Name | Service | Status | Version |
|---|---|---|---|---|
| 0x0004 | ICBM | BOS | Active | 1.25 |
ICBM, or Inter Client Basic Message, is a foodgroup focused around protocol messages that are sent between users or clients.
So now we get to the purpose of this whole thing: messaging. Instant messages are strings of ASCII codes that get sent in very-near-real-time between users of the Basic OSCAR Service (BOS). At no time does one client directly locate another client, or even know the location of any other client. All messages are sent to the message server, which then relays them to their destination client(s).
The text of a message is usually in the form of an HTML-like encoding that AOL calls "text/x-aol-rtf" (MIME format notation). For all intents and purposes, it's a subset of HTML. But, just like with HTML, you don't have to use HTML to be HTML. Sending straight ASCII text works just fine as well. The AOL-sourced AIM clients always use HTML even if you don't type or use any. They will usually append at least the <HTML>, <BODY>, and tags (and their appropriate closing tags) even if you didn't intend to use any. The server does not touch the message at all.
Sending and receiving instant messages (from now on called IMs), is really quite simple. There are some things that can make it go funny, though. I don't have all those things documented yet.
Tutorials
Datatypes and Classes
Datatype: Cookie
| Name | Size | Notes |
|---|---|---|
| ICBM__COOKIE | 8 byte | Opaque data used to link conversations |
Class: ICBM__CHANNELS
Messages sent between users are sent on a specific channel that narrow down how they should be processed and possible rate size parameters.
| Name | Value | Notes |
|---|---|---|
| ICBM__CHANNEL_AOL_IM | 0x01 | Normal IM channel; all clients are expected to understand this channel |
| ICBM__CHANNEL_RENDEZVOUS | 0x02 | For rendezvous negotiations and sending data between clients |
| ICBM__CHANNEL_MIME | 0x03 | NOT CURRENTLY DOCUMENTED |
| ICBM__CHANNEL_ICQ | 0x04 | NOT CURRENTLY DOCUMENTED |
| ICBM__CHANNEL_COBROWSER | 0x05 | NOT CURRENTLY DOCUMENTED |
Class: ICBM__FLAGS
These are flags the client uses to inform the server what kinds of features it supports for the ICBM channel.
| Name | Value | Notes |
|---|---|---|
| ICBM__FLAG_CHANNEL_MSGS_ALLOWED | 0x00000001 | Wants ICBMs on this channel |
| ICBM__FLAG_MISSED_CALLS_ENABLED | 0x00000002 | Wants MISSED_CALLS on this channel |
| ICBM__FLAG_BLOCK_AUTH_MESSAGES | 0x00000004 | NOT CURRENTLY DOCUMENTED |
| ICBM__FLAG_EVENTS_ALLOWED | 0x00000008 | Wants CLIENT_EVENTs |
| ICBM__FLAG_SMS_SUPPORTED | 0x00000010 | Aware of sending to SMS |
| ICBM__FLAG_OFFLINE_MSGS_ALLOWED | 0x00000100 | Support offline IMs; client is capable of storing and retrieving |
TLV Class: ICBM__TAGS
These are the TLV tags used in TOHOST and TOCLIENT SNACs.
| Name | Tag | Type | Notes |
|---|---|---|---|
| ICBM__TLV_TAGS_AOL_IM_DATA | 0x02 | Array of TLV | [Class: ICBM__IM_DATA_TAGS] Message data for the IM channel only; unlike other TLVs the order of TLVs inside this tag does matter - it should be the CAPABILITIES item followed by multiple IM_TEXT items |
| ICBM__TLV_TAGS_REQUEST_HOST_ACK | 0x03 | empty | Host will acknowledge this ICBM upon sending it to the destination client; this does NOT mean the destination user received it |
| ICBM__TLV_TAGS_AUTO_RESPONSE | 0x04 | empty | This message is an auto response; this tag is not allowed with either the REQUEST_HOST_ACK or STORE tags |
| ICBM__TLV_TAGS_DATA | 0x05 | ICBM__IM_RENDEZVOUS | Message data for all other channels |
| ICBM__TLV_TAGS_STORE | 0x06 | empty | If the user is offline then store this message for delivery the next time the user logs in when possible; AIM and ICQ use complex privacy rules that control if an offline IM delivery is allowed or not |
| ICBM__TLV_TAGS_ICQBLOB | 0x07 | NOT CURRENTLY DOCUMENTED | |
| ICBM__TLV_TAGS_AVATAR_INFO | 0x08 | NOT CURRENTLY DOCUMENTED | |
| ICBM__TLV_TAGS_WANT_AVATAR | 0x09 | NOT CURRENTLY DOCUMENTED | |
| ICBM__TLV_TAGS_MULTI_USER | 0x0A | NOT CURRENTLY DOCUMENTED | |
| ICBM__TLV_TAGS_WANT_EVENTS | 0x0B | empty | Used in TO_CLIENT only, it is added by the server if the sender wants client events |
| ICBM__TLV_TAGS_SUBSCRIPTIONS | 0x0C | NOT CURRENTLY DOCUMENTED | |
| ICBM__TLV_TAGS_BART | 0x0D | BART__ID | If desired BART items can be sent with the ICBM, the client should override the ones in USERINFO with these |
| ICBM__TLV_TAGS_HOST_IM_ID | 0x10 | u32 | Unique id for host generated IMs alerting the user of some change |
| ICBM__TLV_TAGS_HOST_IM_ARGS | 0x11 | Array of string16 | String arguments used to form the host generated IM |
| ICBM__TLV_TAGS_SEND_TIME | 0x16 | t70 | Time when the server received the offline IM |
| ICBM__TLV_TAGS_FRIENDLY_NAME | 0x17 | string | For WIMZI this is the friendly name of the anonymous user |
| ICBM__TLV_TAGS_ANONYMOUS | 0x18 | empty | This is an anonymous IM |
| ICBM__TLV_TAGS_WIDGET_NAME | 0x19 | string | The name of the WIMZI widget |
Data Encoding
TLV Class: ICBM__IM_DATA_TAGS
These are the tags inside the IM_DATA TLV of an IM channel ICBM; order matters. For the IM_CHANNEL there should be one IM_CAPABILITIES followed by one or more IM_TEXT tags.
| Name | Tag | Type | Notes |
|---|---|---|---|
| ICBM__IM_DATA_TLV_TAGS_IM_TEXT | 0x0101 | ICBM__IM_SECTION | The actual IM text; there can be multiple of these |
| ICBM__IM_DATA_TLV_TAGS_IM_CAPABILITIES | 0x0501 | uint8 (byte) | Old client support; should just be the value 1 |
| ICBM__IM_DATA_TLV_TAGS_MIME_ARRAY | 0x0D01 | uint16 (word) | Short caps |
Datatype: ICBM__IM_SECTION
An IM can be broken up into multiple sections and encodings. Most clients do not do this anymore and use a single section; however old AOL clients did this to save bandwidth.
| Name | Type | Notes |
|---|---|---|
| encoding | uint16 (word) | [Class: ICBM__IM_ENCODING] Encoding of the data |
| language | uint16 (word) | Language of the data for old clients; new clients should just use 0 |
| data | blob | The IM text; array of uint16 (word) if encoding is ICBM__IM_ENCODING_UNICODE, otherwise uint8 (byte) |
Class: ICBM__IM_ENCODING
An IM can be encoded in the following different forms:
| Name | Value | Notes |
|---|---|---|
| ICBM__IM_ENCODING_ASCII | 0x00 | ANSI ASCII -- ISO 646 |
| ICBM__IM_ENCODING_UNICODE | 0x02 | ISO 10646.USC-2 Unicode |
| ICBM__IM_ENCODING_LATIN_1 | 0x03 | ISO 8859-1 |
SNACs
| Subgroup | Origin | Name |
|---|---|---|
| 0x0001 | Any | ICBM__ERR |
| This is the error SNAC for the ICBM foodgroup. | ||
| 0x0002 | Client | ICBM__ADD_PARAMETERS |
| This SNAC is typically sent prior to sending the OSERVICE__CLIENT_ONLINE so that the host is properly initialized with the clients' preferences. | ||
| 0x0003 | Client | ICBM__DEL_PARAMETERS |
| These are the delete all parameters for a given channel. | ||
| 0x0004 | Client | ICBM__PARAMETER_QUERY |
| This SNAC requests ICBM parameters from the host. | ||
| 0x0005 | Host | ICBM__PARAMETER_REPLY |
| This SNAC is sent by the host in response to a ICBM__PARAMETER_QUERY. | ||
| 0x0006 | Client | ICBM__CHANNEL_MSG_TOHOST |
| This is the basic inter-client message after which the group was named (Inter-Client Basic Messages). | ||
| 0x0007 | Host | ICBM__CHANNEL_MSG_TOCLIENT |
| This is the ICBM__CHANNEL_MSG_TOHOST after it has been reformatted by the host and sent to the destination client. | ||
| 0x0008 | Client | ICBM__EVIL_REQUEST |
| This requests that the specified user is sent an EVIL notification. | ||
| 0x0009 | Host | ICBM__EVIL_REPLY |
| The reply tells the requester, the sender of an ICBM__EVIL_REQUEST SNAC, how much EVIL, if any, was applied to the recipient. | ||
| 0x000A | Host | ICBM__MISSED_CALLS |
| When the host is unable to send one or more messages to the client, the host sends this SNAC to the client to let it know that it missed some messages ("calls"). | ||
| 0x000B | Any | ICBM__CLIENT_ERR |
| This error notice is one of the few SNACs that can be sent to the host and received by a client. | ||
| 0x000C | Host | ICBM__HOST_ACK |
| This SNAC is sent by the host upon receipt of any ICBM__CHANNEL_MSG_TOHOST which includes the optional ICBM__TLV_TAGS_REQUEST_HOST_ACK TLV. | ||
| 0x000D | NCD | ICBM__SIN_STORED |
| This is not currently documented. Want to contribute? | ||
| 0x000E | NCD | ICBM__SIN_LIST_QUERY |
| This is not currently documented. Want to contribute? | ||
| 0x000F | NCD | ICBM__SIN_LIST_REPLY |
| This is not currently documented. Want to contribute? | ||
| 0x0010 | Client | ICBM__SIN_RETRIEVE |
| This requests ICBM__CHANNEL_MSG_TOCLIENT messages be generated for each of the stored ICBMs. Any message retrieved is deleted. | ||
| 0x0011 | NCD | ICBM__SIN_DELETE |
| This is not currently documented. Want to contribute? | ||
| 0x0012 | NCD | ICBM__NOTIFY_REQUEST |
| This is not currently documented. Want to contribute? | ||
| 0x0013 | NCD | ICBM__NOTIFY_REPLY |
| This is not currently documented. Want to contribute? | ||
| 0x0014 | Any | ICBM__CLIENT_EVENT |
| This SNAC is sent as a control message, sent by a client to inform the recipient of an event, or by the host informing of an event. | ||
| 0x0017 | Host | ICBM__SIN_REPLY |
| The host successfully processed the request to retrieve all the offline messages. | ||