OSCAR Protocol

This document is covered under the documented license and terms.

The OSCAR protocol specification lets developers build libraries and clients that can speak to the AIM backend using the same protocol that official native AOL clients use. In general, we recommend that developers do not build new OSCAR libraries but instead use one of the available libraries already built, including our SDK available here. AOL does not endorse any third party library, and regardless of the library used, the client developer must meet the license requirements documented here.

This document is a work in progress; there are details and sections still missing. Please contact us about document feedback and fixes. Please note - this address is NOT for asking questions or support requests. For support questions please visit the forums.

The OSCAR protocol is a binary protocol and is transmitted in network byte order unless otherwise noted. The application protocol stack consists of TCP for networking, a FLAP layer providing framing, and SNACs representing the OSCAR protocol messages. Many of the server connections support TLS between the FLAP and TCP layer if single hop encryption is desired. In most cases, the binary data stream is formed by appending the elements described below in order with no extra padding.

There are several servers that make up the AIM backend complex.

api.screenname.aol.com
The api.screenname servers provide all the authentication web services, also knows as AOL Open Auth. The first step to an AIM session is using clientLogin to authenticate the user.
api.oscar.aol.com
The api.oscar servers provide access to all the AIM web services. For OpenAIM it provides a service discovery mechanism for a client to find the correct BOSS server to which it should connect. It also provides a redirect service for the start page and expressions page.
BOSS
The client spends the most time talking to the Basic OSCAR Service Server, or BOSS for short. The BOSS server provides all the Buddy notifications, IM routing, and general services. It also is the gateway to some of the other AIM backend servers. The client's connection to the BOSS server is very important since it defines the life of the session. If a client gets disconnected from BOSS, it is considered offline and all session state information is removed.
BART
The Buddy Art, or BART, server provides access to the client for downloading image, sound, and xml assets for expressions.

A single user can use multiple clients at the same time on the same or different devices. When building a client, or library, care should be taken to deal with a single user being online multiple times. In general, all IMs and Buddy notifications will be sent to all instances, although there are some IM routing rules that come into effect when users are away or idle.

Common Base Types

The protocol is built on top of some common base types described below; these are the building blocks for all the other datatypes and SNACs. When encoding or decoding these types, make sure to use network byte order.

Base Types

NameSizeNotes
u081 byteUnsigned byte
u162 bytesUnsigned two byte short
u324 bytesUnsigned four byte int
f324 bytesFour byte float
t704 bytesUnsigned four byte timestamp, from UNIX EPOCH
UUID16 bytesSixteen bytes that represent a UUID also known as a GUID
bloblength bytesUsed in a TLV, data type and size is defined by external values
empty0 bytesUsed in a TLV, existence of tag causes behavior, the data is ignored

String Types

In general strings are not NULL terminated and are encoded using UTF8. A string is said to be compressed if all white spaces are removed and all upper case characters are converted to lower case.

NameSizeNotes
stringdataInside of TLVs a string inherits its length from the TLV length
string08u08 + dataOne byte length followed by that many bytes of data
string16u16 + dataTwo byte length followed by that many bytes of data

Datatype: TLV

TLVs are a very common structure used in the OSCAR protocol to represent dynamically typed data. Parsers should always ignore unknown tags as to not break old clients when new protocol items are added. Possible values for tags are determined by where the TLV is in the protocol; these possible values belong to a TLV class. In the wild, the term type is sometimes used interchangeably with tag, however this document uses tag to reference the integer value associated with the TLV and type as the datatype associated with that tag.

NameTypeNotes
tagu16Numeric tag of the data, possible values are defined in the TLV class for the group of TLVs
lenu16Length in bytes of the variable data
valueblobThe data inside the TLV of len length; usually another datatype is used to represent the data - this is described in the TLV class

TLVs are usually used in an array of TLV form, allowing the protocol to easily be expanded. Having just one TLV without an array does not gain much since it only allows one item to be described. There are two common methods for adding an array of TLVs to datatypes and SNACs. An additional method also exists to add an array of TLVs to SNACs. The most common is a tlvBlock which is a u16 number of TLVs followed by that many TLVs. The less common is a tlvLBlock which instead of counting the number of TLVs, counts the size of all the TLVs. The third, which is only available in SNACs, is the tlvRestBlock which says any remaining bytes in the SNAC are TLVs.

NameSizeNotes
tlvBlocku16 + dataTwo byte number of elements, followed by that many elements
tlvLBlocku16 + dataTwo byte length of elements, followed by that many bytes of elements

UUID - Universally Unique Identifier

AIM uses UUIDs in several places to express what kind of capabilities a client has and what features it would like the server to support. The nice thing about UUIDs is there does not have to be a central registry since they are unique when created. There are many websites and tools out there that will create a UUID. UUIDs are also sometimes known as GUIDs.

UUIDs are transmitted as 16 bytes of binary data; however in documents they are written down in string form like 09460000-4C7F-11D1-8222-444553540000.

At some point it was decided that full UUIDs were too verbose for common capabilities, so AIM uses both full UUIDs and what are called "short UUIDs" or "Short Caps". A "Short Cap" is really a UUID of the form 0946XXYY-4C7F-11D1-8222-444553540000 where XXYY is the short cap. A client receives short caps if it asserts the short cap capability. If a client does not assert the short caps UUID, it will get most caps in long form. Some APIs only take UUIDs In those cases the long form of a short cap should be sent.

Client and library developers should feel free to create valid new UUIDs, just do not create new "Short Caps". If developers would like to publish their UUIDs and what they mean, we will be happy to document them here.

NameUUIDNotes
SHORT_CAPS09460000-4C7F-11D1-8222-444553540000Client support short caps
SECURE_IM09460001-4C7F-11D1-8222-444553540000Client supports SECURE_IM
XHTML_IM09460002-4C7F-11D1-8222-444553540000Client supports XHTML profile and ims instead of AOLRTF
RTCVIDEO09460101-4C7F-11D1-8222-444553540000Client supports SIP/RTP video
HAS_CAMERA09460102-4C7F-11D1-8222-444553540000Client has a camera
HAS_MICROPHONE09460103-4C7F-11D1-8222-444553540000Client has a microphone
RTCAUDIO09460104-4C7F-11D1-8222-444553540000Client supports RTCAUDIO
HOST_STATUS_TEXT_AWARE0946010A-4C7F-11D1-8222-444553540000Client supports new status message features
RTIM0946010B-4C7F-11D1-8222-444553540000Client support "see as I type" IMs
SMART_CAPS094601FF-4C7F-11D1-8222-444553540000Client only asserts caps for services it is participating in
FILE_TRANSFER09461343-4C7F-11D1-8222-444553540000File transfer
DIRECT_ICBM09461345-4C7F-11D1-8222-444553540000P2p ims
FILE_SHARING09461348-4C7F-11D1-8222-444553540000File sharing
SUPPORT_ICQ0946134D-4C7F-11D1-8222-444553540000Client supports talking to ICQ users

FLAP - Frame Layer Protocol

FLAP provides the packet framing on top of TCP or TLS layer for the OSCAR protocol. Each message sent to and from the AIM backend is encapsulated in a FLAP frame that is easily identified using a 6 byte header followed by a variable length data segment. The payload of a FLAP frame is in most cases a SNAC.

Datatype: FLAP__Header

The header contains the frame type, a sequence number, and the length of the following data segment. The sequence number is independently sequential in each direction. Packets from the server to client have one sequence number, while the packets from the client to server have a different independently increasing number. If the server receives a sequence number out of order it will terminate the connection. A common mistake is to use a u08 to represent the sequence number, which will roll over at 255 and cause the server to disconnect the client.

NameTypeNotes
startMarkeru08ASTERISK (literal ASCII ‘*’)
frameTypeu08[Class: FLAP__FRAME_TYPE] Frame type
sequenceNumberu16Initialized to a random value, increments for each send
payloadLengthu16Length of data, does not include the 6 byte header length

Class: FLAP__FRAME_TYPE

There are several different frame types, with the most common being the DATA frame.

NameValueNotes
SIGNON1Initialize the FLAP connection
DATA2Messages using the FLAP connection, usually a SNAC message
ERROR3A FLAP error - rare
SIGNOFF4Close down the FLAP connection gracefully
KEEP_ALIVE5Send a heartbeat to server to help keep connection open

Class: FLAP__MULTICONN_FLAGS

These flags control how multiple instances are handled by the servers and if current sessions need to be bumped off when a new session signs on.

NameValueNotes
OLD_CLIENT0x00Don't use
RECENT_CLIENT0x01This is a recent client that understands multiple instances
SINGLE0x03This is a recent client that understands multiple instances but does not want them

TLV Class: FLAP__SIGNON_TAGS

These tags are used in the FLAP signon frame. They appear right after the 4 byte version number.

NameTagTypeNotes
CLIENT_NAME3stringYet another client name
LOGIN_COOKIE6blobLogin cookie returned by startOSCARSession
MAJOR_VERSION23u16Client major version: (1) if the client version is "1.2.3"
MINOR_VERSION24u16Client minor version: (2) if the client version is "1.2.3"
POINT_VERSION25u16Client minor version: (3) if the client version is "1.2.3"
BUILD_NUM26u16Client build number, usually monotonically increasing
MULTICONN_FLAGS74u08[Class:FLAP__MULTICONN_FLAGS] Should almost always be 0x1
CLIENT_RECONNECT148u08Client claims it is reconnecting because it got knocked off

FLAP: FLAP__SIGNON_FRAME

On connection, the server and client each send a FLAP SIGNON frame to initialize the connection. The sequence number field should be initialized with a random value. The data portion of the frame contains a 4 byte version number, currently always 1, followed by any TLVs that are required.

NameTypeNotes
headerFLAP__HeaderFLAP header, type will be FLAP__FRAME_TYPE_SIGNON
flapVersionu32Always 1
tlvsArray of TLV length payloadLength-4[Class: FLAP__SIGNON_TAGS] TLVs

Example in hex: 2a011234000400000001

FLAP: FLAP__KEEPALIVE_FRAME

Many modern operating systems and networks come with firewalls and packet inspectors to protect the user. Unfortunately, these services and devices have proven to be buggy with long lived connections. We recommend that a client sends a FLAP KEEP_ALIVE packet to the server every minute after the connection has gone idle to help keep the connection alive. Please do not send it more often then once a minute or when the connection is not idle. There is no response to this message and a client will never receive a KEEP_ALIVE packet from the server.

NameTypeNotes
headerFLAP__HeaderFLAP header, type will be FLAP__FRAME_TYPE_KEEP_ALIVE

FLAP: FLAP__DATA_FRAME

A data frame will always just contain a single SNAC.

NameTypeNotes
headerFLAP__HeaderFLAP header, type will be FLAP__FRAME_TYPE_KEEP_DATA
snacHeaderSNAC__HeaderSNAC header
snacblobsnac described by the SNAC header

FLAP: FLAP__SIGNOFF_FRAME

This FLAP frame type is sent both to the client and server.

  • Sent to the client to tell it that it is getting bumped off gracefully. The client should NOT try to auto reconnect if it receives one of these messages.
  • Sent to the server by the client to tell it that it is going away gracefully.

NameTypeNotes
headerFLAP__HeaderFLAP header, type will be FLAP__FRAME_TYPE_SIGNOFF

SNAC - Simple Network Atomic Communication

SNACs are used to represent the protocol messages that are sent between the client and backend. The messages are separated into different categories, called foodgroups. Within each foodgroup there are different kinds of messages related to the category.

Datatype: SNAC__Header

The FLAP Header will be immediately followed by the SNAC Header that describes what type of message it is for SNAC messages sent over FLAP. The SNAC Header is a simple 10 byte header that contains the foodgroup, type, any high level flags, and the requestId. The requestId is used to link up requests and replies and can also be used to determine the direction of traffic. A client should never set the high bit of a requestId or use 0. The server will always set the high bit for its requestId unless it is a reply to a client query, in which case it will use the same requestId as the request. The flags field tells the client if for the same request there will be multiple replies and if there are any SNAC Header TLVs.

NameTypeNotes
idSNAC__IDFoodgroup and message type
flagsu16[Class: SNAC__HEADER_FLAGS] Flags
requestIdu32Used to link requests and replies

Datatype: SNAC__ID

Describes the foodgroup and type this SNAC represents

NameTypeNotes
foodgroupu16Numeric value that represents the foodgroup the SNAC is in
typeu16Numeric value that represent the SNAC type

Class: SNAC__HEADER_FLAGS

These are the flags that let the client know details about the SNAC being received.

NameValueNotes
OPT_TLV_PRESENT0x8000A tlvLBlock immediately follows the SNAC header before the rest of the fields
MORE_REPLIES_FOLLOW0x0001More replies follow this message using the same requestId; the last reply is easily detectable because it will not have this flag set

Errors

Errors are implemented in a common way for all foodgroups each having a SNAC as type 1.

Class: ERROR__CODE

Generic error codes

NameValueNotes
INVALID_SNAC1Not a known SNAC
RATE_TO_HOST2Exceed the rate limit to server
RATE_TO_CLIENT3Exceed the rate limit to the remote user
NOT_LOGGED_ON4Remote user is not logged in
SERVICE_UNAVAILABLE5Normally available but something is wrong right now
SERVICE_NOT_DEFINED6Requested a service that does not exist
OBSOLETE_SNAC7This SNAC is known no longer supported
NOT_SUPPORTED_BY_HOST8Unknown SNAC
NOT_SUPPORTED_BY_CLIENT9Remote user is on but does not support the request
REFUSED_BY_CLIENT10Message is bigger then remote client wants
RESPONSES_LOST12Something really messed up
REQUEST_DENIED13Server said user or client is not allowed to do this
BUSTED_SNAC_PAYLOAD14SNAC is too small or is not in the right format
INSUFFICIENT_RIGHTS15User or client does not have the correct rights to make the request
IN_LOCAL_PERMIT_DENY16User is trying to interact with someone blocked by their own settings
TOO_EVIL_SENDER17Sender is too evil
TOO_EVIL_RECEIVER18Receiver is too evil
USER_TEMP_UNAVAIL19User is migrating or the server is down
NO_MATCH20Item was not found
LIST_OVERFLOW21Too many items were specified in a list
REQUEST_AMBIGOUS22Host could not figure out which item to operate on
TIMEOUT26Some kind of timeout
GENERAL_FAILURE28General failure
RESTRICTED_BY_PC31Restricted by parental controls
REMOTE_RESTRICTED_BY_PC32Remote user is restricted by parental controls

TLV Class: ERROR__TAGS

These are common tags used by error SNACs.

NameTagTypeNotes
FAIL_URL4stringURL with more detail
ERROR_SUBCODE8u16Foodgroup-specific error code
ERROR_TEXT27stringString error message text
ERROR_INFO_CLSID41UUIDUUID specifying format of ERROR_INFO_DATA data
ERROR_INFO_DATA42blobExtra information describing error

Foodgroup: OSERVICE

The OSERVICE foodgroup contains basic operations and data types that are common across many of the foodgroups and even different servers. It is also used for service requests when the client needs to connect to a second server to perform some other action.

Datatype: OSERVICE__NickwInfo

Common data structure that contains a user's loginId and information about their session.

NameTypeNotes
displayIdstring08Formated loginId
evilu16Warning level of user
userAttributestlvBlock[Class: OSERVICE__NICK_INFO_TAGS] TLV Block of user attributes

TLV Class: OSERVICE__NICK_INFO_TAGS

These tags contain information about users and their server state.

NameTagTypeNotes
NICK_FLAGS1u16[Class:OSERVICE__NICK_FLAGS] Flags that represent the user's state
SIGNON_TOD3t70Signon time
IDLE_TIME4u16Idle time in minutes
MEMBER_SINCE5t70Approximation of AIM membership
REALIPADDRESS10u32Network byte order IP address
CAPS13Array of UUIDClient capabilities - if not present use the previous values received; if present but empty, clear previous values
ONLINE_TIME15u32Online time in seconds
MY_INSTANCE_NUM20u08Set in first nick info. Identifies the instance number of this client
SHORT_CAPS25Array of u16Short form of capabilities
BART_INFO29Array of BART__IDExpressions
NICK_FLAGS231Array of u08[Class:OSERVICE__NICK_FLAGS] Upper bytes of nick flags, can be any size. nickFlags = NICK_FLAG | (NICK_FLAGS2 << 16)
BUDDYFEED_TIME35t70Last Buddy Feed update time
SIG_TIME38t70Time that the profile was set
AWAY_TIME39t70Time that away was set
GEO_COUNTRY42stringTwo character country code. Sent from host to client if country is known

Class: OSERVICE__NICK_FLAGS

Bits specifying a user's characteristics; For compatibility reasons the lower 2 bytes of NICK_FLAGS are sent in the NICK_FLAGS tag, while the upper bytes are sent in the NICK_FLAGS2 tag. To form the full nick flags the client needs to combine NICK_FLAGS and NICK_FLAGS2 shifted to the left 2 bytes. NICK_FLAGS is always a u16, which NICK_FLAGS2 can be any size. Another way to express the math: nickFlags = NICK_FLAG | (NICK_FLAGS2 << 16)

NameValueNotes
UNCONFIRMED0x0001Unconfirmed account
AOL0x0004AOL user
AIM0x0010AIM user
UNAVAILABLE0x0020User is away
ICQ0x0040ICQ user; AIM bit will also be set
WIRELESS0x0080On a mobile device
IMF0x0200Using IM Forwarding
BOT0x0400Bot user
ONE_WAY_WIRELESS0x1000One way wireless device
NO_KNOCK_KNOCK0x00040000Do not display the "not on your Buddy List" knock-knock as the server took care of it or the sender is trusted
FORWARD_MOBILE0x00080000If no active instances forward to mobile

Datatype: OSERVICE__Version

Description of a foodgroup and the version of that foodgroup the client wants to use when communicating with the backend.

NameTypeNotes
foodgroupu16Foodgroup that the version represents
versionu16Version of the foodgroup implementation; should be 4 for OSERVICE, 3 for FEEDBAG, 1 for all others
tool_idu16Should be 41 for all Open AIM clients
tool_versionu16Any version number the developer would like, usually the build number

SNAC: OSERVICE__ERROR - Foodgroup:1 Type:1

Error SNAC for the OSERVICE foodgroup.

NameTypeNotes
codeu16[Class: ERROR__CODE] Error code
errorTLVsRest of SNAC array of TLV[Class: ERROR__TAGS] Optional error parameters

SNAC: OSERVICE__HOST_ONLINE - Foodgroup:1 Type:3

This is the very first SNAC sent from the server to the client after the FLAP signon frames are sent. The groups array specifies the SNAC groups supported by the server. Attempted use of any other group by the client will result in a terminated connection. In all cases, the client is not allowed to transmit any SNACs until it has received this message.

NameTypeNotes
groupsRest of SNAC array of u16All foodgroups the server supports

SNAC: OSERVICE__CLIENT_ONLINE - Foodgroup:1 Type:2

This message is sent by the client once it has initialized the server state (set preferences, Buddy Lists, locate information, capabilities) and is ready to be announced as being online by the server. The client may have used groups not in groupVersions during initialization, but once this SNAC has been received by the server, SNACs in groups not specified in groupVersions will be rejected. Other users will not see this user online until this SNAC is sent.

NameTypeNotes
groupVersionsRest of SNAC array of OSERVICE__VersionAll foodgroups the client wants to support

Rate Limiting

To protect the server and other users from abusive clients, the server implements SNAC rate limiting. Rate limiting is done with a simple formula that calculates the average time between SNACs over the last few SNACs sent from the client to the server. A client can optionally subscribe to notifications about its rates so that it can warn the user ahead of time or show UI about the rates. Even if the client does not subscribe, it will receive notifications when the rate limit has been reached and the server has started dropping SNACs. If the client continues to send SNACs, it will eventually be disconnected.

All SNACs are assigned to a Rate Class which controls the parameters to the rate limit forumla. Most SNACs are in the most lenient rate class by default, with SNACs like IM sending being in more strict classes. The rate formula is currentAvg = ((currentAvg * (windowSize -1)) + delta)/windowSize. The currentAvg falling below certain thresholds causes the server to warn the client that it is about to be rate limited or disconnected. Once a client is rate limited, its average has to fall above the clear threshold before it can start sending SNACs again.

The actual parameters for the formula are not published in this document since they can change from time to time and are different depending on the current warning level and other things. A client can average around one IM every two seconds without being rate limited.

SNAC: OSERVICE__RATE_PARAMS_QUERY - Foodgroup:1 Type:6

This SNAC is sent by the client to query for the current rate limit parameters.

This SNAC has no fields and is always empty.

Datatype: OSERVICE__Rate_Parameters

Describes the rate parameters for a single rate class.

NameTypeNotes
classIdu16Rate class being described
windowSizeu32Number of events to count
clearThresholdu32Once rate limited the average has to reach this value in order to clear
alertThresholdu32Server will tell the client it is getting close to the limit
limitThresholdu32SNACs will be dropped below this value
disconnectThresholdu32Server will disconnect below this value
currentAverageu32Current value for the class; higher is better
maxAverageu32The maximum rate value; if the current value rises about this value it should be reset
lastArrivalDeltau32Last message was received this long ago
droppingSNACsu08Is the server dropping SNACs for this rate class

Datatype: OSERVICE__Rate_Class_Members

Describes all the SNACs in a single rate class.

NameTypeNotes
idu16Rate class being described
numMembersu16Number of SNACs in this rate class
snacIdsArray of SNAC__ID length numMembersSNACs in this rate class

SNAC: OSERVICE__RATE_PARAMS_REPLY - Foodgroup:1 Type:7

Contains response to the RATE_PARAMS_QUERY. The first part of the SNAC contains the rate classes. The second part contains the list of members within each class.

NameTypeNotes
numClassesu16Number of different rate classes
rateParametersArray of OSERVICE__Rate_Parameters length numClassesControlling parameters
rateMembersArray of OSERVICE__Rate_Class_Members length numClassesWhich SNACs are in what rate class

SNAC: OSERVICE__RATE_ADD_PARAM_SUB - Foodgroup:1 Type:8

Subscribe to any rate parameter changes among the specified class IDs. If there was no prior subscription for a given class ID, an immediate notification will be queued.

NameTypeNotes
classIdsRest of SNAC array of u16Rate class IDs the to which the client wants to subscribe

SNAC: OSERVICE__RATE_DEL_PARAM_SUB - Foodgroup:1 Type:9

Cancels any rate parameter subscriptions for the specified class IDs.

NameTypeNotes
classIdsRest of SNAC array of u16Rate class IDs from which the client wants to unsubscribe

SNAC: OSERVICE__RATE_PARAM_CHANGE - Foodgroup:1 Type:10

This contains an array of class rate parameters that have changed since last query or notification. The server will also generate one of these notifications whenever the client has taken a negative transition through an alert threshold.

NameTypeNotes
rateCodeu16[Class: OSERVICE__RATE_CODE] New rate code from server
rateParametersRest of SNAC array of OSERVICE__Rate_ParametersNew rate parameters

Class: OSERVICE__RATE_CODE

These are the codes used in RATE_PARAM_CHANGE to describe the state of the rate class.

NameValueNotes
CHANGE1Rate parameters have changed
WARNING2Rate limit warning reached; if client does not slow down LIMIT state will be hit
LIMIT3Rate limit reached; if client does not slow down client will be disconnected
CLEAR4Rate limit cleared; client can send SNACs normally now

Migration

The AIM backend supports the concept of migration so AOL can perform maintenance to backend servers without effecting a user's sessions. The server will initiate the migration and tell the client it needs to migrate to a different server. The client acknowledges that it is ready to be migrated to the server. The server then tells the client where to reconnect to start its session up again.

SNAC: OSERVICE__PAUSE - Foodgroup:1 Type:11

This is sent by the server when it needs to migrate the client. The client should cease transmitting SNACs and generate a OSERVICE__PAUSE_ACK SNAC to acknowledge it is ready. If the client ignores the PAUSE it will be kicked off after a short time period.

This SNAC has no fields and is always empty.

SNAC: OSERVICE__PAUSE_ACK - Foodgroup:1 Type:12

This is sent by the client to acknowledge the receipt and processing of a OSERVICE__PAUSE SNAC request.

This SNAC has no fields and is always empty.

TLV Class: OSERVICE__MIGRATE_TAGS

These are the codes used in MIGRATE_GROUPS to describe where the client should recconnect.

NameTagTypeNotes
RECONNECT_HERE5stringIPaddress followed by optional colon and port, 10.0.0.1:5190
LOGIN_COOKIE6stringBinary opaque data
SSL_CERTNAME141stringCertname to use for SSL validation
SSL_STATE142u08[Class:OSERVICE__SERVICE_RESPONSE_SSL_STATE] SSL state

SNAC: OSERVICE__MIGRATE_GROUPS - Foodgroup:1 Type:18

This SNAC commands the client to reconnect to the server specified by the included RECONNECT_HERE TLV. The client needs to present the LOGIN_COOKIE to sign in so that it can reacquire the services which were previously PAUSE'd by the server and PAUSE_ACK'd by the client. All groups currently provided on the existing connection are migrated to the new location. The client should drop the existing connection since services will no longer be available from it.

NameTypeNotes
allGroupsu16Will be zero
tlvAuthDataRest of SNAC array of TLV[Class: OSERVICE__MIGRATE_TAGS] Information about where to reconnect

SNAC: OSERVICE__RESUME - Foodgroup:1 Type:13

In certain situations the server may abort a migration after having told the client to PAUSE. In that case, it will send this SNAC to tell the client that it is back in business.

This SNAC has no fields and is always empty.

Secondary Service Requests

There are other backend servers that a client may need to connect to for more advanced commands. To connect to a secondary server, a client sends up a SERVICE REQUEST and receives a SERVICE RESPONSE back with the connection information. The secondary servers include:

TLV Class: OSERVICE__SERVICE_REQUEST_TAGS

These are the tags the client uses to control what type of service request it wants.

NameTagTypeNotes
USE_SSL140emptyNo value; if present use SSL

Class: OSERVICE__SERVICE_RESPONSE_SSL_STATE

This describes what type of SSL connection the client and backend have.

NameValueNotes
NOT_USED0SSL is not supported or not requested for this connection
USE1SSL is being used
RESUME2SSL is being used and SSL resume is supported if desired

TLV Class: OSERVICE__SERVICE_RESPONSE_TAGS

This class provided information about where the client should connect for the service.

NameTagTypeNotes
GROUP_ID13u16Foodgroup for which this response is for
RECONNECT_HERE5stringIP address followed by optional colon and port, 10.0.0.1:5190
LOGIN_COOKIE6stringBinary opaque data
SSL_CERTNAME141stringCertname to use for SSL validation
SSL_STATE142u08[Class:OSERVICE__SERVICE_RESPONSE_SSL_STATE] SSL state

SNAC: OSERVICE__SERVICE_REQUEST - Foodgroup:1 Type:4

This SNAC requests that the specified service (foodgroup) be provided to it in a way further specified by qualifyingParameters. The server will either reject the request via an error reply or accept it and reply with a SERVICE_RESPONSE. Note that this is a request for new service; this is not like the MIGRATE case where the current FLAP connection might be dropped.

NameTypeNotes
foodgroupu16Group being requested
qualifyingParametersRest of SNAC array of TLV[Class: OSERVICE__SERVICE_REQUEST_TAGS] Modifiers for the request, such as a TLS request

SNAC: OSERVICE__SERVICE_RESPONSE - Foodgroup:1 Type:5

This SNAC contains information about connecting to the new server. It is the response from the server to a service request.

NameTypeNotes
connectInfoRest of SNAC array of TLV[Class: OSERVICE__SERVICE_RESPONSE_TAGS] How to connect to the new server

Miscellaneous

SNAC: OSERVICE__NICK_INFO_QUERY - Foodgroup:1 Type:14

This is a query to find out one's current info. The server will send a NICK_INFO_UPDATE.

This SNAC has no fields and is always empty.

SNAC: OSERVICE__NICK_INFO_UPDATE - Foodgroup:1 Type:15

This SNAC is sent by the server whenever significant parts of a user's NickwInfo change. It can also be requested by the client by sending a OSERVICE__NICK_INFO_QUERY. If more than one OSERVICE__NickwInfo is contained in this SNAC, the first entry describes the overall state of the user and is followed by entries for each online instance for the user.

NameTypeNotes
infoRest of SNAC array of OSERVICE__NickwInfoUpdated info

SNAC: OSERVICE__EVIL_NOTIFICATION - Foodgroup:1 Type:16

This is a notice that the user's evil level has changed. The NickwInfo field is optional and is only present if it is not anonymous.

NameTypeNotes
newEvilu16New evil level - max is 1000; if the value goes down then it is an update and not a evil
vilifierOSERVICE__NickwInfoOptional; user who eviled the receiver of the SNAC

SNAC: OSERVICE__IDLE_NOTIFICATION - Foodgroup:1 Type:17

This SNAC is sent by the client to inform the server of the user's idle state. A non-zero idleTime indicates that the user is idle and specifies the number of seconds since the user's last keyboard or mouse input. A zero idleTime indicates that the user is active. If the client is not capable of detecting the user's idle state it should not send this SNAC. In order to prevent excessive load on the server, the client should not send this SNAC with a non-zero idleTime more often that once every 10 minutes. Once the server receives this SNAC it will automatically increment it as time goes by.

NameTypeNotes
idleTimeu32Client's idle time when changing states

SNAC: OSERVICE__SET_NICKINFO_FIELDS - Foodgroup:1 Type:30

This allows the client to set some of the fields in NickwInfo that are sent to every client. These fields need to be reasserted after a migration. The fields that can be set include STATUS and NICK_FLAGS2 (some flags ignored).

NameTypeNotes
tlvsRest of SNAC array of TLV[Class: OSERVICE__NICK_INFO_TAGS] TLVs to set

SNAC: OSERVICE__BART_REPLY - Foodgroup:1 Type:33

This reply is used to tell the client that a BART item needs to be uploaded or changed.

NameTypeNotes
replyIdsRest of SNAC array of BART__IDBART IDs and their status on the BART server

SNAC: OSERVICE__BART_QUERY2 - Foodgroup:1 Type:34

This query sees if the BART IDs are available; OSERVICE__BART_REPLY2 is sent as a response.

NameTypeNotes
idsRest of SNAC array of BART__IDBART ids to query

SNAC: OSERVICE__BART_REPLY2 - Foodgroup:1 Type:35

This SNAC is sent on initial login about items in the personality section of the Feedbag. It is also used in response to a OSERVICE__BART_QUERY2.

NameTypeNotes
reply_idsRest of SNAC array of BART__QUERY_REPLY_IDInformation on BART IDs that were queried

Foodgroup: BUDDY

The BUDDY foodgroup is used to send clients notifications about the state of other users in their Buddy List. This can also include information about other users that the client has expressed a temporary interest in. These temporary interests are only valid for the duration of the client's session.

SNAC: BUDDY__ERROR - Foodgroup:3 Type:1

These are the error SNACs for the BUDDY foodgroup.

NameTypeNotes
codeu16[Class: ERROR__CODE] Error code
errorTLVsRest of SNAC array of TLV[Class: ERROR__TAGS] Optional error parameters

SNAC: BUDDY__RIGHTS_QUERY - Foodgroup:3 Type:2

This SNAC is optionally sent by the client to discover the client's and user's rights. This SNAC is usually sent before the OSERVICE__CLIENT_ONLINE SNAC.

NameTypeNotes
tlvsRest of SNAC array of TLV[Class: BUDDY__RIGHTS_QUERY_TAGS] Qualifying parameters for query

TLV Class: BUDDY__RIGHTS_QUERY_TAGS

These are tags the client uses to inform the server of options for the BUDDY foodgroup.

NameTagTypeNotes
FLAGS5u16[Class:BUDDY__RIGHTS_QUERY_FLAGS] Flags that govern feature support

Class: BUDDY__RIGHTS_QUERY_FLAGS

These are the flags the client uses to inform the server what kinds of features it supports.

NameValueNotes
BART_SUPPORTED0x0001Want to receive BART items
INITIAL_DEPARTS0x0002Want to receive ARRIVE/DEPART for all users on a Buddy List, even those offline
OFFLINE_BART_SUPPORTED0x0004Want to receive BART items for offline buddies, excluding location
REJECT_PENDING_BUDDIES0x0008If set and INITIAL_DEPARTS is set, use REJECT on pending buddies instead of DEPART

SNAC: BUDDY__RIGHTS_REPLY - Foodgroup:3 Type:3

This is the response the server sends to a BUDDY__RIGHTS_QUERY SNAC.

NameTypeNotes
tlvsRest of SNAC array of TLV[Class: BUDDY__RIGHTS_REPLY_TAGS] TLVs with rights information

TLV Class: BUDDY__RIGHTS_REPLY_TAGS

This class contains information from the server about the BUDDY foodgroup.

NameTagTypeNotes
MAX_BUDDIES1u16Number of loginIds the user can have on their Buddy List
MAX_WATCHERS2u16Number of online users who can simultaneously watch this user
MAX_TEMP_BUDDIES4u16Number of temporary buddies

SNAC: BUDDY__REJECT_NOTIFICATION - Foodgroup:3 Type:10

In the event that one or more of the loginIds specified in the user's Buddy List are overloaded with watchers, the "interest" expressed by our user in those nicknames may be rejected and one or more of these notifications are sent.

NameTypeNotes
loginIdsRest of SNAC array of string08Names being rejected

SNAC: BUDDY__ARRIVED - Foodgroup:3 Type:11

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 server 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 NICK_FLAGS to see if the user is online; NICK_FLAGS will be zero if offline.

NameTypeNotes
arrivedInfosRest of SNAC array of OSERVICE__NickwInfoUser's state being updated

SNAC: BUDDY__DEPARTED - Foodgroup:3 Type:12

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

NameTypeNotes
arrivedInfosRest of SNAC array of OSERVICE__NickwInfoUser's state being updated

SNAC: BUDDY__ADD_TEMP_BUDDIES - Foodgroup:3 Type:15

This SNAC adds one or more loginIds to the client's temporary Buddy List. Temporary buddies are used when the user does not want to add a loginId to their Buddy List, but the client has a desire to find out about updates in real time. For example, when IMing a user not on the Buddy List, temporary buddies are used for displaying state in the IM window. Redundant additions are ignored and if any error is encountered during the processing of the SNAC, the whole transaction is backed out -- nobody is added to the Buddy List. When the client disconnects, the temporary list is automatically cleared. If a Buddy requires authorization then an offline or REJECT SNAC will be received.

NameTypeNotes
loginIdsRest of SNAC array of string08Names to add to the list to watch

SNAC: BUDDY__DEL_TEMP_BUDDIES - Foodgroup:3 Type:16

This SNAC deletes one or more users from the client's temporary Buddy List. If any error is encountered during the processing of the SNAC, the whole transaction is backed out -- nobody is deleted from the list.

NameTypeNotes
loginIdsRest of SNAC array of string08names to remove from the list being watched

Foodgroup: PD

The PD foodgroup is used for the control of Permit/Deny settings for the user

SNAC: PD__ERROR - Foodgroup:9 Type:1

This is the error SNAC for the PD foodgroup.

NameTypeNotes
codeu16[Class: ERROR__CODE] Error code
errorTLVsRest of SNAC array of TLV[Class: ERROR__TAGS] Optional error parameters

TLV Class: PD__RIGHTS_REPLY_TAGS

This class contains information from the server about the PD foodgroup.

NameTagTypeNotes
MAX_PERMITS1u16Number of permit entries a user is allowed
MAX_DENIES2u16Number of deny entries a user is allowed
MAX_TEMP_PERMITS3u16Number of temporary permit entries a client is allowed

SNAC: PD__RIGHTS_QUERY - Foodgroup:9 Type:2

This is a query sent to the server by the client to discover what some of its rights are with respect to the PD SNAC group.

This SNAC has no fields and is always empty.

SNAC: PD__RIGHTS_REPLY - Foodgroup:9 Type:3

This SNAC is the response to the PD__RIGHTS_QUERY SNAC.

NameTypeNotes
tlvsRest of SNAC array of TLV[Class: PD__RIGHTS_REPLY_TAGS] TLVs with rights information

SNAC: PD__ADD_TEMP_PERMIT_LIST_ENTRIES - Foodgroup:9 Type:10

This SNAC adds one or more entries to the temporary permit list. A loginId in this list will bypass the Feedbag permit/deny lists and always be permitted.

NameTypeNotes
loginIdsRest of SNAC array of string08Names to add from the temporary allow list

SNAC: PD__DEL_TEMP_PERMIT_LIST_ENTRIES - Foodgroup:9 Type:11

This SNAC deletes one or more entries in the temporary permit list.

NameTypeNotes
loginIdsRest of SNAC array of string08Names to remove from the temporary allow list

Foodgroup: LOCATE

The LOCATE foodgroup allows the discovery and setting of personalization features such as AIM signatures and away messages. The AIM signature has been surfaced under many different names in AIM products, such as AIM Profile, AIM Buddy Info, and AIM Get Info.

SNAC: LOCATE__ERROR - Foodgroup:2 Type:1

This is the error SNAC for the LOCATE foodgroup.

NameTypeNotes
codeu16[Class: ERROR__CODE] Error code
errorTLVsRest of SNAC array of TLV[Class: ERROR__TAGS] Optional error parameters

TLV Class: LOCATE__RIGHTS_REPLY_TAGS

This class contains information from the server about the LOCATE foodgroup.

NameTagTypeNotes
MAX_SIG_LEN1u16Maximum signature length for this user
MAX_CAPABILITIES_LEN2u16Number of full UUID capabilities allowed
MAX_FIND_BY_EMAIL_LIST3u16Maximum number of email addresses to look up at once
MAX_CERTS_LEN4u16Largest CERT length for end to end encryption
MAX_SHORT_CAPABILITIES5u16Number of short UUID capabilities allowed

SNAC: LOCATE__RIGHTS_QUERY - Foodgroup:2 Type:2

This query is sent to the server by the client to discover what some of its rights are with respect to the PD SNAC group.

This SNAC has no fields and is always empty.

SNAC: LOCATE__RIGHTS_REPLY - Foodgroup:2 Type:3

This is the response to the LOCATE__RIGHTS_QUERY SNAC.

NameTypeNotes
tlvsRest of SNAC array of TLV[Class: LOCATE__RIGHTS_REPLY_TAGS] TLVs with rights information

TLV Class: LOCATE__TAGS

These are the possible tags for the SET_INFO and GET_INFO SNACs.

NameTagTypeNotes
SIG_TYPE1stringSignature's MIME type
SIG_DATA2stringSignature data, also called the get info profile
UNAVAILABLE_TYPE3stringAway message MIME type
UNAVAILABLE_DATA4stringAway message data
CAPABILITIES5Array of UUIDCapabilities of the client
SIG_TIME10t70Time the signature was set
UNAVAILABLE_TIME11t70Time the away message was set
SUPPORT_HOST_SIG12u08If true, enable server based profiles
HTML_INFO_TYPE13stringHost based Buddy Info MIME type
HTML_INFO_DATA14stringHost based Buddy Info data that the client should display in a browser window

SNAC: LOCATE__SET_INFO - Foodgroup:2 Type:4

The client may set SIG, UNAVAILABLE, and CAPABILITIES type and data tags with this SNAC. A tag with no data clears the SIG, UNAVAILABLE message, or CAPABILITIES.

NameTypeNotes
infoDataTLV[Class: LOCATE__TAGS] Information to set or replace - empty tags will cause that data to be cleared; tags not present will cause no change

Class: LOCATE__QUERY_TYPE

This class specified which fields the client wants returned when doing a USER INFO QUERY2.

NameValueNotes
SIG0x00000001The AIM signature
UNAVAILABLE0x00000002The away message
CAPABILITIES0x00000004CAPABILITIES UUID array; short caps will be represented in long form
CERTS0x00000008The CERT Blob
HTML_INFO0x00000400Return HTML formatted Buddy Info page

SNAC: LOCATE__USER_INFO_QUERY2 - Foodgroup:2 Type:21

This SNAC is sent by the client to perform the basic locate query on a user. A client should only use this SNAC when it needs to display information to a user and should not call on every Buddy arrive. Either a LOCATE__USER_INFO_REPLY or a LOCATE__ERROR will be generated.

NameTypeNotes
type2u32[Class: LOCATE__QUERY_TYPE] What data should be returned
loginIdstring08User for which to the information requested

SNAC: LOCATE__USER_INFO_REPLY - Foodgroup:2 Type:6

This is the usual response to a LOCATE__USER_INFO_QUERY2 SNAC.

NameTypeNotes
infoOSERVICE__NickwInfoGeneric nick with info about user
locateInfoRest of SNAC array of TLV[Class: LOCATE__TAGS] Fields requested in the query

SNAC: LOCATE__FIND_LIST_BY_EMAILS - Foodgroup:2 Type:19

This is a query sent to the server that looks up a list of users by their email address and returns one NickwInfo for each email account queried. There can be only one outstanding query at a time. The maximum number of emails is specified in the LOCATE__RIGHTS_REPLY.

  • If the user has multiple accounts online, a random full NickwInfo is returned.
  • If the user has no accounts online, a random NickwInfo with just the displayId filled in is returned.
  • If the user does not have an account, or their accounts are marked as not to be returned, then their email address is not included in the array of results. Since this is the case, it is possible to have an empty SNAC returned.

NameTypeNotes
emailsRest of SNAC array of string16List of email addresses to look up

SNAC: LOCATE__FIND_LIST_REPLYS - Foodgroup:2 Type:20

This SNAC provides the results of the LOCATE__FIND_LIST_BY_EMAILS.

NameTypeNotes
infosRest of SNAC array of LOCATE__NickwInfo_EmailInformation about all the email addresses that were queried

Datatype: LOCATE__NickwInfo_Email

This is the data structure that makes it easy to link a NickwInfo and an email address.

NameTypeNotes
infoOSERVICE__NickwInfoInfo for loginId that matched the email address
emailstring16Email address requested

Foodgroup: ICBM

ICBM, or Inter Client Basic Message, is a foodgroup focused around protocol messages that are sent between users or clients.

NameSizeNotes
ICBM__Cookie8 byteOpaque 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.

NameValueNotes
IM1Normal IM channel; all clients are expected to understand this channel
RENDEZVOUS2For rendezvous negotiations and sending data between clients

Class: ICBM__PARAMETER_FLAGS

These are flags the client uses to inform the server what kinds of features it supports for the ICBM channel.

NameValueNotes
CHANNEL_MSGS_ALLOWED0x00000001Wants ICBMs on this channel
MISSED_CALLS_ENABLED0x00000002Wants MISSED_CALLS on this channel
EVENTS_ALLOWED0x00000008Wants CLIENT_EVENTs
SMS_SUPPORTED0x00000010Aware of sending to SMS
OFFLINE_MSGS_ALLOWED0x00000100Support offline IMs; client is capable of storing and retrieving

Class: ICBM__ERROR_SUBCODE

These are subcodes used with standard errors.

NameValueNotes
REMOTE_IM_OFF1Used with NOT_LOGGED_ON
REMOTE_RESTRICTED_BY_PC2Used with NOT_LOGGED_ON; the remote side denied because of parental controls
NEED_SMS_LEGAL_TO_SEND3User tried to send a message to an SMS user and is required to accept the legal text first
SMS_WITHOUT_DISCLAIMER4Client tried to send a message to an SMS user without the character counter being displayed
SMS_COUNTRY_NOT_ALLOWED5Client tried to send a message to an SMS user but the SMS matrix said the country code combination not permitted
SMS_UNKNOWN_COUNTRY8Client tried to send to an SMS user but the server could not determine the country
CANNOT_INITIATE_IM9An IM cannot be initiated by a BOT
IM_NOT_ALLOWED10An IM is not allowed by a consumer BOT to a user
CANNOT_IM_USAGE_LIMITED11An IM is not allowed by a consumer BOT due to reaching a generic usage limit, not common
CANNOT_IM_DUSAGE_LIMITED12An IM is not allowed by a consumer BOT due to reaching the daily usage limit
CANNOT_IM_MUSAGE_LIMITED13An IM is not allowed by consumer BOT due to reaching the monthly usage limit
OFFLINE_IM_NOT_ACCEPTED14User does not accept offline IMs
OFFLINE_IM_EXCEED_MAX15Exceeded max storage limit

SNAC: ICBM__ERROR - Foodgroup:4 Type:1

This is the error SNAC for the ICBM foodgroup.

NameTypeNotes
codeu16[Class: ERROR__CODE] Error code
errorTLVsRest of SNAC array of TLV[Class: ERROR__TAGS] Optional error parameters

SNAC: ICBM__ADD_PARAMETERS - Foodgroup:4 Type:2

This SNAC is typically sent prior to sending the CLIENT_ONLINE so that the server is properly initialized with the clients' preferences, although it can be sent at any time to update the situation. The default flag settings allow everything and have missed call notifications turned on. The default values for the other values may be obtained from the server by issuing a PARAMETER_QUERY.

The minInterICBMInterval is the minimum spacing the server will allow between ICBMs sent to the client. This is used in conjunction with maxIncomingICBMLen to limit the impact that incoming ICBMs can have on the client's total available bandwidth. The "channel" field specifies to which channel these parameters apply. There are a maximum number of channel "slots" available to a client. The exact number can be obtained via a PARAMETER_QUERY. A channel number of 0 (zero) is the reserved channel number to be used to set the default parameters for all channels. Therefore, the channel 0 parameters will be applied to all channels unless channel specific parameters are supplied via the ADD_PARAMETERS call which overrides the defaults. The maximum number of slots does not apply to channel 0.

NameTypeNotes
channelu16[Class: ICBM__CHANNELS] To which channel these parameters apply, or 0 for the defaults
icbmFlagsu32[Class: ICBM__PARAMETER_FLAGS] Controlling flags
maxIncomingICBMLenu16Maximum size of an ICBM the client wants to receive; the range is from 80 to 8000
maxSourceEvilu16When receiving an ICBM, the maximum evil level of the sender; the range is from 0 to 999
maxDestinationEvilu16When sending an ICBM, the maximum evil level of destination; the range is from 0 to 999
minInterICBMIntervalu32How often the client wants to receive ICBMs in milliseconds

SNAC: ICBM__DELETE_PARAMETERS - Foodgroup:4 Type:3

These are the delete all parameters for a given channel. This action is allowed for all channels other than zero. This would typically be used if a client ran out of parameter slots and needed to free one up.

NameTypeNotes
channelu16Channel to delete the parameters set with ADD_PARAMETERS

SNAC: ICBM__PARAMETER_QUERY - Foodgroup:4 Type:4

This SNAC requests the PARAMETER_REPLY from the server. This is typically used prior to sending the CLIENT_ONLINE in order to determine the default parameter settings for all channels. It is not required.

This SNAC has no fields and is always empty.

SNAC: ICBM__PARAMETER_REPLY - Foodgroup:4 Type:5

This SNAC is sent by the server in response to a PARAMETER_QUERY - see the ADD_PARAMETERS for more information.

NameTypeNotes
maxSlotsu16Represents the maximum number of parameter slots available
icbmFlagsu32[Class: ICBM__PARAMETER_FLAGS] Controlling flags
maxIncomingICBMLenu16Maximum size of an ICBM the client wants to receive; the range is from 80 to 8000
maxSourceEvilu16When receiving an ICBM, the maximum evil level of the sender; the range is from 0 to 999
maxDestinationEvilu16When sending an ICBM, the maximum evil level of the destination; the range is from 0 to 999
minInterICBMIntervalu32How often the client wants to receive ICBMs in milliseconds

Class: ICBM__IM_SECTION_ENCODINGS

An IM can be encoded in the following different forms:

NameValueNotes
ASCII0ANSI ASCII -- ISO 646
UNICODE2ISO 10646.USC-2 Unicode
LATIN_13ISO 8859-1

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. :) Anyone remember those days?

NameTypeNotes
encodingu16[Class: ICBM__IM_SECTION_ENCODINGS] Encoding of the data
languageu16Language of the data for old clients; new clients should just use 0
datablobThe IM text; array of u16 if encoding is ICBM__IM_SECTION_ENCODINGS_UNICODE, otherwise u08

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.

NameTagTypeNotes
IM_TEXT0x0101ICBM__IM_SECTIONThe actual IM text; there can be multiple of these
IM_CAPABILITIES0x0501u08Old client support; should just be the value 1
MIME_ARRAY0x0D01u16Short caps

Class: ICBM__RENDEZVOUS_MESSAGE

This is a type of rendezvous/data message.

NameValueNotes
PROPOSE0Propose a rendezvous
CANCEL1Cancel a proposal you generated
ACCEPT2Accept a proposal someone else generated

Class: ICBM__RENDEZVOUS_CANCEL_REASONS

These are the reasons a proposal is cancelled.

NameValueNotes
UNKNOWN0Reason not specified
USER_CANCEL1Recipient user declined
TIMEOUT2Timeout
ACCEPTED_ELSEWHERE3Proposal was accepted by a different instance of the user

TLV Class: ICBM__RENDEZVOUS_TAGS

These are the tags inside the DATA TLV of the RENDEZVOUS channel in ICBM.

NameTagTypeNotes
CHANNEL1u16ICBM channel on which the rendezvous is to occur
IP_ADDR2u32IP address proposed for the rendezvous
PROPOSER_IP_ADDR3u32IP address of the proposing client
VERIFIED_IP_ADDR4u32IP address of the proposing client as seen by server; NOTE - this TLV may only be added by the server
PORT5u16Port value of the client for rendezvous
DOWNLOAD_URL6stringURL for downloading software to support the service
VERIFIED_DOWNLOAD_URL8stringSame as DOWNLOAD_URL, but added by server if the service is well known; Note - this TLV may only be added by the server
SEQUENCE_NUM10u16Identifies which proposal this is in the rendezvous conversation; the initial proposal has sequence_num 1; NOTE - this tag is required in *all* rendezvous *proposal* payloads and may only occur in proposal payloads; each proposal applying to a given rendezvous cookie increments the sequence_num by one
CANCEL_REASON11u16[Class:ICBM__RENDEZVOUS_CANCEL_REASONS] Reason for cancelling a rendezvous; this tag must be present in all RENDEZVOUS_CANCEL payloads.
INVITATION12stringText inviting the other player to join
INVITE_MIME_CHARSET13stringCharset used by the data
INVITE_MIME_LANG14stringLanguage used by the data
REQUEST_HOST_CHECK15emptyRequests that the server check caps for recipient
REQUEST_USE_ARS16emptyRequests that the Rendezvous Server be used as a transport for the data
REQUEST_SECURE17emptyRequests that SSL be used for the connection
MAX_PROTOCOL_VERSION18u16Maximum application protocol version supported
MIN_PROTOCOL_VERSION19u16Minimum application protocol version supported
COUNTER_REASON20u16Reason for a counter proposal
INVITE_MIME_TYPE21stringContent-type used by the data
IP_ADDR_XOR22u32IP_ADDR ^ 0xFFFFFFFF
PORT_XOR23u16PORT ^ 0xFFFF
ADDR_LIST24Array of string08List of "IP port" pairs to try
SESSION_ID25stringIdentifier for session
ROLLOVER_ID26stringIdentifier of session to rollover
SERVICE_DATA10001blobService specific data

Datatype: ICBM__IM_RENDEZVOUS

There are three different types of rendezvous messages - propose, cancel, and accept.

PROPOSE
This is the message that a client sends to the server to propose a rendezvous with another client. The tag values to be used in the TLV are the ones specified in RENDEZVOUS_TLV_TAGS. Proposals typically specify either a RENDEZVOUS__CHANNEL or a RENDEZVOUS_IP_ADDR/PORT pair. If neither is specified, the systems which are rendezvousing must know out-of-band how to connect to each other (e.g., a server IP_ADDR compiled into a third party client). If specifying RENDEZVOUS_IP_ADDR, the client may also specify PROPOSER_IP_ADDR which is the IP address that it identifies itself by, as found by a call to get_local_host. If PROPOSER_IP_ADDR is used, VERIFIED_IP_ADDR is added by the server before sending the RENDEZVOUS_PROPOSAL_TO_CLIENT. VERIFIED_IP_ADDR may not be specified by the client in RENDEZVOUS_PROPOSAL_TOHOST. Likewise, if DOWNLOAD_URL is specified and the service UUID matches a well known service, the server may add VERIFIED_DOWNLOAD_URL. The client may not specify VERIFIED_DOWNLOAD_URL itself.
Additionally, the client can send any tags specific to a given service as long as the tag values fall outside the reserved range defined above.
NOTE: Reserved tag values MUST be at the beginning of the TLV. The server will stop parsing the TLV as soon as it encounters the first non-reserved tag.
CANCEL
This message is sent by the sender of a RENDEZVOUS_PROPOSAL_TOCLIENT in order to indicate a desire to cancel the rendezvous. Note that due to timing issues, the cancel may arrive at the other client after the other client has acted on the rendezvous proposal. In other words, cancel is an advisory message only. The sender should take other precautions to prevent a rendezvous attempt from succeeding (e.g., shut down any systems which are listening, etc.).
ACCEPT
This message is sent by the recipient of a PROPOSE in order to indicate that it has completed the rendezvous. It may contain modifications to the original PROPOSE TLVs indicating different levels of feature support (e.g., version negotiation).

NameTypeNotes
typeu16[Class: ICBM__RENDEZVOUS_MESSAGE] What kind of rendezvous message is this
cookieICBM__CookieOpaque data generated by conversation initiator and used to link up the conversation and errors
serviceUUIDIdentifies type of data message being exchanged
paramsRest of SNAC array of TLV[Class: ICBM__RENDEZVOUS_TAGS] Message data and parameters

TLV Class: ICBM__TAGS

These are the TLV tags used in TOHOST and TOCLIENT SNACs.

NameTagTypeNotes
IM_DATA2Array 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
REQUEST_HOST_ACK3emptyHost will acknowledge this ICBM upon sending it to the destination client; this does NOT mean the destination user received it
AUTO_RESPONSE4emptyThis message is an auto response; this tag is not allowed with either the REQUEST_HOST_ACK or STORE tags
DATA5ICBM__IM_RENDEZVOUSMessage data for all other channels
STORE6emptyIf 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
WANT_EVENTS11emptyUsed in TO_CLIENT only, it is added by the server if the sender wants client events
BART13BART__IDIf desired BART items can be sent with the ICBM, the client should override the ones in NickwInfo with these
SEND_TIME22t70Time when the server received the offline IM
FRIENDLY_NAME23stringFor WIMZI this is the friendly name of the anonymous user
ANONYMOUS24emptyThis is an anonymous IM

SNAC: ICBM__CHANNEL_MSG_TOHOST - Foodgroup:4 Type:6

This is the basic inter-client message after which the group was named (Inter-Client Basic Messages). Once at the server, the SNAC is reformatted into a CHANNEL_MSG_TOCLIENT before it is sent to the destination user.

NameTypeNotes
cookieICBM__CookieOpaque data generated by conversation initiator and used to link up the conversation and errors
channelu16[Class: ICBM__CHANNELS] Channel the message is on
destLoginIdstring08Destination loginId, who should receive the message
icbmTlvsRest of SNAC array of TLV[Class: ICBM__TAGS] Message data and parameters; it must contain either the IM or DATA tag

SNAC: ICBM__CHANNEL_MSG_TOCLIENT - Foodgroup:4 Type:7

This is the CHANNEL_MSG_TOHOST after it has been reformatted by the server and sent to the destination client.

NameTypeNotes
cookieICBM__CookieOpaque data generated by conversation initiator and used to link up the conversation and errors
channelu16[Class: ICBM__CHANNELS] Channel the message is on
infoOSERVICE__NickwInfoInformation about the sender of the message
icbmTlvsTLV[Class: ICBM__TAGS] Actual message

Class: ICBM__EVIL_REQUEST_FLAGS

These are the flags that control how EVIL should work.

NameValueNotes
ANONYMOUS0x0001Do not reveal my loginId to the evilee.

SNAC: ICBM__EVIL_REQUEST - Foodgroup:4 Type:8

This requests that the specified loginId is sent an EVIL notification . If the request is marked as anonymous, less EVILing may be done. The result of the evil request is returned in an EVIL_REPLY (or an error). One may only EVIL another user if that user has "recently" sent the EVILing user a CHANNEL_MSG and the other user started the conversation. To implement this rule, the server keeps a short list of users who have recently sent messages to a given user. If the user to be EVILed has rolled off this list, or was never on it, the EVIL request is denied via ERR_REQUEST_DENIED.

NameTypeNotes
evilFlagsu16[Class: ICBM__EVIL_REQUEST_FLAGS] What kind of EVIL to perform
evilLoginIdstring08Who to try to EVIL

SNAC: ICBM__EVIL_REPLY - Foodgroup:4 Type:9

The reply tells the requester, the sender of an EVIL_REQUEST SNAC, how much EVIL, if any, was applied to the recipient and provides an updated accounting of their total EVIL if evilDeltaApplied is non-zero.

NameTypeNotes
evilDeltaAppliedu16How much EVIL was applied to the requestee
updatedEvilValueu16Requestee's new EVIL value

Class: ICBM__MISSED_CALL_REASONS

These are the reasons sent to a receiver why they could not receive an IM from a sender.

NameValueNotes
TOO_LARGE0x0001Sender's message was too large
RATE_EXCEEDED0x0002Sender exceeded the receiver's rate limit
EVIL_SENDER0x0004Message rejected because sender is EVIL
EVIL_RECEIVER0x0008Message rejected because receiver is EVIL

Datatype: ICBM__Missed_Call

This represents a single missed IM from a sender, sent to the potential receiver.

NameTypeNotes
channelu16Channel on which the missed message was
senderInfoOSERVICE__NickwInfoInformation about the sender
numMissedu16How many messages were dropped
reasonu16[Class: ICBM__MISSED_CALL_REASONS] Why the IM failed

SNAC: ICBM__MISSED_CALLS - Foodgroup:4 Type:10

When the server is unable to send one or more messages to the client, the server sends this SNAC to the client to let it know that it missed some messages ("calls"). It does this at the earliest possible time (e.g., at the first available time slot allowed by minInterICBMInterval). So if user A sends a message to user B, and the server denies sending to user B because of size, user A gets an error and user B gets a missed call.

NameTypeNotes
missedCallArrayRest of SNAC array of ICBM__Missed_CallInformation about the messages that were missed

Class: ICBM__RENDEZVOUS_NAK

Sent in ICBM__CLIENT_ERR errorInfo field

NameValueNotes
PROPOSAL_UNSUPPORTED0Proposal UUID not supported
PROPOSAL_DENIED1Not authorized, or user declined
PROPOSAL_IGNORED2DO NOT USE; 'ignores' should no-op
BUSTED_PARAMETERS3Proposal malformed
PROPOSAL_TIMED_OUT4Attempt to act on proposal (e.g. connect) timed out
ONLINE_BUT_NOT_AVAILABLE5Recipient away or busy
INSUFFICIENT_RESOURCES6Recipient had internal error
RATE_LIMITED7Recipient was ratelimited
NO_DATA8Recipient had nothing to send
VERSION_MISMATCH9Incompatible versions
SECURITY_MISMATCH10Incompatible security settings
SERVICE_SPECIFIC_REASON15Service-specific reject defined by client

Class: ICBM__CLIENT_ERRORS

The following are Inter-Client error codes.

NameValueNotes
UNSUPPORTED_CHANNEL1Receiving client does not understand the channel
BUSTED_ICBM_PAYLOAD2Receiving client thinks the payload is busted
CHANNEL_SPECIFIC_ERROR3See ICBM__RENDEZVOUS_NAK which will be inside the errorInfo for values for ICBM__CHANNEL_RENDEZVOUS

SNAC: ICBM__CLIENT_ERR - Foodgroup:4 Type:11

This is one of the few SNACs that can be sent to the server and received by a client. This is because the message is basically forwarded from the source client, to the server, to the destination client.

This SNAC may only be sent as a programmatic response to an inter-client message. It is used to indicate that there was some problem with the original message received by the sender. If this SNAC is not immediately generated as a response, the client loses the right to send it at all and attempts to send it will be rejected by the server.

As transmitted, "cookie", "channel", and "loginId" are to be those which were presented in the inter-client message being rejected. As received, "loginId" has been changed to indicate the source of the error.

It is not allowed to respond to a CLIENT_ERR SNAC with another CLIENT_ERR SNAC. Receiving a CLIENT_ERR SNAC does not grant the right to EVIL.

NameTypeNotes
cookieICBM__CookieOpaque data generated by conversation initiator and used to link up the conversation and errors
channelu16[Class: ICBM__CHANNELS] Channel the message is on
loginIdstring08Destination loginId when sending and the source loginId when received
codeu16[Class: ICBM__CLIENT_ERRORS] Error code
errorInfoblobOptional error info

TLV Class: ICBM__ACK_TLV_TAGS

These are the TLV tags used in HOST_ACK SNACs. New tags may be defined for future use

NameTagTypeNotes

SNAC: ICBM__HOST_ACK - Foodgroup:4 Type:12

This SNAC is sent by the server upon receipt of any CHANNEL_MSG_TOHOST which includes the optional REQUEST_HOST_ACK TLV. "Cookie", "channel", and "loginId" should be provided in the inter-client message being acknowledged.

NameTypeNotes
cookieICBM__CookieOpaque data generated by conversation initiator and used to link up the conversation and errors
channelu16[Class: ICBM__CHANNELS] Channel the message is on
loginIdstring08Destination loginId that should receive the message
ackTlvsRest of SNAC array of TLV[Class: ICBM__ACK_TLV_TAGS] Extra TLVs in the response

SNAC: ICBM__OFFLINE_RETRIEVE - Foodgroup:4 Type:16

This requests CHANNEL_MSG_TOCLIENT messages be generated for each of the stored ICBMs. Any message retrieved is deleted.

This SNAC has no fields and is always empty.

SNAC: ICBM__OFFLINE_RETRIEVE_REPLY - Foodgroup:4 Type:23

The server successfully processed the request to retrieve all the offline messages.

This SNAC has no fields and is always empty.

Class: ICBM__EVENTS

These are the codes used in the CLIENT_EVENT SNAC.

NameValueNotes
NONE0Default state; only sent if the user was typing but erased the message
TYPED1Indicates that the user was typing but has stopped for at least 2 seconds
TYPING2Indicates the message is being actively composed; only send once when switching to this state, do NOT send for every character
RESERVED3Reserved
CLOSED15Indicates that the user closed the IM window; can be an issue in multiple instance environments

SNAC: ICBM__CLIENT_EVENT - Foodgroup:4 Type:20

This SNAC is sent as a control message, sent by a client to inform the recipient of an event. At this time the only events defined are NONE, TYPED, and TYPING. The client should send events only after receiving a message that indicates events are desired. This is another SNAC that is both sent and received by the client.

NameTypeNotes
cookieICBM__CookieOpaque data generated by conversation initiator and used to link up the conversation and errors
channelu16[Class: ICBM__CHANNELS] Channel the message is on
loginIdstring08Destination loginId when sending and the source loginId when received
eventu16[Class: ICBM__EVENTS] What event is happening

Foodgroup: INVITE

This is the foodgroup for inviting users to join AIM.

TLV Class: INVITE__TAGS

These are the tags used when inviting a user to join the AIM service.

NameTagTypeNotes
EMAIL17stringEmail address to invite
PERSONALIZED_TEXT21stringPersonalized message to send in an invite

SNAC: INVITE__ERROR - Foodgroup:6 Type:1

This is the error SNAC for the INVITE foodgroup.

NameTypeNotes
codeu16[Class: ERROR__CODE] Error code
errorTLVsRest of SNAC array of TLV[Class: ERROR__TAGS] Optional error parameters

SNAC: INVITE__REQUEST - Foodgroup:6 Type:2

This SNAC contains a request to send an invite to join AIM to a given email address. The server will perform a lookup on the email address and if already a member will return an error.

NameTypeNotes
inviteTLVsRest of SNAC array of TLV[Class: INVITE__TAGS] Email and message to send

SNAC: REQUEST_ACK - Foodgroup:6 Type:3

This SNAC is sent in reply to a successful REQUEST.

This SNAC has no fields and is always empty.

Foodgroup: FEEDBAG

A Feedbag is the stored Buddy List and server based preferences for an AIM user. The client has direct access to manipulate the Feedbag in any way it sees fit, including corrupting it. The server has some checks in place to prevent destruction, but a client developer must be careful not to corrupt things.

Class
All the entries in the Feedbag are assigned a class, which defines the characteristics of how they should behave. The class is represented by a numeric classId with each entry.
Item
An item is a generic term that is used for any entry that can be added to a user's Feedbag. An item can be a group, a Buddy, a preference, a permit/deny entry, or anything else. All items have a name (which can be empty), a groupId, an itemId, a classId, and attributes with groupId and itemId being unique. The groupId and itemId can have values between 0 and 32767; values between 32768 and 65535 are reserved. The client is responsible for picking new groupId and itemIds.
Group
A group is a special type of item that is always represented by using an itemId of 0 and classId of GROUP. All items live inside of a group, with items that use a groupId of 0 being called in the Root Group. All group items have an ORDER attribute that describes how the items in the group should be ordered, since the order in Feedbag can be random.

Sample:

groupIditemIdclassIdNameAttributes
00GROUP(0)ORDER(200):321 10
01805DENY(3)spimmer123
04046BART(20)5BART_INFO(213): 00052b000013b9
012108PDINFO(4)PD_MODE(202): 04
PD_MASK(203): ffffffff
PD_FLAGS(204): 00000001
100GROUP(1)FriendsORDER(200): 110 147
10110BUDDY(0)ChattingChuck
10147BUDDY(0)example@example.com
3210GROUP(1)Empty GroupORDER(200):

Feedbag Implementation Notes

Basics

A Feedbag consists of zero or more items. Feedbags are interpreted by the server and the client. All strings in Feedbag are UTF8 encoded.

It is mandated that only users or the server shall delete information from the user's Feedbag. A client may not delete, or "forget", information if it does not support or recognize the information; deleting corrupt items is permitted.

For instance, a user loads a special Buddy tagging plugin on a machine at home but does not have this plugin at work. Changes made to the user's Feedbag (aka, Buddy List) at work shall not delete (or "forget") the user's Buddy tagging plugin attributes from the Feedbag.

Finally, subject to the rules outlined below, all items in the Feedbag are optional. If a client does not see an item or attribute on an item, it should adopt a sensible default. For example, if the PDINFO item is not present, the client should assume permit-all mode.

Root Group

In any Feedbag that contains groups there should exist a 'root group' that has an empty name, group id 0, item id 0, and a class id 1 (GROUP). This root group contains the group ordering in an ORDER attribute. If the root group does not exist and a group is to be added, the client should create the root group first. The Root Group should never be deleted by the client.

Note that some classes of items can only be in the root group and some classes of items can only be in regular groups. For example, buddies can only be in regular groups but permit/deny entries can only be in the root group. See the class enumerations for more information where items can exist.

Ordering of Feedbag

For a FEEDBAG__REPLY, the items in the Feedbag are guaranteed to be ordered. They are sorted by group id and then by item id. Thus, the root group is first, followed by groupless items (permits, denies, etc.), followed by the group with the lowest group id, followed by its items, followed by the next group, etc.

Display of Buddy List

A client can offer several methods for sorting the display of the Buddy List. One of the offered methods should be the "Natural Order" which is calculated by using the ORDER attribute of each group. A client should NOT use the order of items in the Feedbag for display, since the items can be in random order. If a user reorders their Buddy List, only the ORDER attribute needs to be changed; the itemIds should stay the same.

Naming rules

The root group must have "" for its name.

Regular groups must have unique names independent of case (e.g., if you have a group "abc", you can also have "a b c" but not "aBc"). This is the way the old client worked, so we need to keep it this way.

Items in the root group must have unique compressed names for their class (e.g., if you have an item "abc" with class==PERMIT, you cannot have "aBc" or "a b c" with class==PERMIT, but you could have "abc" with class==DENY).

Classes limited to a single item, such as Buddy-prefs and pdinfo, should have "" for the name of the item.

Items in groups must have unique compressed names in the group (e.g., if you have a Buddy "abc" in a group, you cannot have a Buddy "a bc").

Preventing corruption

In an effort to prevent corruption of the order attribute, when the client adds a Buddy/group, the client should only send the INSERT/UPDATE for the group/root after the INSERT for the Buddy/group returns its STATUS. This way if there is a failure, the ORDER can be fixed before it is sent in the INSERT/UPDATE. In cases where a group and a Buddy are added, this can mean sending the Buddy INSERT, waiting for the STATUS, sending the group INSERT, waiting for the STATUS, then sending the root INSERT/UPDATE.

Optimizations

The client should strive to optimize its transactions with the server. This means that even if several item attributes are changed by the user, the client should send only one UPDATE_ITEM. Additionally, the client should avoid sending redundant transactions such as an INSERT followed by an UPDATE (the INSERT alone will be sufficient) or an INSERT followed by a DELETE (nothing should be sent), or an UPDATE followed by a DELETE (just send the DELETE).

Class: FEEDBAG__RIGHTS_QUERY_FLAGS

These are the flags used in FEEDBAG__RIGHTS_QUERY to determine how Feedbag is treated.

NameValueNotes
INTERACTION_SUPPORTED0x0001Client supports interactions
AUTHORIZATION_SUPPORTED0x0002Client supports Buddy authorization
DOMAIN_SN_SUPPORTED0x0004Client supports a@b.com
ICQ_NUM_SUPPORTED0x0008Client supports 1234567890
SMS_NUM_SUPPORTED0x0010Client supports +17035551212
ALIAS_ATTR_SUPPORTED0x0020Client supports alias attribute
SMARTGRP_SUPPORTED0x0040Client supports smart groups

TLV Class: FEEDBAG__RIGHTS_QUERY_TAGS

These are the types used in the Feedbag rights query.

NameTagTypeNotes
FLAGS11u16[Class:FEEDBAG__RIGHTS_QUERY_FLAGS] Flags that govern feature support

SNAC: FEEDBAG__ERROR - Foodgroup:19 Type:1

This is the error SNAC for the Feedbag foodgroup.

NameTypeNotes
codeu16[Class: ERROR__CODE] Error code
errorTLVsRest of SNAC array of TLV[Class: ERROR__TAGS] Optional error parameters

SNAC: FEEDBAG__RIGHTS_QUERY - Foodgroup:19 Type:2

This SNAC issues a query to the server for the client's Feedbag rights and to let the system know what kind of Feedbag support it wants. This should be called before the FEEDBAG__QUERY SNAC and before the OSERVICE__CLIENT_ONLINE. This is useful to figure out how many items are allowed for each class type.

NameTypeNotes
tlvsRest of SNAC array of TLV[Class: FEEDBAG__RIGHTS_QUERY_TAGS] Qualifying parameters

TLV Class: FEEDBAG__RIGHTS_REPLY_TAGS

This class provides information from the server about the Feedbag foodgroup.

NameTagTypeNotes
MAX_ITEM_ATTRS3u16Maximum size of all the attributes on a single item
MAX_ITEMS_BY_CLASS4Array of u16Maximum number of items per class
MAX_CLIENT_ITEMS5u16Total number of items with classId > 1024
MAX_ITEM_NAME_LEN6u16Maximum length of name in Item that the database supports
MAX_RECENT_BUDDIES7u16How many RECENT_BUDDIES are allowed
INTERACTION_BUDDIES8u16Top N interactions are buddies
INTERACTION_HALF_LIFE9u32Half life in 2^(-age/half_life) in seconds
INTERACTION_MAX_SCORE10u32Upper limit in interaction score
MAX_BUDDIES_PER_GROUP12u16How many BUDDIES are allowed per group
MAX_MEGA_BOTS13u16How many BOT BUDDIES are allowed
MAX_SMART_GROUPS14u16How many smart groups are allowed

SNAC: FEEDBAG__RIGHTS_REPLY - Foodgroup:19 Type:3

This is the response to the FEEDBAG__RIGHTS_QUERY SNAC.

NameTypeNotes
tlvsRest of SNAC array of TLV[Class: FEEDBAG__RIGHTS_REPLY_TAGS] TLVs with rights information

SNAC: FEEDBAG__QUERY - Foodgroup:19 Type:4

This SNAC is sent to query the Feedbag data stored on the server. This query only needs to be done for the initial connection and should not be done after a migration.

This SNAC has no fields and is always empty.

Datatype: FEEDBAG__INTERACTION_INFO

The server tracks the last interaction time and generates a score with time decay for a frequency display.

NameTypeNotes
lastUpdatet70The last interaction with this Buddy
scoref32The score; higher means more interactions

Class: FEEDBAG__CLASS_IDS

Class index constants:

  • (R) means items of class should only be in the root group
  • (G) means items of class should only be in regular groups
  • (B) means items of class can be anywhere

NameValueNotes
BUDDY0(G) Names for Buddy List
GROUP1(R) Group Name
PERMIT2(R) Names for Permit List
DENY3(R) Names for Deny List
PDINFO4(R) PDMODE/PDMASK/PDFLAGS
BUDDY_PREFS5(R) Buddy List preferences
NONBUDDY6(R) Users not in the Buddy List; use this to store aliases or other information for future use
CLIENT_PREFS9(R) Client-specific preferences; name is name of client, e.g., "AIM Express"
DATE_TIME15(R) Timestamp; when a record of this class is inserted or updated in the Feedbag, the server always adds a TIME_T attribute (overriding any that may have been provided) containing the current date and time (or one second greater than the old value, if required to keep the value increasing)
BART20(R) BART IDs; name is the BART Type
RB_ORDER21(R) Order attribute lists recent buddies in the least to most recently used order
PERSONALITY22(R) Collection of BART ids
AL_PROF23(R) Information about Account Linking prefrences
AL_INFO24(R) Account linking information
INTERACTION25(R) Non-Buddy interaction record
VANITY_INFO29(R) Vanity information kept at user logoff
FAVORITE_LOCATION30(R) User's favorite locations
BART_PDINFO31(R) BART PDMODE
CUSTOM_EMOTICONS36ICQ Custom Emoticons with BART_LIST attributes
MAX_PREDEFINED36Dummy value; Set to highest used ID
MIN1024(B) Values above this are valid indexes

Class: FEEDBAG__PD_MODE

The permit deny system can be in the following different modes.

NameValueNotes
PERMIT_ALL1Allow anyone
DENY_ALL2Deny everyone
PERMIT_SOME3Permit folks listed
DENY_SOME4Deny folks listed
PERMIT_ON_LIST5Allow folks on the Buddy List

Class: FEEDBAG__WEB_PD_MODE

These are the different modes that control anonymous web queries.

NameValueNotes
PD_MODE0Only show my anonymous queries on web pages when user is in Allow All or Deny Some mode [DEFAULT]
PERMIT_ALL1Permit anonymous queries always
DENY_ALL2Deny anonymous queries always

Class: FEEDBAG__PD_FLAGS

This class changes how the permit deny settings work.

NameValueNotes
APPLIES_IM0x0001The permit/deny settings should apply also to the IM permit/deny settings. If not set, the IM permit/deny settings can be different and is controlled by sending IMs to $im_off & $im_on. This is turned on for AIM users no matter the setting.
HIDE_WIRELESS0x002Hide the fact that the user is on a wireless device from other users

Class: FEEDBAG__BUDDY_PREFS

These are all the server based preferences and their defaults.

NameValueNotes
DISPLAY_LOGIN0[1] Whether or not to display Buddy List at login
DISPLAY_EBUDDY1[1] Whether or not to display the EBuddy group
PLAY_ENTER2[1] Whether or not to play a sound when a Buddy enters
PLAY_EXIT3[1] Whether or not to play a sound when a Buddy exits
VIEW_IMSTAMP4[1] Whether or not to display the timestamp in IMs
VIEW_SMILEYS5[1] Whether or not to display :) as a graphic
ACCEPT_ICONS6[1] Accept Buddy icons
RESERVED7[1] Legacy pref
KNOCK_NONAOLIMS8[1] Want knock-knocks for IMs from non-AOL users
KNOCK_NONLISTIMS9[1] Want knock-knocks for IMs from people not on your Buddy List
DISCLOSE_IDLE10[1] Let other users know if you are idle
ACCEPT_CUSTOMBART11[0] Accept non-official icons, chromes
ACCEPT_NONLISTBART12[0] Accept icon, chromes, from non-buddies (official only)
ACCEPT_BGS13[1] Accept IM window backgrounds
ACCEPT_CHROMES14[1] Accept IM window chromes
ACCEPT_BLSOUNDS15[1] Accept Buddy List arrive/depart sounds
ACCEPT_IMSOUNDS16[1] Accept IM sounds
NO_SEE_RECENT_BUDDIES17[0] Use does not see RECENT BUDDIES group
ACCEPT_SMS_LEGAL18[0] User has accepted to SMS legal agreement
ENTER_DOES_CRLF20[0] Enter does not send IM
PLAY_IM_SOUND21[1] Play sound on IM receipt
DISCLOSE_TYPING22[1] Send typing notifications
ACCEPT_SUPERICONS24[1] Accept 'super-buddies'
ACCEPT_BLRICHTEXT25[1] Display rich-text screennames in Buddy List
REDUCE_IM_SOUND26[1] Attenuate IM sounds after first sound
CONFIRM_DIRECT_IM27[1] Confirm with local user before starting DIM
ONE_TABBED_IM_WINDOW28[1] Show all IMs in one tabbed window
BUDDYINFO_ON_MOUSEOVER29[1] Popup information when mouse pauses above Buddy
DISCLOSE_BUDDY_MATCHES30[1] Let other users know if they have Buddy matches
CATCH_IMS31[0] For server use only; clients use CATCH_IMS_FOR_CLIENT
SHOW_FRIENDLY_NAME32[1] Show alias instead of screenname?
DISCLOSE_RADIO33[1] Buddies know when user listening to AOL radio
SHOW_CAPABILIITES34[1] Show capabilities in the Buddy List
SHOW_BUDDYLIST_FILTER35[1] Show Buddy List filter
SHOW_AWAY_IDLE36[1] Show away and idle buddies
SHOW_MOBILE37[1] Show mobile buddies
SORT_BUDDYLIST38[0] Keep Buddy List sorted A-Z
CATCH_IMS_FOR_CLIENT39[0] IM catcher window enabled?
NEW_MESSAGE_SMALL_NOTIFICATION40[1] show small notification after new message arrives
NO_FREQUENT_BUDDIES41[0] User does not see FREQUENT BUDDIES group
BLOG_AWAY_MESSAGES42[0] Send away messages to journals ?
BLOG_AIMSIG_MESSAGES43[0] Send AIM signature to journals ?
BLOG_NOCOMMENTS44[0] User allows comments ?
FRIEND_OF_FRIEND45[0] Allow Friend of Friend queries
FRIEND_GET_CONTACT_LIST46[0] Allow friend to get my Buddy List
COMPAD_INIT47[0] ICQ Compad Init
SEND_BUDDYFEED48[1] Send Buddy Feed; Young Teens(YT)/Kids Only(KO) - KO default to OFF
BLK_SEND_IM_WHILE_AWAY49[0] Block send IM while away
SHOW_BUDDYFEED50[1] Show What is New indicator
NO_SAVE_VANITY_INFO51[0] Do not save vanity related information (IM sent, idle, etc.)
ACCEPT_OFFLINE_IM52[1] Accept Offline IMs
SHOW_GROUPS53[0] ICQ: Show buddies in groups ?
SORT_GROUP54[1] ICQ: Sort groups ?
SHOW_OFFLINE_BUDDIES55[1] ICQ: Show/Hide Offline Buddies
EXPAND_BUDDIES56[0] ICQ: Show multiline information on some buddies
THIRD_PARTY_FEEDS57[0] BUDDY FEED: Does the owner have third party feeds
NOTIFY_RECEIVED_INVITE58[1] Notify at login about received AIMPages invitations
APF_AUTO_ACCEPT59[0] Auto accept AIMPages invitations
APF_AUTO_ACCEPT_BUDDY60[0] If APF_AUTO_ACCEPT and APF_AUTO_ACCEPT_BUDDY, auto accept invites only from buddies
BLOCK_AWAY_MSG_FEED61[0] Block feed storage for away messages
BLOCK_AIM_PROFILE_FEED62[0] Block feed storage for AIM Profiles
BLOCK_AIM_PAGES_FEED63[0] Block feed storage for AIM Pages
BLOCK_JOURNALS_FEED64[0] Block feed storage for AOL Journals
BLOCK_LOCATION_FEED65[0] Block feed storage for Location data
BLOCK_STICKIES_FEED66[0] Block feed storage for Stickies
BLOCK_UNCUT_FEED67[0] Block feed storage for Uncut video
BLOCK_LINKS_FEED68[0] Block feed storage for Interesting Links
BLOCK_AIM_BULLETIN_FEED69[0] Block feed storage for AIM Bulletins
SAVE_STATUS_MSG70[1] Save status message
APF_NOTIFY_RECEIVED_INVITE_BY_EMAIL71[0] Should email be sent when user invited ?
SHOW_OFFLINE_GRP72[1] Show Offline group
OFFLINE_GRP_COLLAPSED73[0] Offline Group is collapsed
FIRST_IM_SOUND_ONLY74[0] Only play the sound on the first IM
IMBLAST_INVITE_NOTIFY75[1] ALLOWS IMSERV invite notify message

Class: FEEDBAG__BUDALERT_MASK

Masks for when to trigger Buddy alerts or pounces

NameValueNotes
WHEN_ONLINE0x0001Trigger when online
WHEN_NOTIDLE0x0002Trigger when no longer idle
WHEN_NOTAWAY0x0004Trigger when no longer away
DISPLAY_DIALOG0x0100Display dialog
PLAY_SOUND0x0200Play sound

TLV Class: FEEDBAG__ATTRIBUTES

The following attributes as found in TLVs of Items:

  • The range 0-99 is reserved. At this point in time the server will reject any attribute value that is less than MIN_ATTR. This is intended for later system use.
  • The range 100-199 is reserved for attributes that can only be modified by the server. Clients should not attempt to change or remove these attributes. The server will reject any attribute value that hasn't been registered in this file.
  • The range 200-299 is reserved for attributes that have special meaning and ordinarily are hidden from the client by some form of abstraction. Clients that fully understand the meaning of these attributes can modify these attributes. The server will reject any attribute value that has not been registered in this file.
  • The range 300-9999 is reserved for normal, client-modifiable attributes. The server will reject any attribute value that has not been registered in this file.
  • The range 10000-0x7fff is free for use anywhere.

NameTagTypeNotes
MIN_ATTR100emptyAnything less than this value will be rejected by the server
SHARED100emptyGROUP: this is a shared group
INVITED101emptyBUDDY: invited to join the shared group
PENDING102emptyBUDDY: pending authorization, a client can insert/delete this record, but not update
TIME_T103t70Timestamp
DENIED104emptyBUDDY: Denied authorization
RECENT_BUDDY106emptyGROUP/BUDDY: Tag to mark the group or Buddy as a recent Buddy
BOT107emptyGROUP/BUDDY: Tag to mark the group or Buddy as an auto BOT
INTERACTION109INTERACTION_INFOBUDDY: Interaction data
BOT111emptyGROUP/BUDDY: Tag to mark the group or Buddy as a mega BOT
ORDER200Array of u16BUDDY/GROUP Array of IDs, this represents order
BUDDY_PREFS201u32[Class:FEEDBAG__BUDDY_PREFS] BUDDY_PREFS: the first 32 of the Buddy List preferences
PD_MODE202u08[Class:FEEDBAG__PD_MODE] PD_MODE: permit/deny mode
PD_MASK203u32[Class:OSERVICE__NICK_FLAGS] PD_MODE: permit/deny mask, usually just 0xffffffff
PD_FLAGS204u32[Class:FEEDBAG__PD_FLAGS] PD_MODE: permit/deny flags
CLIENT_PREFS205blobCLIENT_PREFS: blob of client data; name of item should be client
BART_INFO213blobBART: opaque BART data; the item name is the string version of the BART type
BUDDY_PREFS_VALID214u32[Class:FEEDBAG__BUDDY_PREFS] BUDDY_PREFS: mask indicating which of the first 32 BUDDY_PREFS have actually been set and which are uninitialized
BUDDY_PREFS2215Array of u08[Class:FEEDBAG__BUDDY_PREFS] BUDDY_PREFS: For all prefs after the first 32, this is a growing array
BUDDY_PREFS2_VALID216Array of u08[Class:FEEDBAG__BUDDY_PREFS] BUDDY_PREFS: bitmask indicating which of BUDDY_PREFS2 have actually been set
BART_LIST217Array of BART__IDBART: array of complete BART items, the item name is the personality name
ALIAS305stringBUDDY: alias for Item
COLLAPSED308emptyGROUP: If present the group is collapsed when initially shown
EMAIL_ADDR311stringBUDDY: string for user's Email address
PHONE_NUMBER312stringBUDDY: string for user's normal phone number
CELL_PHONE_NUMBER313stringBUDDY: string for user's cell phone number
SMS_PHONE_NUMBER314stringBUDDY: string for user's SMS phone number
NOTE316stringBUDDY: string for "notes" about item
ALERT_PREFS317u16[Class:FEEDBAG__BUDALERT_MASK] BUDDY: alert prefs
IM_SENT336u32VANITY_INFO: Client read only, number of IMs sent
ONLINE_TIME337u32VANITY_INFO: Client read only, number of seconds a user is online
AWAY_MSG338u32VANITY_INFO: Client read only, number of times a user has the away message set
IM_RECEIVED339u32VANITY_INFO: Client read only, number of IMs received
BUDDYFEED_VIEW340t70BUDDY: When did I last view this person's Buddy Feed ?
WORK_PHONE_NUMBER344stringBUDDY: string for user's work phone number
OTHER_PHONE_NUMBER345stringBUDDY: string for user's other phone number
WEB_PD_MODE351u08[Class:FEEDBAG__WEB_PD_MODE] PDINFO: When to show anonymous presence

Datatype: FEEDBAG__Item

This is a single Feedbag item.

NameTypeNotes
namestring16UTF8 string of the item's name; maximum length of 97 characters
groupIdu16ID of the group of which the item is part
itemIdu16ID inside the group; if 0 then this is the definition of the group
classIdu16[Class: FEEDBAG__CLASS_IDS] ID of the class of which this item is a member
attributestlvLBlock[Class: FEEDBAG__ATTRIBUTES] All the attributes for the item; a group must contain the ORDER attribute

SNAC: FEEDBAG__REPLY - Foodgroup:19 Type:6

This is the reply to FEEDBAG_QUERY. A client will need to handle receiving multiple replies since a Feedbag might not fit in one SNAC, or the server might choose to break it up.

NameTypeNotes
numClassesu08Always 0
numItemsu16Number of items in the Feedbag
itemsArray of FEEDBAG__Item length numItemsActual items inside the users Buddy List
lastUpdatet70Most recent update time of any item in the Feedbag

SNAC: FEEDBAG__USE - Foodgroup:19 Type:7

Directs the server to use the specified stored Feedbag information. A USE Feedbag only needs to be sent on the initial connection and does not need to be sent after a migration.

This SNAC has no fields and is always empty.

SNAC: FEEDBAG__INSERT_ITEMS - Foodgroup:19 Type:8

When this SNAC is sent to the server, the client is requesting that one or more new items are added to the Feedbag.

When this SNAC is received by the client, either another client or the server has added new items to the Feedbag. A client will not receive this SNAC for items it just inserted.

NameTypeNotes
itemsRest of SNAC array of FEEDBAG__ItemItems to insert

SNAC: FEEDBAG__UPDATE_ITEMS - Foodgroup:19 Type:9

When this SNAC is sent to the server, the client is requesting to update one or more items. The client needs to pass up all the attributes for the item, not just the ones it is updating, as the server will replace them all.

When this SNAC is received by the client, either another client or the server has updated items in Feedbag. A client will not receive this SNAC for items it just updated.

NameTypeNotes
itemsRest of SNAC array of FEEDBAG__ItemItems to update

SNAC: FEEDBAG__DELETE_ITEMS - Foodgroup:19 Type:10

When this SNAC is sent to the server, the client is requesting that one or more items be deleted from the Feedbag.

When this SNAC is received by the client, either another client or the server has deleted items from Feedbag. A client will not receive this SNAC for items it just deleted.

NameTypeNotes
itemsRest of SNAC array of FEEDBAG__ItemItems to delete

Class: FEEDBAG__STATUS_CODES

These are the status codes returned from database operations.

NameValueNotes
SUCCESS0Success
DB_ERROR1Some kind of database error
NOT_FOUND2Item was not found for an update or delete
ALREADY_EXISTS3Item already exists for an insert
UNAVAILABLE5Server or database is not available
BAD_REQUEST10Request was not formed well
DB_TIME_OUT11Database timed out
OVER_ROW_LIMIT12Too many items of this class for an insert
NOT_EXECUTED13Due to other error in same request
AUTH_REQUIRED14Buddy List authorization required
BAD_LOGINID16Bad loginId
OVER_BUDDY_LIMIT17Too many buddies
INSERT_SMART_GROUP20Attempt to added a Buddy to a smart group
TIMEOUT26General timeout

SNAC: STATUS - Foodgroup:19 Type:14

These are the results of one of the insert/update/delete item SNACs from above. There will be a status code for each of the items in the original SNAC.

NameTypeNotes
statusesRest of SNAC array of u16[Class: FEEDBAG__STATUS_CODES] Results of the operation; one for each item in original SNAC

SNAC: FEEDBAG__START_CLUSTER - Foodgroup:19 Type:17

The cluster SNACs bracket a set of transactions that should be handled by clients as a group to avoid "flashing" the user's screen. They help in cases where multiple instances are online, or when the host is making updates for the client, so the receiving client knows several changes are happening at once. These SNACs have nothing to do with the actual database transactions. In particular, non-receipt of an END_CLUSTER does not cause the database transactions to be rolled back.

NameTypeNotes
tlvsRest of SNAC array of TLVOptional qualifying parameters

SNAC: FEEDBAG__END_CLUSTER - Foodgroup:19 Type:18

See FEEDBAG__START_CLUSTER

This SNAC has no fields and is always empty.

Foodgroup: BART

BART is the system that the AIM clients use to download expressions for their buddies and themselves. Examples of BART items include Buddy icons, Buddy arrival sounds, and immersive wallpapers. For some items, the actual assets are downloaded using the BART system and in other cases, just descriptive XML files are used. Once a BART item is downloaded, it is basically cached FOREVER by the client, so updating requires publishing a new BART item. This is especially important when the BART item is an asset. When the BART item is a descriptive XML file, only the XML file is cached forever and any assets it refers to can use different caching schemes determined by the client.

All BART items are represented by a BART ID. A BART ID is a 5 byte to 20 byte binary value that represents the BART item and is sent around by the client and the servers. One simple way to think of the BART ID is as a compressed URL. When the client receives a BART ID, either from another client or from the server, it checks its cache or uses the BART server to download the item. The BART server also has a cache and connects to the various partners to download the assets if it does not have them. It is expected that each BART ID points to a unique item. The backend will collapse duplicate items into a single ID. The BART server also will store custom items for some asset types.

Having a Buddy icon with opaque data of 0x0201d20472 means the user has explicitly chosen to have no Buddy icon. This is different then not having a Buddy icon. This ID should be treated specially and does not need to be fetched from BART (although BART will return an empty GIF). This was done so clients could tell when they upgraded from old style Buddy icons to BART Buddy icons. This special ID should NOT be used for other BART types.

Class: BART__ID_FLAGS

These are the flags used by the client to detect how the BART ID should be processed.

NameValueNotes
CUSTOM0x01This is a custom blob; the opaque data will also be 16 bytes
DATA0x04The opaque field is really data the client knows how to process; these items do not need to be downloaded from BART
UNKNOWN0x40Used in OSERVICE__BART_REPLY; BART does not know about this ID, please upload
REDIRECT0x80Used in OSERVICE__BART_REPLY; BART says use this ID instead for the matching type

Class: BART__ID_TYPES

These are all the different BART ID types that are known about and their restrictions.

NameValueNotes
BUDDY_ICON_SMALL0GIF/JPG/BMP, <= 32 pixels and 2k
BUDDY_ICON1GIF/JPG/BMP, <= 64 pixels and 7k
STATUS_STR2StringTLV format; DATA flag is always set
ARRIVE_SOUND3WAV/MP3/MID, <= 10K
RICH_TEXT4byte array of rich text codes; DATA flag is always set
SUPERBUDDY_ICON5XML
RADIO_STATION6Opaque struct; DATA flag is always set
BUDDY_ICON_BIG12SWF
STATUS_STR_TOD13Time when the status string is set
CURRENT_AV_TRACK15XML file; Data flag should not be set
DEPART_SOUND96WAV/MP3/MID, <= 10K
IM_CHROME129GIF/JPG/BMP wallpaper
IM_SOUND131WAV/MP3, <= 10K
IM_CHROME_XML136XML
IM_CHROME_IMMERS137Immersive Expressions
EMOTICON_SET1024Set of default Emoticons
ENCR_CERT_CHAIN1026Cert chain for encryption certs
SIGN_CERT_CHAIN1027Cert chain for signing certs
GATEWAY_CERT1028Cert for enterprise gateway

Datatype: BART__ID

This represents a BART asset and can be thought of as a "Tiny URL" equivalent. Some BART IDs contain the data while some are pointers to the data and must be downloaded using the BART server.

NameTypeNotes
typeu16[Class: BART__ID_TYPES] Kind of asset this BART ID represents
flagsu08[Class: BART__ID_FLAGS] Any flags associated with the BART item; DATA is important since it means the BART__ID holds the data and the BART server is not needed
lenu08Length of the opaque data
opaqueArray of u08 length lenOpaque data; if the DATA flag is set then this is the actual data to use

Datatype: BART__IDs_wName

This links a BART ID and a loginId.

NameTypeNotes
loginIdstring08User who is using the asset
numIdsu08Number of assets being requested
idsArray of BART__ID length numIdsBART IDs to fetch

Datatype: BART__QUERY_REPLY_ID

This links a queried BART ID with an error code and a replyId.

NameTypeNotes
queryIdBART__IDInitial ID that is queried or used
codeu08[Class: BART__REPLY_CODES] Result code of the query
replyIdBART__IDID that will be used; might be different then queryId

Class: BART__REPLY_CODES

These are the result codes of uploads, downloads, and queries.

NameValueNotes
SUCCESS0Operation was a success
INVALID1ID is malformed
NOCUSTOM2Custom blobs are not allowed for this type
TOSMALL3Item uploaded is too small for this type
TOBIG4Item uploaded is too big for this type
INVALIDTYPE5Item uploaded is the wrong type
BANNED6Item uploaded has been banned
NOTFOUND7Item downloaded was not found

SNAC: BART__ERROR - Foodgroup:16 Type:1

This is the error SNAC for the BART foodgroup.

NameTypeNotes
codeu16[Class: ERROR__CODE] Error code
errorTLVsRest of SNAC array of TLV[Class: ERROR__TAGS] Optional error parameters

SNAC: BART__UPLOAD - Foodgroup:16 Type:2

This SNAC uploads a custom item to the BART server. Only certain types allow custom items.

NameTypeNotes
typeu16[Class: BART__ID_TYPES] Type of the item to upload
lenu16Size of the custom item
dataArray of u08 length lenCustom item

SNAC: BART__UPLOAD_REPLY - Foodgroup:16 Type:3

These are the results for an item requested with BART_UPLOAD.

NameTypeNotes
codeu08[Class: BART__REPLY_CODES] Results of the upload
idBART__IDIf success, this is the new ID for the item uploaded

SNAC: BART__DOWNLOAD2 - Foodgroup:16 Type:6

This SNAC downloads an asset from the BART server. Multiple downloads can be requested in the SNAC; however for each item, the server will respond with a separate DOWNLOAD__REPLY2.

NameTypeNotes
requestRest of SNAC array of BART__IDs_wNameItems to download

SNAC: BART__DOWNLOAD_REPLY2 - Foodgroup:16 Type:7

These are the results for an item requested with DOWNLOAD2.

NameTypeNotes
refnamestring08Name to which the asset belongs
qr_idBART__QUERY_REPLY_IDInformation about the query
lenu16Length of the asset
dataArray of u08 length lenAsset's data

Authentication

Over the years, the AIM backend has supported several different methods for authentication. The OpenAIM program only supports the clientLogin method since it makes meeting the terms requirements easier. The clientLogin method allows the client to collect the user name and password and make a simple web service call to retrieve authentication credentials. These credentials are then used in future web service calls to sign requests to help against man in the middle and reply attacks.

When a client collects the loginId and password for the user it should not normalize them in any manner. It also should not prevent the user from entering certain characters as the AIM name space is constantly changing. For example, currently the AIM name space is ASCII based, but in the future that may change. In general, the client should not perform input checking and instead allow the backend to reject bad values.

Authentication and requesting the BOSS connection normally requires two web service calls.

  1. The clientLogin call checks the key, loginId, and password and performs any rate limit or captcha challenges
  2. .
  3. The startOSCARSession call requests a BOSS connection and returns where the client needs to connect to and a one time use cookie to present to the BOSS server for authentication. This call requires an OAuth style URL signing which is described along with clientLogin.

Here is an example of the signon process:

Step #1 - Authentication Request

The client should collect the loginId and password for the user. It should not do any length or character validations. A POST web service call should be made to https://api.screenname.aol.com/auth/clientLogin?f=[FORMAT] with a POST body of k=[KEY]&s=[LOGINID]&pwd=[PASSWORD]&clientVersion=[CLIENTVERSION]&clientName=[clientName] and a content type of application/x-www-form-urlencoded where

[FORMAT]
Format to return the response in; XML, AMF3, PHP, JSON are all supported
[KEY]
Client key obtained from here
[LOGINID]
URI encoded loginId entered by the user
[PASSWORD]
URI encoded password entered by the user
[clientVersion]
A single number representing the client version number for metrics and tracking, usually the build number
[clientName]
URI encoded friendly name representing the client being used

Step #2 - Authentication Reply

There can be several intermediate replies before a successful authentication is completed. These include incorrect passwords, need for extra credentials, or the need for the user to complete a CAPTCHA challenge. To test if a client supports CAPTCHA challenges correctly it can add an extra parameter of forceRateLimit=true. It is recommended that all clients test CAPTCHA support.

When successfully authenticated, the token->a and sessionSecret need to be extracted from the results. The sessionSecret is used to generate a sessionKey that will be used on future calls. For example, the startOSCARSession service, the start page, and the expressions page all require the sessionKey.

The sessionKey is calculated using

sessionKey = hmac_sha256_base64($sessionSecret, $password);
For example, if the sessionSecret was "AB123FO" and the user's password was "weakpassword", then the sessionKey would be "ZyCaA1QlF8oBzh0QXeXNCf+7qUItBaiXwk3xOVcFZhY=" Historically some hmac_sha256_base64 do not return valid base64 data. All these APIs require valid base64 data, so check the implementation being used.

Step #3 - Start OSCAR Session Request

Once successfully authenticated, the client needs to connect to the BOSS server to start the AIM session. This is done by requesting a BOSS reservation and then connecting to the BOSS server. Requesting the BOSS reservation is done with a signed startOSCARSession WIM call. Since the URL needs to be signed, the parameters are required to be in alphabetical order.

[FORMAT]
Format to return the response in: XML, AMF3, PHP, JSON are all supported
[KEY]
Client key obtained from here
[TOKEN]
The URI encoded token extracted from clientLogin
[clientVersion]
A single number representing the client version number for metrics and tracking
[clientName]
A URI encoded friendly name representing the client being used
[TIME]
The current time, in seconds, since UNIX EPOCH
[USETLS]
Should the connection to BOSS use TLS

$uri = "https://api.oscar.aol.com/aim/startOSCARSession";
$queryString = "a=[TOKEN]&clientName=CLIENTNAME]&clientVersion=[CLIENTVERSION]&f=[FORMAT]&k=[KEY]&ts=[TIME]&useTLS=[USETLS]";
$hashData= "GET&" . uri_encode($uri) . "&" . uri_encode($queryString);
$digest = hmac_sha256_base64($hashData, $sessionKey);
$url = $uri . "?" . $queryString . "&sig_sha25sig_sha256=$digest";

Step #4 - Start OSCAR Session Reply

On a successful startOSCARSession, the backend will return where the BOSS server is running, the cookie to present to the BOSS server, and the certname that should be validated when connecting to BOSS if TLS was selected. At this point the client should connect to BOSS using FLAP or FLAP over TLS and start sending SNACs back and forth.

Single Signon to Web Pages

Many AIM web pages require authentication before they will display protected content. Since the user has already authenticated to use the AIM client, we offer a service that allows the authentication to be transfered from the client to the web page. The API requires an URL be formed using the credentials from clientLogin and the destination URL and then signed. Full documentation can be found at client2web site.

Here is a complete example of the single signon process:

Step #1 - Form the client2Web URL

Just like startOSCARSession for authentication, the client2Web URL needs to be signed. The parameters are required to be in alphabetical order since the URL needs to be signed.

[KEY]
Client key used with clientLogin - for this API the parameter is called devId instead of k
[TOKEN]
URI encoded token extracted from clientLogin
[DESTURL]
URI encoded destination URL to redirect to after establishing web authentication session
[TIME]
The current time in seconds since UNIX EPOCH

$uri = "http://my.screenname.aol.com/_cqr/login/login.psp";
$queryString = "a=[TOKEN]&destURL=[DESTURL]&devId=[KEY]&entryType=client2Web&ts=[TIME]";
$hashData= "GET&" . uri_encode($uri) . "&" . uri_encode($queryString);
$digest = hmac_sha256_base64($hashData, $sessionKey);
$url = $uri . "?" . $queryString . "&sig_sha256=$digest";

Step #2 - Launch a Browser

Using the URL from step one, launch the user's preferred browser with the URL. It is as simple as that.

AIM Start Page

Supporting the AIM Start Page is one of the available choices to meet the requirements of the terms. A client that chooses this feature must keep a local preference per loginId if the start page should be shown or not. The preference must default to on for all loginIds.

So the start page can be fully customized, we require authentication credentials to be passed using the Single Signon method described above. The client must show the start page to the user if they have not elected to turn it off.

Showing the start page is a simple operation.

  1. Form the start page URL following the instructions documented here.
  2. Use the Single Signon method described above to form the full signed URL for the browser.
  3. Launch the browser with the full URL.

Expressions Requirement

Supporting expressions is one of the available choices to meet the requirements of the terms. Both the ability to choose expressions from a web page and the ability to display at least Buddy icons is required. So the expression chooser can be fully customized, we require authentication credentials to be passed using the Single Signon method described above.

Showing the expression chooser is simple.

  1. Form the expressions URL following the instructions documented here.
  2. Use the Single Signon method described above to form the full signed URL for the browser.
  3. Launch the browser with the full URL.

Showing Buddy icons for a user requires a little more work.

Step #1 - Finding the icon for a user

First the client will need to discover what the Buddy icon BART ID is for the user. Depending on display, the client will want to look inside the NickwInfo for either the ICBM__CHANNEL_MSG_TOCLIENT SNAC or BUDDY__ARRIVED SNAC. The NickwInfo will contain an array of BART IDs and the client should select the one with the BART__ID_TYPES for which it is looking.

Step #2 - Connecting to BART

If the client is not already connected to the BART server it will need to do so.

  1. Send a OSERVICE__SERVICE_REQUEST to BOSS with the foodgroup of BART.
  2. Wait for a OSERVICE__SERVICE_RESPONSE from BOSS.
  3. Using the RECONNECT_HERE tag, connect to the BART server.
  4. Using the LOGIN_COOKIE tag send a FLAP SIGNON packet, just like connecting to BOSS.
  5. Send a OSERVICE__CLIENT_ONLINE SNAC to the BART server.

Step #3 - Downloading from BART

Once connected to BART, use the BART__DOWNLOAD2 SNAC to download as many assets as required.

Step #4 - Display Icon

Display the image.

Examples

Signon Flow

Here is a complete signon flow using example loginIds and passwords.

Step #1 - Open Auth Client Login

  1. A clientLogin POST request to log the user in.
    • URL: https://api.screenname.aol.com/auth/clientLogin?f=xml
    • POST Data:
      k=thekey&s=chattingChuck&pwd=WeakPassword&clientVersion=3&clientName=Cool+Client
  2. Assuming correct loginId, password, and no CAPTCHA challenge, a good response will look like the following:
    <response xmlns="https://api.login.aol.com">
      <statusCode>200</statusCode>
    
      <statusText>OK</statusText>
      <data>
        <token>
          <expiresIn>86400</expiresIn>
          <a>%2FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%2BE9nGhXtbQt%2BHoaa8Fw9yMTuuuks3%2F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%3D</a>
    
        </token>
        <sessionSecret>m3UPFGcH5hmKSv24</sessionSecret>
      </data>
    </response>
    
  3. Extract the token->a element and save for later.
  4. Calculate the sessionKey and save for future use, making sure to use a hmac_sha256_base64 that returns entire base64 data. After calculating the sessionKey a secure client should overwrite the memory where the password was stored.
    $sessionKey = hmac_sha256_base64("m3UPFGcH5hmKSv24", "WeakPassword");
                = "wEOki901gedaIeJbMAy5k+hv4iJgfvshgM+cWtk+s1g=";
    

Step #2 - Request BOSS Session and Connect

  1. Now that we have the session key, we can request a BOSS server connection. This involves creating a signed URL.
    $uri = "https://api.oscar.aol.com/aim/startOSCARSession";
    
    $queryString = "a=" . uri_encode("%2FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%2BE9nGhXtbQt%2BHoaa8Fw9yMTuuuks3%2F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%3D") .
                   "&clientName=" . uri_encode("Cool Client") .
                   "&clientVersion=3&f=xml&k=thekey&ts=1203799990";
                 = "a=%252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%252BE9nGhXtbQt%252BHoaa8Fw9yMTuuuks3%252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%253D&clientName=Cool%20Client&clientVersion=3&f=xml&k=thekey&ts=1203799990";
    
    $hashData= "GET&" . uri_encode($uri) . "&" . uri_encode($queryString);
             = "GET&https%3A%2F%2Fapi.oscar.aol.com%2Faim%2FstartOSCARSession&a%3D%25252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%25252BE9nGhXtbQt%25252BHoaa8Fw9yMTuuuks3%25252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%25253D%26clientName%3DCool%2520Client%26clientVersion%3D3%26f%3Dxml%26k%3Dthekey%26ts%3D1203799990"
    
    $digest = hmac_sha256_base64($hashData, $sessionKey);
            = "F2U+nrI5cJXVuTVwSOMyH3r6lhsCOspQ9J6XpLxgmAw="
    
    $url = $uri . "?" . $queryString . "&sig_sha25sig_sha256=$digest";
         = "https://api.oscar.aol.com/aim/startOSCARSession?a=%252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%252BE9nGhXtbQt%252BHoaa8Fw9yMTuuuks3%252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%253D&clientName=Cool%20Client&clientVersion=3&f=xml&k=thekey&ts=1203799990&sig_sha25sig_sha256=F2U+nrI5cJXVuTVwSOMyH3r6lhsCOspQ9J6XpLxgmAw=";
    
    
  2. Assuming no errors, a reply like the following should be received:
    <response xmlns="http://developer.aim.com/xsd/aim.xsd">
      <statusCode>200</statusCode>
      <statusText>Ok</statusText>
    
      <data>
        <host>192.168.1.1</host>
        <port>9343</port>
        <cookie>yoOR9mTV9hGH2vHNXtDytoHTu4q/yYpzkQzrs9L0GKg9ePe29nfS6J0+mIJD0ibMndzjde1AsumqQ6q+1pW95IyNHIhLxDm0PKF+aV8Mg05WZ7guQwiaNGPGXOq5qHI4kIyuVFU1kb9suwStkn+awsySalirJvTJbnbws2RqEV7MsBNF99MUJl+PEHuvEtqAAPuq0HvUGiFqPLC25D+cTYFmLMRwoQPtqIaHHAlaxo+kSWDTAKLzXGZ1JS/6Jd1p2HqPaBjCXuawVFpbwJT+DepJojJHGA4YMGh+YxM8dIfG8IH28w3/cqMZB/RDKaqZX+p0/AH4eqg34+BtYrfq/g==</cookie>
    
      </data>
    </response>
    
  3. Open a binary socket connection to the host and port.
  4. Save the base64 decoded cookie for use in the FLAP SIGNON Frame.

Step #3 - Send FLAP SIGNON Frame

  1. Once connected, the client should send a FLAP__SIGNON_FRAME with the login cookie and any version information it would like to provide.
    FieldSizeValue
    u08flapHeader.startMarker'*'
    u08flapHeader.frameType1 (FLAP__FRAME_TYPE_SIGNON)
    u16flapHeader.sequenceNumberXX
    u16flapHeader.payloadLengthYY
    u32version1
    u16tlvs[0].tag6 (FLAP__SIGNON_TAGS_LOGIN_COOKIE)
    u16tlvs[0].len256
    blobtlvs[0].valuebase64 decoded $cookie value from Step #2
    u16tlvs[1].tag74 (FLAP__SIGNON_TAGS_MULTICONN_FLAGS)
    u16tlvs[1].len1
    u08tlvs[1].value0x01
  2. It should then listen for a FLAP__SIGNON_FRAME from BOSS before continuing.
  3. Once it has received the FLAP__SIGNON_FRAME, the client can start sending SNAC messages to the server.

Step #4 - Send Rights Requests

Once the connection has been established and the FLAP signon frames have been exchanged, the client can start sending SNACs to the server. Usually the first thing the client sends are all the rights queries and a FEEDBAG__QUERY SNAC. It can and should send all these requests in parallel for a quicker login experience.

  • Query the BUDDY foodgroup rights:
    FieldSizeValue
    u08flapHeader.startMarker'*'
    u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
    u16flapHeader.sequenceNumberXX
    u16flapHeader.payloadLengthYY
    u16snacHeader.foodgroup3 (BUDDY)
    u16snacHeader.type2 (BUDDY__RIGHTS_QUERY)
    u16snacHeader.flags0
    u32snacHeader.requestIdZZ
    u16tlvs[0].tag5 (BUDDY__RIGHTS_QUERY_TAGS_FLAGS)
    u16tlvs[0].len2
    u16tlvs[0].value0xf
  • Query the PD foodgroup rights:
    FieldSizeValue
    u08flapHeader.startMarker'*'
    u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
    u16flapHeader.sequenceNumberXX
    u16flapHeader.payloadLengthYY
    u16snacHeader.foodgroup9 (PD)
    u16snacHeader.type2 (PD__RIGHTS_QUERY)
    u16snacHeader.flags0
    u32snacHeader.requestIdZZ
  • Query the LOCATE foodgroup rights:
    FieldSizeValue
    u08flapHeader.startMarker'*'
    u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
    u16flapHeader.sequenceNumberXX
    u16flapHeader.payloadLengthYY
    u16snacHeader.foodgroup2 (LOCATE)
    u16snacHeader.type2 (LOCATE__RIGHTS_QUERY)
    u16snacHeader.flags0
    u32snacHeader.requestIdZZ
  • Query the FEEDBAG foodgroup rights:
    FieldSizeValue
    u08flapHeader.startMarker'*'
    u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
    u16flapHeader.sequenceNumberXX
    u16flapHeader.payloadLengthYY
    u16snacHeader.foodgroup19 (FEEDBAG)
    u16snacHeader.type2 (FEEDBAG__RIGHTS_QUERY)
    u16snacHeader.flags0
    u32snacHeader.requestIdZZ
    u16tlvs[0].tag11 (FEEDBAG__RIGHTS_QUERY_TAGS_FLAGS)
    u16tlvs[0].len2
    u16tlvs[0].value0x7f
  • Query what the Buddy List and preferences are:
    FieldSizeValue
    u08flapHeader.startMarker'*'
    u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
    u16flapHeader.sequenceNumberXX
    u16flapHeader.payloadLengthYY
    u16snacHeader.foodgroup19 (FEEDBAG)
    u16snacHeader.type2 (FEEDBAG__QUERY)
    u16snacHeader.flags0
    u32snacHeader.requestIdZZ

Step #5 - FEEDBAG Use and Client Online

Once all the rights replies and feedbag replies are received, it is time to tell the server that the client is ready to proceed.

  • First tell the server that the feedbag looks OK and the client is ready to use it.
    FieldSizeValue
    u08flapHeader.startMarker'*'
    u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
    u16flapHeader.sequenceNumberXX
    u16flapHeader.payloadLengthYY
    u16snacHeader.foodgroup19 (FEEDBAG)
    u16snacHeader.type7 (FEEDBAG__USE)
    u16snacHeader.flags0
    u32snacHeader.requestIdZZ
  • Next we tell the client we are ready to appear online to everyone else and our version numbers.
    FieldSizeValue
    u08flapHeader.startMarker'*'
    u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
    u16flapHeader.sequenceNumberXX
    u16flapHeader.payloadLengthYY
    u16snacHeader.foodgroup1 (OSERVICE)
    u16snacHeader.type2 (OSERVICE__CLIENT_ONLINE)
    u16snacHeader.flags0
    u32snacHeader.requestIdZZ
    u16groupVersions[0].foodgroup1 (OSERVICE)
    u16groupVersions[0].version4
    u16groupVersions[0].tool_id41
    u16groupVersions[0].tool_versionAA
    u16groupVersions[1].foodgroup19 (FEEDBAG)
    u16groupVersions[1].version3
    u16groupVersions[1].tool_id41
    u16groupVersions[1].tool_versionAA
    u16groupVersions[1].foodgroup3 (BUDDY)
    u16groupVersions[1].version1
    u16groupVersions[1].tool_id41
    u16groupVersions[1].tool_versionAA
    u16groupVersions[1].foodgroup2 (LOCATE)
    u16groupVersions[1].version1
    u16groupVersions[1].tool_id41
    u16groupVersions[1].tool_versionAA
    u16groupVersions[1].foodgroup6 (INVITE)
    u16groupVersions[1].version1
    u16groupVersions[1].tool_id41
    u16groupVersions[1].tool_versionAA
    u16groupVersions[1].foodgroup4 (ICBM)
    u16groupVersions[1].version1
    u16groupVersions[1].tool_id41
    u16groupVersions[1].tool_versionAA

Step #6 - Online

The client is now considered online, visible to other users, and will start to receive BUDDY__ARRIVED for any online buddies.

Sending an IM

An IM conversation involves multiple CLIENT_EVENTS and ICBMs. CLIENT_EVENTS are used to inform the remote user what the sender is doing so the remote user knows they are still there. Here is a sample session where GabbyGrace is sending IMs to ChattingChuck.

Step #1 - Sending Typing Event

A client can optionally support sending a typing notification to the other user.

FieldSizeValue
u08flapHeader.startMarker'*'
u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
u16flapHeader.sequenceNumberXX
u16flapHeader.payloadLengthYY
u16snacHeader.foodgroup4 (ICBM)
u16snacHeader.type20 (ICBM__CLIENT_EVENT)
u16snacHeader.flags0
u32snacHeader.requestIdZZ
Array of u08cookie'12345678'
u16channel1 (ICBM__CHANNELS_IM)
u08loginId.len13
Array of u08loginId.value'ChattingChuck'
u16event2 (ICBM__EVENTS_TYPING)

Step #2 - Sending IM

FieldSizeValue
u08flapHeader.startMarker'*'
u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
u16flapHeader.sequenceNumberXX
u16flapHeader.payloadLengthYY
u16snacHeader.foodgroup4 (ICBM)
u16snacHeader.type6 (ICBM__CHANNEL_MSG_TOHOST)
u16snacHeader.flags0
u32snacHeader.requestIdZZ
Array of u08cookie'12345678'
u16channel1 (ICBM__CHANNELS_IM)
u08destLoginId.len13
Array of u08destLoginId.value'ChattingChuck'
u16icbmTlvs[0].tag3 (ICBM__TAGS_REQUEST_HOST_ACK)
u16icbmTlvs[0].len0
u16icbmTlvs[1].tag2 (ICBM__TAGS_IM_DATA)
u16icbmTlvs[1].len15
u16icbmTlvs[1].imData[0].tag0x0501 (ICBM__IM_DATA_TAGS_IM_CAPABILITIES)
u16icbmTlvs[1].imData[0].len1
u08icbmTlvs[1].imData[0].value1
u16icbmTlvs[1].imData[1].tag0x0101 (ICBM__IM_DATA_TAGS_IM_TEXT)
u16icbmTlvs[1].imData[1].len6
u16icbmTlvs[1].imData[1].encoding0 (ICBM__IM_SECTION_ENCODINGS_ASCII)
u16icbmTlvs[1].imData[1].language0
u08icbmTlvs[1].imData[1].data'Hi'

Step #3 - Receiving Typing Event

The receiving side of the client event looks identical to the sending side other then the loginId has been reversed.

FieldSizeValue
u08flapHeader.startMarker'*'
u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
u16flapHeader.sequenceNumberXX
u16flapHeader.payloadLengthYY
u16snacHeader.foodgroup4 (ICBM)
u16snacHeader.type20 (ICBM__CLIENT_EVENT)
u16snacHeader.flags0
u32snacHeader.requestIdZZ
Array of u08cookie'12345678'
u16channel1 (ICBM__CHANNELS_IM)
u08loginId.len10
Array of u08loginId.value'GabbyGrace'
u16event2 (ICBM__EVENTS_TYPING)

Step #4 - Receiving IM

FieldSizeValue
u08flapHeader.startMarker'*'
u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
u16flapHeader.sequenceNumberXX
u16flapHeader.payloadLengthYY
u16snacHeader.foodgroup4 (ICBM)
u16snacHeader.type7 (ICBM__CHANNEL_MSG_TOCLIENT)
u16snacHeader.flags0
u32snacHeader.requestIdZZ
Array of u08cookie'12345678'
u16channel1 (ICBM__CHANNELS_IM)
u08info.loginId.len10
Array of u08info.loginId.value'GabbyGrace'
u16info.evil0
u16info.attrs.num1
u16info.attrs[0].tag1 (OSERVICE__NICK_INFO_TAGS_NICK_FLAGS)
u16info.attrs[0].len2
u16info.attrs[0].value0x10
u16icbmTlvs[0].tag2 (ICBM__TAGS_IM_DATA)
u16icbmTlvs[0].len15
u16icbmTlvs[0].imData[0].tag0x0501 (ICBM__IM_DATA_TAGS_IM_CAPABILITIES)
u16icbmTlvs[0].imData[0].len1
u08icbmTlvs[0].imData[0].value1
u16icbmTlvs[0].imData[1].tag0x0101 (ICBM__IM_DATA_TAGS_IM_TEXT)
u16icbmTlvs[0].imData[1].len6
u16icbmTlvs[0].imData[1].encoding0 (ICBM__IM_SECTION_ENCODINGS_ASCII)
u16icbmTlvs[0].imData[1].language0
u08icbmTlvs[0].imData[1].data'Hi'

Buddy Info Requirement

Buddy Info is one of the available choices to meet the requirements of the terms. It is a straight forward feature to implement and most users in the target audience enjoy looking at the Buddy Info of their friends. To implement the feature, the client needs to fetch the HTML from the backend and display it in an HTML view with javascript enabled. Even if a client does not use this to meet a license requirement, we still recommend this as a high value end user feature.

Step #1 - Fetching the content

Over the BOSS connection, send a LOCATE__USER_INFO_QUERY2 SNAC with at least the HTML_INFO type2 set.

For example, to get ChattingChuck's information the following server message would be used:

FieldSizeValue
u08flapHeader.startMarker'*'
u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
u16flapHeader.sequenceNumberXX
u16flapHeader.payloadLengthYY
u16snacHeader.foodgroup2 (LOCATE)
u16snacHeader.type21 (LOCATE__USER_INFO_QUERY2)
u16snacHeader.flags0
u32snacHeader.requestIdZZ
u32type20x00000400 (LOCATE__QUERY_TYPE_HTML_INFO)
u08loginId.len13
Array of u08loginId.value'ChattingChuck'

Step #2 - Wait for the response

Wait for a response LOCATE__USER_INFO_REPLY SNAC.

For example the response for the ChattingChuck's query above might be:

FieldSizeValue
u08flapHeader.startMarker'*'
u08flapHeader.frameType2 (FLAP__FRAME_TYPE_DATA)
u16flapHeader.sequenceNumberXX
u16flapHeader.payloadLengthYY
u16snacHeader.foodgroup2 (LOCATE)
u16snacHeader.type6 (LOCATE__USER_INFO_REPLY)
u16snacHeader.flags0
u32snacHeader.requestIdZZ
u08info.displayId.len13
Array of u08info.displayId.value'ChattingChuck'
u16info.evil0
u16info.attrs.num1
u16info.attrs[0].tag1 (OSERVICE__NICK_INFO_TAGS_NICK_FLAGS)
u16info.attrs[0].len2
u16info.attrs[0].value0
u16locateInfo[0].tag13 (LOCATE__TAGS_HTML_INFO_TYPE)
u16locateInfo[0].len9
Array of u08locateInfo[0].value'text/html'
u16locateInfo[1].tag14 (LOCATE__TAGS_HTML_INFO_DATA)
u16locateInfo[1].len100
Array of u16locateInfo[1].value'<html>Stuff</html>'

Step #3 - Display the content

The client should now open (or reuse) an HTML view with javascript enabled and display the content returned inside the LOCATE__TAGS_HTML_INFO_DATA TLV.

Start Page and Expression Chooser

Displaying either the Start Page or the Expression Chooser using Single Signon is almost exactly the same. For the example the start page is used, but it is easy to substitute the Expression Chooser.

This example will use the same sessionKey and token as previous examples.

$sessionKey = "wEOki901gedaIeJbMAy5k+hv4iJgfvshgM+cWtk+s1g=";

$destUrl = uri_encode("http://api.oscar.aol.com/aim/getStartPage?f=html&language=en-us");


$uri = "http://my.screenname.aol.com/_cqr/login/login.psp";

$queryString = "a=" . uri_encode("%2FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%2BE9nGhXtbQt%2BHoaa8Fw9yMTuuuks3%2F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%3D") .
              "&destUrl=$destUrl" . 
              "&devId=thekey" .
              "&entryType=client2Web" .
              "&ts=203799990";
             = "a=%252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%252BE9nGhXtbQt%252BHoaa8Fw9yMTuuuks3%252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%253D&destUrl=http%3A%2F%2Fapi.oscar.aol.com%2Faim%2FgetStartPage%3Ff%3Dhtml%26language%3Den-us&devId=thekey&entryType=client2Web&ts=203799990"

$hashData = "GET&" . uri_encode($uri) . "&" . uri_encode($queryString);
          = "GET&http%3A%2F%2Fmy.screenname.aol.com%2F_cqr%2Flogin%2Flogin.psp&a%3D%25252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%25252BE9nGhXtbQt%25252BHoaa8Fw9yMTuuuks3%25252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%25253D%26destUrl%3Dhttp%253A%252F%252Fapi.oscar.aol.com%252Faim%252FgetStartPage%253Ff%253Dhtml%2526language%253Den-us%26devId%3Dthekey%26entryType%3Dclient2Web%26ts%3D203799990"


$digest = hmac_sha256_base64($hashData, $sessionKey);
        = "8nMlPovQqriZyPvWbftEjz+lPnQRF5A8TDcU79raYc4"

$url = $uri . "?" . $queryString . "&sig_sha256=$digest";
     = "http://my.screenname.aol.com/_cqr/login/login.psp?a=%252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%252BE9nGhXtbQt%252BHoaa8Fw9yMTuuuks3%252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%253D&destUrl=http%3A%2F%2Fapi.oscar.aol.com%2Faim%2FgetStartPage%3Ff%3Dhtml%26language%3Den-us&devId=thekey&entryType=client2Web&ts=203799990&sig_sha256=8nMlPovQqriZyPvWbftEjz+lPnQRF5A8TDcU79raYc4"