OSCAR Protocol

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.

• Introduction
• Datatypes
• UUIDs
• FLAP
• SNAC
• ERRORs
• Foodgroups
  • OSERVICE
    • Rate Limiting
    • Migration
    • Secondary Service Requests
    • Miscellaneous
  • PD - Permit/Deny
  • ICBM - Inter Client Basic Message
  • INVITE - Invite users to join AIM
  • BUDDY - Presence
  • FEEDBAG - Host Based Buddy List & Preferences
  • BART - Buddy Art
  • LOCATE - Get Info
• Authentication
• Single Signon to Web Pages
• Start Page Requirement
• Expressions Requirement
• Examples
  • Signon Flow
  • IM Flow
  • Buddy Info Requirement
  • Start Page and Expression Chooser

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

Name	Size	Notes
u08	1 byte	Unsigned byte
u16	2 bytes	Unsigned two byte short
u32	4 bytes	Unsigned four byte int
f32	4 bytes	Four byte float
t70	4 bytes	Unsigned four byte timestamp, from UNIX EPOCH
UUID	16 bytes	Sixteen bytes that represent a UUID also known as a GUID
blob	length bytes	Used in a TLV, data type and size is defined by external values
empty	0 bytes	Used 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.

Name	Size	Notes
string	data	Inside of TLVs a string inherits its length from the TLV length
string08	u08 + data	One byte length followed by that many bytes of data
string16	u16 + data	Two 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.

Name	Type	Notes
tag	u16	Numeric tag of the data, possible values are defined in the TLV class for the group of TLVs
len	u16	Length in bytes of the variable data
value	blob	The 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.

Name	Size	Notes
tlvBlock	u16 + data	Two byte number of elements, followed by that many elements
tlvLBlock	u16 + data	Two 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.

Name	UUID	Notes
SHORT_CAPS	09460000-4C7F-11D1-8222-444553540000	Client support short caps
SECURE_IM	09460001-4C7F-11D1-8222-444553540000	Client supports SECURE_IM
XHTML_IM	09460002-4C7F-11D1-8222-444553540000	Client supports XHTML profile and ims instead of AOLRTF
RTCVIDEO	09460101-4C7F-11D1-8222-444553540000	Client supports SIP/RTP video
HAS_CAMERA	09460102-4C7F-11D1-8222-444553540000	Client has a camera
HAS_MICROPHONE	09460103-4C7F-11D1-8222-444553540000	Client has a microphone
RTCAUDIO	09460104-4C7F-11D1-8222-444553540000	Client supports RTCAUDIO
HOST_STATUS_TEXT_AWARE	0946010A-4C7F-11D1-8222-444553540000	Client supports new status message features
RTIM	0946010B-4C7F-11D1-8222-444553540000	Client support "see as I type" IMs
SMART_CAPS	094601FF-4C7F-11D1-8222-444553540000	Client only asserts caps for services it is participating in
FILE_TRANSFER	09461343-4C7F-11D1-8222-444553540000	File transfer
DIRECT_ICBM	09461345-4C7F-11D1-8222-444553540000	P2p ims
FILE_SHARING	09461348-4C7F-11D1-8222-444553540000	File sharing
SUPPORT_ICQ	0946134D-4C7F-11D1-8222-444553540000	Client 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.

Name	Type	Notes
startMarker	u08	ASTERISK (literal ASCII ‘*’)
frameType	u08	[Class: FLAP__FRAME_TYPE] Frame type
sequenceNumber	u16	Initialized to a random value, increments for each send
payloadLength	u16	Length 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.

Name	Value	Notes
SIGNON	1	Initialize the FLAP connection
DATA	2	Messages using the FLAP connection, usually a SNAC message
ERROR	3	A FLAP error - rare
SIGNOFF	4	Close down the FLAP connection gracefully
KEEP_ALIVE	5	Send 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.

Name	Value	Notes
OLD_CLIENT	0x00	Don't use
RECENT_CLIENT	0x01	This is a recent client that understands multiple instances
SINGLE	0x03	This 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.

Name	Tag	Type	Notes
CLIENT_NAME	3	string	Yet another client name
LOGIN_COOKIE	6	blob	Login cookie returned by startOSCARSession
MAJOR_VERSION	23	u16	Client major version: (1) if the client version is "1.2.3"
MINOR_VERSION	24	u16	Client minor version: (2) if the client version is "1.2.3"
POINT_VERSION	25	u16	Client minor version: (3) if the client version is "1.2.3"
BUILD_NUM	26	u16	Client build number, usually monotonically increasing
MULTICONN_FLAGS	74	u08	[Class:FLAP__MULTICONN_FLAGS] Should almost always be 0x1
CLIENT_RECONNECT	148	u08	Client 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.

Name	Type	Notes
header	FLAP__Header	FLAP header, type will be FLAP__FRAME_TYPE_SIGNON
flapVersion	u32	Always 1
tlvs	Array 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.

Name	Type	Notes
header	FLAP__Header	FLAP header, type will be FLAP__FRAME_TYPE_KEEP_ALIVE

FLAP: FLAP__DATA_FRAME

A data frame will always just contain a single SNAC.

Name	Type	Notes
header	FLAP__Header	FLAP header, type will be FLAP__FRAME_TYPE_KEEP_DATA
snacHeader	SNAC__Header	SNAC header
snac	blob	snac 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.

Name	Type	Notes
header	FLAP__Header	FLAP 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.

Name	Type	Notes
id	SNAC__ID	Foodgroup and message type
flags	u16	[Class: SNAC__HEADER_FLAGS] Flags
requestId	u32	Used to link requests and replies

Datatype: SNAC__ID

Describes the foodgroup and type this SNAC represents

Name	Type	Notes
foodgroup	u16	Numeric value that represents the foodgroup the SNAC is in
type	u16	Numeric 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.

Name	Value	Notes
OPT_TLV_PRESENT	0x8000	A tlvLBlock immediately follows the SNAC header before the rest of the fields
MORE_REPLIES_FOLLOW	0x0001	More 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

Name	Value	Notes
INVALID_SNAC	1	Not a known SNAC
RATE_TO_HOST	2	Exceed the rate limit to server
RATE_TO_CLIENT	3	Exceed the rate limit to the remote user
NOT_LOGGED_ON	4	Remote user is not logged in
SERVICE_UNAVAILABLE	5	Normally available but something is wrong right now
SERVICE_NOT_DEFINED	6	Requested a service that does not exist
OBSOLETE_SNAC	7	This SNAC is known no longer supported
NOT_SUPPORTED_BY_HOST	8	Unknown SNAC
NOT_SUPPORTED_BY_CLIENT	9	Remote user is on but does not support the request
REFUSED_BY_CLIENT	10	Message is bigger then remote client wants
RESPONSES_LOST	12	Something really messed up
REQUEST_DENIED	13	Server said user or client is not allowed to do this
BUSTED_SNAC_PAYLOAD	14	SNAC is too small or is not in the right format
INSUFFICIENT_RIGHTS	15	User or client does not have the correct rights to make the request
IN_LOCAL_PERMIT_DENY	16	User is trying to interact with someone blocked by their own settings
TOO_EVIL_SENDER	17	Sender is too evil
TOO_EVIL_RECEIVER	18	Receiver is too evil
USER_TEMP_UNAVAIL	19	User is migrating or the server is down
NO_MATCH	20	Item was not found
LIST_OVERFLOW	21	Too many items were specified in a list
REQUEST_AMBIGOUS	22	Host could not figure out which item to operate on
TIMEOUT	26	Some kind of timeout
GENERAL_FAILURE	28	General failure
RESTRICTED_BY_PC	31	Restricted by parental controls
REMOTE_RESTRICTED_BY_PC	32	Remote user is restricted by parental controls

TLV Class: ERROR__TAGS

These are common tags used by error SNACs.

Name	Tag	Type	Notes
FAIL_URL	4	string	URL with more detail
ERROR_SUBCODE	8	u16	Foodgroup-specific error code
ERROR_TEXT	27	string	String error message text
ERROR_INFO_CLSID	41	UUID	UUID specifying format of ERROR_INFO_DATA data
ERROR_INFO_DATA	42	blob	Extra 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.

Name	Type	Notes
displayId	string08	Formated loginId
evil	u16	Warning level of user
userAttributes	tlvBlock	[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.

Name	Tag	Type	Notes
NICK_FLAGS	1	u16	[Class:OSERVICE__NICK_FLAGS] Flags that represent the user's state
SIGNON_TOD	3	t70	Signon time
IDLE_TIME	4	u16	Idle time in minutes
MEMBER_SINCE	5	t70	Approximation of AIM membership
REALIPADDRESS	10	u32	Network byte order IP address
CAPS	13	Array of UUID	Client capabilities - if not present use the previous values received; if present but empty, clear previous values
ONLINE_TIME	15	u32	Online time in seconds
MY_INSTANCE_NUM	20	u08	Set in first nick info. Identifies the instance number of this client
SHORT_CAPS	25	Array of u16	Short form of capabilities
BART_INFO	29	Array of BART__ID	Expressions
NICK_FLAGS2	31	Array of u08	[Class:OSERVICE__NICK_FLAGS] Upper bytes of nick flags, can be any size. nickFlags = NICK_FLAG | (NICK_FLAGS2 << 16)
BUDDYFEED_TIME	35	t70	Last Buddy Feed update time
SIG_TIME	38	t70	Time that the profile was set
AWAY_TIME	39	t70	Time that away was set
GEO_COUNTRY	42	string	Two 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)

Name	Value	Notes
UNCONFIRMED	0x0001	Unconfirmed account
AOL	0x0004	AOL user
AIM	0x0010	AIM user
UNAVAILABLE	0x0020	User is away
ICQ	0x0040	ICQ user; AIM bit will also be set
WIRELESS	0x0080	On a mobile device
IMF	0x0200	Using IM Forwarding
BOT	0x0400	Bot user
ONE_WAY_WIRELESS	0x1000	One way wireless device
NO_KNOCK_KNOCK	0x00040000	Do not display the "not on your Buddy List" knock-knock as the server took care of it or the sender is trusted
FORWARD_MOBILE	0x00080000	If 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.

Name	Type	Notes
foodgroup	u16	Foodgroup that the version represents
version	u16	Version of the foodgroup implementation; should be 4 for OSERVICE, 3 for FEEDBAG, 1 for all others
tool_id	u16	Should be 41 for all Open AIM clients
tool_version	u16	Any version number the developer would like, usually the build number

SNAC: OSERVICE__ERROR - Foodgroup:1 Type:1

Error SNAC for the OSERVICE foodgroup.

Name	Type	Notes
code	u16	[Class: ERROR__CODE] Error code
errorTLVs	Rest 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.

Name	Type	Notes
groups	Rest of SNAC array of u16	All 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.

Name	Type	Notes
groupVersions	Rest of SNAC array of OSERVICE__Version	All 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.

Name	Type	Notes
classId	u16	Rate class being described
windowSize	u32	Number of events to count
clearThreshold	u32	Once rate limited the average has to reach this value in order to clear
alertThreshold	u32	Server will tell the client it is getting close to the limit
limitThreshold	u32	SNACs will be dropped below this value
disconnectThreshold	u32	Server will disconnect below this value
currentAverage	u32	Current value for the class; higher is better
maxAverage	u32	The maximum rate value; if the current value rises about this value it should be reset
lastArrivalDelta	u32	Last message was received this long ago
droppingSNACs	u08	Is the server dropping SNACs for this rate class

Datatype: OSERVICE__Rate_Class_Members

Describes all the SNACs in a single rate class.

Name	Type	Notes
id	u16	Rate class being described
numMembers	u16	Number of SNACs in this rate class
snacIds	Array of SNAC__ID length numMembers	SNACs 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.

Name	Type	Notes
numClasses	u16	Number of different rate classes
rateParameters	Array of OSERVICE__Rate_Parameters length numClasses	Controlling parameters
rateMembers	Array of OSERVICE__Rate_Class_Members length numClasses	Which 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.

Name	Type	Notes
classIds	Rest of SNAC array of u16	Rate 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.

Name	Type	Notes
classIds	Rest of SNAC array of u16	Rate 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.

Name	Type	Notes
rateCode	u16	[Class: OSERVICE__RATE_CODE] New rate code from server
rateParameters	Rest of SNAC array of OSERVICE__Rate_Parameters	New rate parameters

Class: OSERVICE__RATE_CODE

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

Name	Value	Notes
CHANGE	1	Rate parameters have changed
WARNING	2	Rate limit warning reached; if client does not slow down LIMIT state will be hit
LIMIT	3	Rate limit reached; if client does not slow down client will be disconnected
CLEAR	4	Rate 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.

Name	Tag	Type	Notes
RECONNECT_HERE	5	string	IPaddress followed by optional colon and port, 10.0.0.1:5190
LOGIN_COOKIE	6	string	Binary opaque data
SSL_CERTNAME	141	string	Certname to use for SSL validation
SSL_STATE	142	u08	[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.

Name	Type	Notes
allGroups	u16	Will be zero
tlvAuthData	Rest 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:

• BART - For downloading Buddy Art

TLV Class: OSERVICE__SERVICE_REQUEST_TAGS

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

Name	Tag	Type	Notes
USE_SSL	140	empty	No value; if present use SSL

Class: OSERVICE__SERVICE_RESPONSE_SSL_STATE

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

Name	Value	Notes
NOT_USED	0	SSL is not supported or not requested for this connection
USE	1	SSL is being used
RESUME	2	SSL 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.

Name	Tag	Type	Notes
GROUP_ID	13	u16	Foodgroup for which this response is for
RECONNECT_HERE	5	string	IP address followed by optional colon and port, 10.0.0.1:5190
LOGIN_COOKIE	6	string	Binary opaque data
SSL_CERTNAME	141	string	Certname to use for SSL validation
SSL_STATE	142	u08	[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.

Name	Type	Notes
foodgroup	u16	Group being requested
qualifyingParameters	Rest 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.

Name	Type	Notes
connectInfo	Rest 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.

Name	Type	Notes
info	Rest of SNAC array of OSERVICE__NickwInfo	Updated 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.

Name	Type	Notes
newEvil	u16	New evil level - max is 1000; if the value goes down then it is an update and not a evil
vilifier	OSERVICE__NickwInfo	Optional; 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.

Name	Type	Notes
idleTime	u32	Client'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).

Name	Type	Notes
tlvs	Rest 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.

Name	Type	Notes
replyIds	Rest of SNAC array of BART__ID	BART 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.

Name	Type	Notes
ids	Rest of SNAC array of BART__ID	BART 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.

Name	Type	Notes
reply_ids	Rest of SNAC array of BART__QUERY_REPLY_ID	Information 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.

Name	Type	Notes
code	u16	[Class: ERROR__CODE] Error code
errorTLVs	Rest 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.

Name	Type	Notes
tlvs	Rest 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.

Name	Tag	Type	Notes
FLAGS	5	u16	[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.

Name	Value	Notes
BART_SUPPORTED	0x0001	Want to receive BART items
INITIAL_DEPARTS	0x0002	Want to receive ARRIVE/DEPART for all users on a Buddy List, even those offline
OFFLINE_BART_SUPPORTED	0x0004	Want to receive BART items for offline buddies, excluding location
REJECT_PENDING_BUDDIES	0x0008	If 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.

Name	Type	Notes
tlvs	Rest 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.

Name	Tag	Type	Notes
MAX_BUDDIES	1	u16	Number of loginIds the user can have on their Buddy List
MAX_WATCHERS	2	u16	Number of online users who can simultaneously watch this user
MAX_TEMP_BUDDIES	4	u16	Number 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.

Name	Type	Notes
loginIds	Rest of SNAC array of string08	Names 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.

Name	Type	Notes
arrivedInfos	Rest of SNAC array of OSERVICE__NickwInfo	User'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.

Name	Type	Notes
arrivedInfos	Rest of SNAC array of OSERVICE__NickwInfo	User'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.

Name	Type	Notes
loginIds	Rest of SNAC array of string08	Names 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.

Name	Type	Notes
loginIds	Rest of SNAC array of string08	names 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.

Name	Type	Notes
code	u16	[Class: ERROR__CODE] Error code
errorTLVs	Rest 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.

Name	Tag	Type	Notes
MAX_PERMITS	1	u16	Number of permit entries a user is allowed
MAX_DENIES	2	u16	Number of deny entries a user is allowed
MAX_TEMP_PERMITS	3	u16	Number 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.

Name	Type	Notes
tlvs	Rest 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.

Name	Type	Notes
loginIds	Rest of SNAC array of string08	Names 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.

Name	Type	Notes
loginIds	Rest of SNAC array of string08	Names 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.

Name	Type	Notes
code	u16	[Class: ERROR__CODE] Error code
errorTLVs	Rest 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.

Name	Tag	Type	Notes
MAX_SIG_LEN	1	u16	Maximum signature length for this user
MAX_CAPABILITIES_LEN	2	u16	Number of full UUID capabilities allowed
MAX_FIND_BY_EMAIL_LIST	3	u16	Maximum number of email addresses to look up at once
MAX_CERTS_LEN	4	u16	Largest CERT length for end to end encryption
MAX_SHORT_CAPABILITIES	5	u16	Number 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.

Name	Type	Notes
tlvs	Rest 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.

Name	Tag	Type	Notes
SIG_TYPE	1	string	Signature's MIME type
SIG_DATA	2	string	Signature data, also called the get info profile
UNAVAILABLE_TYPE	3	string	Away message MIME type
UNAVAILABLE_DATA	4	string	Away message data
CAPABILITIES	5	Array of UUID	Capabilities of the client
SIG_TIME	10	t70	Time the signature was set
UNAVAILABLE_TIME	11	t70	Time the away message was set
SUPPORT_HOST_SIG	12	u08	If true, enable server based profiles
HTML_INFO_TYPE	13	string	Host based Buddy Info MIME type
HTML_INFO_DATA	14	string	Host 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.

Name	Type	Notes
infoData	TLV	[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.

Name	Value	Notes
SIG	0x00000001	The AIM signature
UNAVAILABLE	0x00000002	The away message
CAPABILITIES	0x00000004	CAPABILITIES UUID array; short caps will be represented in long form
CERTS	0x00000008	The CERT Blob
HTML_INFO	0x00000400	Return 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.

Name	Type	Notes
type2	u32	[Class: LOCATE__QUERY_TYPE] What data should be returned
loginId	string08	User 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.

Name	Type	Notes
info	OSERVICE__NickwInfo	Generic nick with info about user
locateInfo	Rest 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.

Name	Type	Notes
emails	Rest of SNAC array of string16	List 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.

Name	Type	Notes
infos	Rest of SNAC array of LOCATE__NickwInfo_Email	Information 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.

Name	Type	Notes
info	OSERVICE__NickwInfo	Info for loginId that matched the email address
email	string16	Email address requested

Foodgroup: ICBM

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

Name	Size	Notes
ICBM__Cookie	8 byte	Opaque data used to link conversations

Class: ICBM__CHANNELS

Messages sent between users are sent on a specific channel that narrow down how they should be processed and possible rate size parameters.

Name	Value	Notes
IM	1	Normal IM channel; all clients are expected to understand this channel
RENDEZVOUS	2	For 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.

Name	Value	Notes
CHANNEL_MSGS_ALLOWED	0x00000001	Wants ICBMs on this channel
MISSED_CALLS_ENABLED	0x00000002	Wants MISSED_CALLS on this channel
EVENTS_ALLOWED	0x00000008	Wants CLIENT_EVENTs
SMS_SUPPORTED	0x00000010	Aware of sending to SMS
OFFLINE_MSGS_ALLOWED	0x00000100	Support offline IMs; client is capable of storing and retrieving

Class: ICBM__ERROR_SUBCODE

These are subcodes used with standard errors.

Name	Value	Notes
REMOTE_IM_OFF	1	Used with NOT_LOGGED_ON
REMOTE_RESTRICTED_BY_PC	2	Used with NOT_LOGGED_ON; the remote side denied because of parental controls
NEED_SMS_LEGAL_TO_SEND	3	User tried to send a message to an SMS user and is required to accept the legal text first
SMS_WITHOUT_DISCLAIMER	4	Client tried to send a message to an SMS user without the character counter being displayed
SMS_COUNTRY_NOT_ALLOWED	5	Client tried to send a message to an SMS user but the SMS matrix said the country code combination not permitted
SMS_UNKNOWN_COUNTRY	8	Client tried to send to an SMS user but the server could not determine the country
CANNOT_INITIATE_IM	9	An IM cannot be initiated by a BOT
IM_NOT_ALLOWED	10	An IM is not allowed by a consumer BOT to a user
CANNOT_IM_USAGE_LIMITED	11	An IM is not allowed by a consumer BOT due to reaching a generic usage limit, not common
CANNOT_IM_DUSAGE_LIMITED	12	An IM is not allowed by a consumer BOT due to reaching the daily usage limit
CANNOT_IM_MUSAGE_LIMITED	13	An IM is not allowed by consumer BOT due to reaching the monthly usage limit
OFFLINE_IM_NOT_ACCEPTED	14	User does not accept offline IMs
OFFLINE_IM_EXCEED_MAX	15	Exceeded max storage limit

SNAC: ICBM__ERROR - Foodgroup:4 Type:1

This is the error SNAC for the ICBM foodgroup.

Name	Type	Notes
code	u16	[Class: ERROR__CODE] Error code
errorTLVs	Rest 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.

Name	Type	Notes
channel	u16	[Class: ICBM__CHANNELS] To which channel these parameters apply, or 0 for the defaults
icbmFlags	u32	[Class: ICBM__PARAMETER_FLAGS] Controlling flags
maxIncomingICBMLen	u16	Maximum size of an ICBM the client wants to receive; the range is from 80 to 8000
maxSourceEvil	u16	When receiving an ICBM, the maximum evil level of the sender; the range is from 0 to 999
maxDestinationEvil	u16	When sending an ICBM, the maximum evil level of destination; the range is from 0 to 999
minInterICBMInterval	u32	How 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.

Name	Type	Notes
channel	u16	Channel 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.

Name	Type	Notes
maxSlots	u16	Represents the maximum number of parameter slots available
icbmFlags	u32	[Class: ICBM__PARAMETER_FLAGS] Controlling flags
maxIncomingICBMLen	u16	Maximum size of an ICBM the client wants to receive; the range is from 80 to 8000
maxSourceEvil	u16	When receiving an ICBM, the maximum evil level of the sender; the range is from 0 to 999
maxDestinationEvil	u16	When sending an ICBM, the maximum evil level of the destination; the range is from 0 to 999
minInterICBMInterval	u32	How often the client wants to receive ICBMs in milliseconds

Class: ICBM__IM_SECTION_ENCODINGS

An IM can be encoded in the following different forms:

Name	Value	Notes
ASCII	0	ANSI ASCII -- ISO 646
UNICODE	2	ISO 10646.USC-2 Unicode
LATIN_1	3	ISO 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?

Name	Type	Notes
encoding	u16	[Class: ICBM__IM_SECTION_ENCODINGS] Encoding of the data
language	u16	Language of the data for old clients; new clients should just use 0
data	blob	The 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.

Name	Tag	Type	Notes
IM_TEXT	0x0101	ICBM__IM_SECTION	The actual IM text; there can be multiple of these
IM_CAPABILITIES	0x0501	u08	Old client support; should just be the value 1
MIME_ARRAY	0x0D01	u16	Short caps

Class: ICBM__RENDEZVOUS_MESSAGE

This is a type of rendezvous/data message.

Name	Value	Notes
PROPOSE	0	Propose a rendezvous
CANCEL	1	Cancel a proposal you generated
ACCEPT	2	Accept a proposal someone else generated

Class: ICBM__RENDEZVOUS_CANCEL_REASONS

These are the reasons a proposal is cancelled.

Name	Value	Notes
UNKNOWN	0	Reason not specified
USER_CANCEL	1	Recipient user declined
TIMEOUT	2	Timeout
ACCEPTED_ELSEWHERE	3	Proposal 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.

Name	Tag	Type	Notes
CHANNEL	1	u16	ICBM channel on which the rendezvous is to occur
IP_ADDR	2	u32	IP address proposed for the rendezvous
PROPOSER_IP_ADDR	3	u32	IP address of the proposing client
VERIFIED_IP_ADDR	4	u32	IP address of the proposing client as seen by server; NOTE - this TLV may only be added by the server
PORT	5	u16	Port value of the client for rendezvous
DOWNLOAD_URL	6	string	URL for downloading software to support the service
VERIFIED_DOWNLOAD_URL	8	string	Same as DOWNLOAD_URL, but added by server if the service is well known; Note - this TLV may only be added by the server
SEQUENCE_NUM	10	u16	Identifies 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_REASON	11	u16	[Class:ICBM__RENDEZVOUS_CANCEL_REASONS] Reason for cancelling a rendezvous; this tag must be present in all RENDEZVOUS_CANCEL payloads.
INVITATION	12	string	Text inviting the other player to join
INVITE_MIME_CHARSET	13	string	Charset used by the data
INVITE_MIME_LANG	14	string	Language used by the data
REQUEST_HOST_CHECK	15	empty	Requests that the server check caps for recipient
REQUEST_USE_ARS	16	empty	Requests that the Rendezvous Server be used as a transport for the data
REQUEST_SECURE	17	empty	Requests that SSL be used for the connection
MAX_PROTOCOL_VERSION	18	u16	Maximum application protocol version supported
MIN_PROTOCOL_VERSION	19	u16	Minimum application protocol version supported
COUNTER_REASON	20	u16	Reason for a counter proposal
INVITE_MIME_TYPE	21	string	Content-type used by the data
IP_ADDR_XOR	22	u32	IP_ADDR ^ 0xFFFFFFFF
PORT_XOR	23	u16	PORT ^ 0xFFFF
ADDR_LIST	24	Array of string08	List of "IP port" pairs to try
SESSION_ID	25	string	Identifier for session
ROLLOVER_ID	26	string	Identifier of session to rollover
SERVICE_DATA	10001	blob	Service 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).

Name	Type	Notes
type	u16	[Class: ICBM__RENDEZVOUS_MESSAGE] What kind of rendezvous message is this
cookie	ICBM__Cookie	Opaque data generated by conversation initiator and used to link up the conversation and errors
service	UUID	Identifies type of data message being exchanged
params	Rest 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.

Name	Tag	Type	Notes
IM_DATA	2	Array of TLV	[Class:ICBM__IM_DATA_TAGS] Message data for the IM channel only; unlike other TLVs the order of TLVs inside this tag does matter - it should be the CAPABILITIES item followed by multiple IM_TEXT items
REQUEST_HOST_ACK	3	empty	Host will acknowledge this ICBM upon sending it to the destination client; this does NOT mean the destination user received it
AUTO_RESPONSE	4	empty	This message is an auto response; this tag is not allowed with either the REQUEST_HOST_ACK or STORE tags
DATA	5	ICBM__IM_RENDEZVOUS	Message data for all other channels
STORE	6	empty	If the user is offline then store this message for delivery the next time the user logs in when possible; AIM and ICQ use complex privacy rules that control if an offline IM delivery is allowed or not
WANT_EVENTS	11	empty	Used in TO_CLIENT only, it is added by the server if the sender wants client events
BART	13	BART__ID	If desired BART items can be sent with the ICBM, the client should override the ones in NickwInfo with these
SEND_TIME	22	t70	Time when the server received the offline IM
FRIENDLY_NAME	23	string	For WIMZI this is the friendly name of the anonymous user
ANONYMOUS	24	empty	This 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.

Name	Type	Notes
cookie	ICBM__Cookie	Opaque data generated by conversation initiator and used to link up the conversation and errors
channel	u16	[Class: ICBM__CHANNELS] Channel the message is on
destLoginId	string08	Destination loginId, who should receive the message
icbmTlvs	Rest 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.

Name	Type	Notes
cookie	ICBM__Cookie	Opaque data generated by conversation initiator and used to link up the conversation and errors
channel	u16	[Class: ICBM__CHANNELS] Channel the message is on
info	OSERVICE__NickwInfo	Information about the sender of the message
icbmTlvs	TLV	[Class: ICBM__TAGS] Actual message

Class: ICBM__EVIL_REQUEST_FLAGS

These are the flags that control how EVIL should work.

Name	Value	Notes
ANONYMOUS	0x0001	Do 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.

Name	Type	Notes
evilFlags	u16	[Class: ICBM__EVIL_REQUEST_FLAGS] What kind of EVIL to perform
evilLoginId	string08	Who 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.

Name	Type	Notes
evilDeltaApplied	u16	How much EVIL was applied to the requestee
updatedEvilValue	u16	Requestee'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.

Name	Value	Notes
TOO_LARGE	0x0001	Sender's message was too large
RATE_EXCEEDED	0x0002	Sender exceeded the receiver's rate limit
EVIL_SENDER	0x0004	Message rejected because sender is EVIL
EVIL_RECEIVER	0x0008	Message rejected because receiver is EVIL

Datatype: ICBM__Missed_Call

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

Name	Type	Notes
channel	u16	Channel on which the missed message was
senderInfo	OSERVICE__NickwInfo	Information about the sender
numMissed	u16	How many messages were dropped
reason	u16	[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.

Name	Type	Notes
missedCallArray	Rest of SNAC array of ICBM__Missed_Call	Information about the messages that were missed

Class: ICBM__RENDEZVOUS_NAK

Sent in ICBM__CLIENT_ERR errorInfo field

Name	Value	Notes
PROPOSAL_UNSUPPORTED	0	Proposal UUID not supported
PROPOSAL_DENIED	1	Not authorized, or user declined
PROPOSAL_IGNORED	2	DO NOT USE; 'ignores' should no-op
BUSTED_PARAMETERS	3	Proposal malformed
PROPOSAL_TIMED_OUT	4	Attempt to act on proposal (e.g. connect) timed out
ONLINE_BUT_NOT_AVAILABLE	5	Recipient away or busy
INSUFFICIENT_RESOURCES	6	Recipient had internal error
RATE_LIMITED	7	Recipient was ratelimited
NO_DATA	8	Recipient had nothing to send
VERSION_MISMATCH	9	Incompatible versions
SECURITY_MISMATCH	10	Incompatible security settings
SERVICE_SPECIFIC_REASON	15	Service-specific reject defined by client

Class: ICBM__CLIENT_ERRORS

The following are Inter-Client error codes.

Name	Value	Notes
UNSUPPORTED_CHANNEL	1	Receiving client does not understand the channel
BUSTED_ICBM_PAYLOAD	2	Receiving client thinks the payload is busted
CHANNEL_SPECIFIC_ERROR	3	See 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.

Name	Type	Notes
cookie	ICBM__Cookie	Opaque data generated by conversation initiator and used to link up the conversation and errors
channel	u16	[Class: ICBM__CHANNELS] Channel the message is on
loginId	string08	Destination loginId when sending and the source loginId when received
code	u16	[Class: ICBM__CLIENT_ERRORS] Error code
errorInfo	blob	Optional 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

Name	Tag	Type	Notes

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.

Name	Type	Notes
cookie	ICBM__Cookie	Opaque data generated by conversation initiator and used to link up the conversation and errors
channel	u16	[Class: ICBM__CHANNELS] Channel the message is on
loginId	string08	Destination loginId that should receive the message
ackTlvs	Rest 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.

Name	Value	Notes
NONE	0	Default state; only sent if the user was typing but erased the message
TYPED	1	Indicates that the user was typing but has stopped for at least 2 seconds
TYPING	2	Indicates the message is being actively composed; only send once when switching to this state, do NOT send for every character
RESERVED	3	Reserved
CLOSED	15	Indicates 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.

Name	Type	Notes
cookie	ICBM__Cookie	Opaque data generated by conversation initiator and used to link up the conversation and errors
channel	u16	[Class: ICBM__CHANNELS] Channel the message is on
loginId	string08	Destination loginId when sending and the source loginId when received
event	u16	[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.

Name	Tag	Type	Notes
EMAIL	17	string	Email address to invite
PERSONALIZED_TEXT	21	string	Personalized message to send in an invite

SNAC: INVITE__ERROR - Foodgroup:6 Type:1

This is the error SNAC for the INVITE foodgroup.

Name	Type	Notes
code	u16	[Class: ERROR__CODE] Error code
errorTLVs	Rest 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.

Name	Type	Notes
inviteTLVs	Rest 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:

groupId	itemId	classId	Name	Attributes
0	0	GROUP(0)		ORDER(200):321 10
0	1805	DENY(3)	spimmer123
0	4046	BART(20)	5	BART_INFO(213): 00052b000013b9
0	12108	PDINFO(4)		PD_MODE(202): 04 PD_MASK(203): ffffffff PD_FLAGS(204): 00000001
10	0	GROUP(1)	Friends	ORDER(200): 110 147
10	110	BUDDY(0)	ChattingChuck
10	147	BUDDY(0)	example@example.com
321	0	GROUP(1)	Empty Group	ORDER(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.

Name	Value	Notes
INTERACTION_SUPPORTED	0x0001	Client supports interactions
AUTHORIZATION_SUPPORTED	0x0002	Client supports Buddy authorization
DOMAIN_SN_SUPPORTED	0x0004	Client supports a@b.com
ICQ_NUM_SUPPORTED	0x0008	Client supports 1234567890
SMS_NUM_SUPPORTED	0x0010	Client supports +17035551212
ALIAS_ATTR_SUPPORTED	0x0020	Client supports alias attribute
SMARTGRP_SUPPORTED	0x0040	Client supports smart groups

TLV Class: FEEDBAG__RIGHTS_QUERY_TAGS

These are the types used in the Feedbag rights query.

Name	Tag	Type	Notes
FLAGS	11	u16	[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.

Name	Type	Notes
code	u16	[Class: ERROR__CODE] Error code
errorTLVs	Rest 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.

Name	Type	Notes
tlvs	Rest 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.

Name	Tag	Type	Notes
MAX_ITEM_ATTRS	3	u16	Maximum size of all the attributes on a single item
MAX_ITEMS_BY_CLASS	4	Array of u16	Maximum number of items per class
MAX_CLIENT_ITEMS	5	u16	Total number of items with classId > 1024
MAX_ITEM_NAME_LEN	6	u16	Maximum length of name in Item that the database supports
MAX_RECENT_BUDDIES	7	u16	How many RECENT_BUDDIES are allowed
INTERACTION_BUDDIES	8	u16	Top N interactions are buddies
INTERACTION_HALF_LIFE	9	u32	Half life in 2^(-age/half_life) in seconds
INTERACTION_MAX_SCORE	10	u32	Upper limit in interaction score
MAX_BUDDIES_PER_GROUP	12	u16	How many BUDDIES are allowed per group
MAX_MEGA_BOTS	13	u16	How many BOT BUDDIES are allowed
MAX_SMART_GROUPS	14	u16	How many smart groups are allowed

SNAC: FEEDBAG__RIGHTS_REPLY - Foodgroup:19 Type:3

This is the response to the FEEDBAG__RIGHTS_QUERY SNAC.

Name	Type	Notes
tlvs	Rest 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.

Name	Type	Notes
lastUpdate	t70	The last interaction with this Buddy
score	f32	The 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

Name	Value	Notes
BUDDY	0	(G) Names for Buddy List
GROUP	1	(R) Group Name
PERMIT	2	(R) Names for Permit List
DENY	3	(R) Names for Deny List
PDINFO	4	(R) PDMODE/PDMASK/PDFLAGS
BUDDY_PREFS	5	(R) Buddy List preferences
NONBUDDY	6	(R) Users not in the Buddy List; use this to store aliases or other information for future use
CLIENT_PREFS	9	(R) Client-specific preferences; name is name of client, e.g., "AIM Express"
DATE_TIME	15	(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)
BART	20	(R) BART IDs; name is the BART Type
RB_ORDER	21	(R) Order attribute lists recent buddies in the least to most recently used order
PERSONALITY	22	(R) Collection of BART ids
AL_PROF	23	(R) Information about Account Linking prefrences
AL_INFO	24	(R) Account linking information
INTERACTION	25	(R) Non-Buddy interaction record
VANITY_INFO	29	(R) Vanity information kept at user logoff
FAVORITE_LOCATION	30	(R) User's favorite locations
BART_PDINFO	31	(R) BART PDMODE
CUSTOM_EMOTICONS	36	ICQ Custom Emoticons with BART_LIST attributes
MAX_PREDEFINED	36	Dummy value; Set to highest used ID
MIN	1024	(B) Values above this are valid indexes

Class: FEEDBAG__PD_MODE

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

Name	Value	Notes
PERMIT_ALL	1	Allow anyone
DENY_ALL	2	Deny everyone
PERMIT_SOME	3	Permit folks listed
DENY_SOME	4	Deny folks listed
PERMIT_ON_LIST	5	Allow folks on the Buddy List

Class: FEEDBAG__WEB_PD_MODE

These are the different modes that control anonymous web queries.

Name	Value	Notes
PD_MODE	0	Only show my anonymous queries on web pages when user is in Allow All or Deny Some mode [DEFAULT]
PERMIT_ALL	1	Permit anonymous queries always
DENY_ALL	2	Deny anonymous queries always

Class: FEEDBAG__PD_FLAGS

This class changes how the permit deny settings work.

Name	Value	Notes
APPLIES_IM	0x0001	The 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_WIRELESS	0x002	Hide 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.

Name	Value	Notes
DISPLAY_LOGIN	0	[1] Whether or not to display Buddy List at login
DISPLAY_EBUDDY	1	[1] Whether or not to display the EBuddy group
PLAY_ENTER	2	[1] Whether or not to play a sound when a Buddy enters
PLAY_EXIT	3	[1] Whether or not to play a sound when a Buddy exits
VIEW_IMSTAMP	4	[1] Whether or not to display the timestamp in IMs
VIEW_SMILEYS	5	[1] Whether or not to display :) as a graphic
ACCEPT_ICONS	6	[1] Accept Buddy icons
RESERVED	7	[1] Legacy pref
KNOCK_NONAOLIMS	8	[1] Want knock-knocks for IMs from non-AOL users
KNOCK_NONLISTIMS	9	[1] Want knock-knocks for IMs from people not on your Buddy List
DISCLOSE_IDLE	10	[1] Let other users know if you are idle
ACCEPT_CUSTOMBART	11	[0] Accept non-official icons, chromes
ACCEPT_NONLISTBART	12	[0] Accept icon, chromes, from non-buddies (official only)
ACCEPT_BGS	13	[1] Accept IM window backgrounds
ACCEPT_CHROMES	14	[1] Accept IM window chromes
ACCEPT_BLSOUNDS	15	[1] Accept Buddy List arrive/depart sounds
ACCEPT_IMSOUNDS	16	[1] Accept IM sounds
NO_SEE_RECENT_BUDDIES	17	[0] Use does not see RECENT BUDDIES group
ACCEPT_SMS_LEGAL	18	[0] User has accepted to SMS legal agreement
ENTER_DOES_CRLF	20	[0] Enter does not send IM
PLAY_IM_SOUND	21	[1] Play sound on IM receipt
DISCLOSE_TYPING	22	[1] Send typing notifications
ACCEPT_SUPERICONS	24	[1] Accept 'super-buddies'
ACCEPT_BLRICHTEXT	25	[1] Display rich-text screennames in Buddy List
REDUCE_IM_SOUND	26	[1] Attenuate IM sounds after first sound
CONFIRM_DIRECT_IM	27	[1] Confirm with local user before starting DIM
ONE_TABBED_IM_WINDOW	28	[1] Show all IMs in one tabbed window
BUDDYINFO_ON_MOUSEOVER	29	[1] Popup information when mouse pauses above Buddy
DISCLOSE_BUDDY_MATCHES	30	[1] Let other users know if they have Buddy matches
CATCH_IMS	31	[0] For server use only; clients use CATCH_IMS_FOR_CLIENT
SHOW_FRIENDLY_NAME	32	[1] Show alias instead of screenname?
DISCLOSE_RADIO	33	[1] Buddies know when user listening to AOL radio
SHOW_CAPABILIITES	34	[1] Show capabilities in the Buddy List
SHOW_BUDDYLIST_FILTER	35	[1] Show Buddy List filter
SHOW_AWAY_IDLE	36	[1] Show away and idle buddies
SHOW_MOBILE	37	[1] Show mobile buddies
SORT_BUDDYLIST	38	[0] Keep Buddy List sorted A-Z
CATCH_IMS_FOR_CLIENT	39	[0] IM catcher window enabled?
NEW_MESSAGE_SMALL_NOTIFICATION	40	[1] show small notification after new message arrives
NO_FREQUENT_BUDDIES	41	[0] User does not see FREQUENT BUDDIES group
BLOG_AWAY_MESSAGES	42	[0] Send away messages to journals ?
BLOG_AIMSIG_MESSAGES	43	[0] Send AIM signature to journals ?
BLOG_NOCOMMENTS	44	[0] User allows comments ?
FRIEND_OF_FRIEND	45	[0] Allow Friend of Friend queries
FRIEND_GET_CONTACT_LIST	46	[0] Allow friend to get my Buddy List
COMPAD_INIT	47	[0] ICQ Compad Init
SEND_BUDDYFEED	48	[1] Send Buddy Feed; Young Teens(YT)/Kids Only(KO) - KO default to OFF
BLK_SEND_IM_WHILE_AWAY	49	[0] Block send IM while away
SHOW_BUDDYFEED	50	[1] Show What is New indicator
NO_SAVE_VANITY_INFO	51	[0] Do not save vanity related information (IM sent, idle, etc.)
ACCEPT_OFFLINE_IM	52	[1] Accept Offline IMs
SHOW_GROUPS	53	[0] ICQ: Show buddies in groups ?
SORT_GROUP	54	[1] ICQ: Sort groups ?
SHOW_OFFLINE_BUDDIES	55	[1] ICQ: Show/Hide Offline Buddies
EXPAND_BUDDIES	56	[0] ICQ: Show multiline information on some buddies
THIRD_PARTY_FEEDS	57	[0] BUDDY FEED: Does the owner have third party feeds
NOTIFY_RECEIVED_INVITE	58	[1] Notify at login about received AIMPages invitations
APF_AUTO_ACCEPT	59	[0] Auto accept AIMPages invitations
APF_AUTO_ACCEPT_BUDDY	60	[0] If APF_AUTO_ACCEPT and APF_AUTO_ACCEPT_BUDDY, auto accept invites only from buddies
BLOCK_AWAY_MSG_FEED	61	[0] Block feed storage for away messages
BLOCK_AIM_PROFILE_FEED	62	[0] Block feed storage for AIM Profiles
BLOCK_AIM_PAGES_FEED	63	[0] Block feed storage for AIM Pages
BLOCK_JOURNALS_FEED	64	[0] Block feed storage for AOL Journals
BLOCK_LOCATION_FEED	65	[0] Block feed storage for Location data
BLOCK_STICKIES_FEED	66	[0] Block feed storage for Stickies
BLOCK_UNCUT_FEED	67	[0] Block feed storage for Uncut video
BLOCK_LINKS_FEED	68	[0] Block feed storage for Interesting Links
BLOCK_AIM_BULLETIN_FEED	69	[0] Block feed storage for AIM Bulletins
SAVE_STATUS_MSG	70	[1] Save status message
APF_NOTIFY_RECEIVED_INVITE_BY_EMAIL	71	[0] Should email be sent when user invited ?
SHOW_OFFLINE_GRP	72	[1] Show Offline group
OFFLINE_GRP_COLLAPSED	73	[0] Offline Group is collapsed
FIRST_IM_SOUND_ONLY	74	[0] Only play the sound on the first IM
IMBLAST_INVITE_NOTIFY	75	[1] ALLOWS IMSERV invite notify message

Class: FEEDBAG__BUDALERT_MASK

Masks for when to trigger Buddy alerts or pounces

Name	Value	Notes
WHEN_ONLINE	0x0001	Trigger when online
WHEN_NOTIDLE	0x0002	Trigger when no longer idle
WHEN_NOTAWAY	0x0004	Trigger when no longer away
DISPLAY_DIALOG	0x0100	Display dialog
PLAY_SOUND	0x0200	Play sound

Datatype: FEEDBAG__Item

This is a single Feedbag item.

Name	Type	Notes
name	string16	UTF8 string of the item's name; maximum length of 97 characters
groupId	u16	ID of the group of which the item is part
itemId	u16	ID inside the group; if 0 then this is the definition of the group
classId	u16	[Class: FEEDBAG__CLASS_IDS] ID of the class of which this item is a member
attributes	tlvLBlock	[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.

Name	Type	Notes
numClasses	u08	Always 0
numItems	u16	Number of items in the Feedbag
items	Array of FEEDBAG__Item length numItems	Actual items inside the users Buddy List
lastUpdate	t70	Most 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.

Name	Type	Notes
items	Rest of SNAC array of FEEDBAG__Item	Items 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.

Name	Type	Notes
items	Rest of SNAC array of FEEDBAG__Item	Items 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.

Name	Type	Notes
items	Rest of SNAC array of FEEDBAG__Item	Items to delete

Class: FEEDBAG__STATUS_CODES

These are the status codes returned from database operations.

Name	Value	Notes
SUCCESS	0	Success
DB_ERROR	1	Some kind of database error
NOT_FOUND	2	Item was not found for an update or delete
ALREADY_EXISTS	3	Item already exists for an insert
UNAVAILABLE	5	Server or database is not available
BAD_REQUEST	10	Request was not formed well
DB_TIME_OUT	11	Database timed out
OVER_ROW_LIMIT	12	Too many items of this class for an insert
NOT_EXECUTED	13	Due to other error in same request
AUTH_REQUIRED	14	Buddy List authorization required
BAD_LOGINID	16	Bad loginId
OVER_BUDDY_LIMIT	17	Too many buddies
INSERT_SMART_GROUP	20	Attempt to added a Buddy to a smart group
TIMEOUT	26	General 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.

Name	Type	Notes
statuses	Rest 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.

Name	Type	Notes
tlvs	Rest of SNAC array of TLV	Optional 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.

Name	Value	Notes
CUSTOM	0x01	This is a custom blob; the opaque data will also be 16 bytes
DATA	0x04	The opaque field is really data the client knows how to process; these items do not need to be downloaded from BART
UNKNOWN	0x40	Used in OSERVICE__BART_REPLY; BART does not know about this ID, please upload
REDIRECT	0x80	Used 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.

Name	Value	Notes
BUDDY_ICON_SMALL	0	GIF/JPG/BMP, <= 32 pixels and 2k
BUDDY_ICON	1	GIF/JPG/BMP, <= 64 pixels and 7k
STATUS_STR	2	StringTLV format; DATA flag is always set
ARRIVE_SOUND	3	WAV/MP3/MID, <= 10K
RICH_TEXT	4	byte array of rich text codes; DATA flag is always set
SUPERBUDDY_ICON	5	XML
RADIO_STATION	6	Opaque struct; DATA flag is always set
BUDDY_ICON_BIG	12	SWF
STATUS_STR_TOD	13	Time when the status string is set
CURRENT_AV_TRACK	15	XML file; Data flag should not be set
DEPART_SOUND	96	WAV/MP3/MID, <= 10K
IM_CHROME	129	GIF/JPG/BMP wallpaper
IM_SOUND	131	WAV/MP3, <= 10K
IM_CHROME_XML	136	XML
IM_CHROME_IMMERS	137	Immersive Expressions
EMOTICON_SET	1024	Set of default Emoticons
ENCR_CERT_CHAIN	1026	Cert chain for encryption certs
SIGN_CERT_CHAIN	1027	Cert chain for signing certs
GATEWAY_CERT	1028	Cert 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.

Name	Type	Notes
type	u16	[Class: BART__ID_TYPES] Kind of asset this BART ID represents
flags	u08	[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
len	u08	Length of the opaque data
opaque	Array of u08 length len	Opaque 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.

Name	Type	Notes
loginId	string08	User who is using the asset
numIds	u08	Number of assets being requested
ids	Array of BART__ID length numIds	BART IDs to fetch

Datatype: BART__QUERY_REPLY_ID

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

Name	Type	Notes
queryId	BART__ID	Initial ID that is queried or used
code	u08	[Class: BART__REPLY_CODES] Result code of the query
replyId	BART__ID	ID that will be used; might be different then queryId

Class: BART__REPLY_CODES

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

Name	Value	Notes
SUCCESS	0	Operation was a success
INVALID	1	ID is malformed
NOCUSTOM	2	Custom blobs are not allowed for this type
TOSMALL	3	Item uploaded is too small for this type
TOBIG	4	Item uploaded is too big for this type
INVALIDTYPE	5	Item uploaded is the wrong type
BANNED	6	Item uploaded has been banned
NOTFOUND	7	Item downloaded was not found

SNAC: BART__ERROR - Foodgroup:16 Type:1

This is the error SNAC for the BART foodgroup.

Name	Type	Notes
code	u16	[Class: ERROR__CODE] Error code
errorTLVs	Rest 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.

Name	Type	Notes
type	u16	[Class: BART__ID_TYPES] Type of the item to upload
len	u16	Size of the custom item
data	Array of u08 length len	Custom item

SNAC: BART__UPLOAD_REPLY - Foodgroup:16 Type:3

These are the results for an item requested with BART_UPLOAD.

Name	Type	Notes
code	u08	[Class: BART__REPLY_CODES] Results of the upload
id	BART__ID	If 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.

Name	Type	Notes
request	Rest of SNAC array of BART__IDs_wName	Items to download

SNAC: BART__DOWNLOAD_REPLY2 - Foodgroup:16 Type:7

These are the results for an item requested with DOWNLOAD2.

Name	Type	Notes
refname	string08	Name to which the asset belongs
qr_id	BART__QUERY_REPLY_ID	Information about the query
len	u16	Length of the asset
data	Array of u08 length len	Asset'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. 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.

   Field	Size	Value
   u08	flapHeader.startMarker	'*'
   u08	flapHeader.frameType	1 (FLAP__FRAME_TYPE_SIGNON)
   u16	flapHeader.sequenceNumber	XX
   u16	flapHeader.payloadLength	YY
   u32	version	1
   u16	tlvs[0].tag	6 (FLAP__SIGNON_TAGS_LOGIN_COOKIE)
   u16	tlvs[0].len	256
   blob	tlvs[0].value	base64 decoded $cookie value from Step #2
   u16	tlvs[1].tag	74 (FLAP__SIGNON_TAGS_MULTICONN_FLAGS)
   u16	tlvs[1].len	1
   u08	tlvs[1].value	0x01

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:

  Field	Size	Value
  u08	flapHeader.startMarker	'*'
  u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
  u16	flapHeader.sequenceNumber	XX
  u16	flapHeader.payloadLength	YY
  u16	snacHeader.foodgroup	3 (BUDDY)
  u16	snacHeader.type	2 (BUDDY__RIGHTS_QUERY)
  u16	snacHeader.flags	0
  u32	snacHeader.requestId	ZZ
  u16	tlvs[0].tag	5 (BUDDY__RIGHTS_QUERY_TAGS_FLAGS)
  u16	tlvs[0].len	2
  u16	tlvs[0].value	0xf

• Query the PD foodgroup rights:

  Field	Size	Value
  u08	flapHeader.startMarker	'*'
  u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
  u16	flapHeader.sequenceNumber	XX
  u16	flapHeader.payloadLength	YY
  u16	snacHeader.foodgroup	9 (PD)
  u16	snacHeader.type	2 (PD__RIGHTS_QUERY)
  u16	snacHeader.flags	0
  u32	snacHeader.requestId	ZZ

• Query the LOCATE foodgroup rights:

  Field	Size	Value
  u08	flapHeader.startMarker	'*'
  u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
  u16	flapHeader.sequenceNumber	XX
  u16	flapHeader.payloadLength	YY
  u16	snacHeader.foodgroup	2 (LOCATE)
  u16	snacHeader.type	2 (LOCATE__RIGHTS_QUERY)
  u16	snacHeader.flags	0
  u32	snacHeader.requestId	ZZ

• Query the FEEDBAG foodgroup rights:

  Field	Size	Value
  u08	flapHeader.startMarker	'*'
  u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
  u16	flapHeader.sequenceNumber	XX
  u16	flapHeader.payloadLength	YY
  u16	snacHeader.foodgroup	19 (FEEDBAG)
  u16	snacHeader.type	2 (FEEDBAG__RIGHTS_QUERY)
  u16	snacHeader.flags	0
  u32	snacHeader.requestId	ZZ
  u16	tlvs[0].tag	11 (FEEDBAG__RIGHTS_QUERY_TAGS_FLAGS)
  u16	tlvs[0].len	2
  u16	tlvs[0].value	0x7f

• Query what the Buddy List and preferences are:

  Field	Size	Value
  u08	flapHeader.startMarker	'*'
  u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
  u16	flapHeader.sequenceNumber	XX
  u16	flapHeader.payloadLength	YY
  u16	snacHeader.foodgroup	19 (FEEDBAG)
  u16	snacHeader.type	2 (FEEDBAG__QUERY)
  u16	snacHeader.flags	0
  u32	snacHeader.requestId	ZZ

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.

  Field	Size	Value
  u08	flapHeader.startMarker	'*'
  u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
  u16	flapHeader.sequenceNumber	XX
  u16	flapHeader.payloadLength	YY
  u16	snacHeader.foodgroup	19 (FEEDBAG)
  u16	snacHeader.type	7 (FEEDBAG__USE)
  u16	snacHeader.flags	0
  u32	snacHeader.requestId	ZZ

• Next we tell the client we are ready to appear online to everyone else and our version numbers.

  Field	Size	Value
  u08	flapHeader.startMarker	'*'
  u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
  u16	flapHeader.sequenceNumber	XX
  u16	flapHeader.payloadLength	YY
  u16	snacHeader.foodgroup	1 (OSERVICE)
  u16	snacHeader.type	2 (OSERVICE__CLIENT_ONLINE)
  u16	snacHeader.flags	0
  u32	snacHeader.requestId	ZZ
  u16	groupVersions[0].foodgroup	1 (OSERVICE)
  u16	groupVersions[0].version	4
  u16	groupVersions[0].tool_id	41
  u16	groupVersions[0].tool_version	AA
  u16	groupVersions[1].foodgroup	19 (FEEDBAG)
  u16	groupVersions[1].version	3
  u16	groupVersions[1].tool_id	41
  u16	groupVersions[1].tool_version	AA
  u16	groupVersions[1].foodgroup	3 (BUDDY)
  u16	groupVersions[1].version	1
  u16	groupVersions[1].tool_id	41
  u16	groupVersions[1].tool_version	AA
  u16	groupVersions[1].foodgroup	2 (LOCATE)
  u16	groupVersions[1].version	1
  u16	groupVersions[1].tool_id	41
  u16	groupVersions[1].tool_version	AA
  u16	groupVersions[1].foodgroup	6 (INVITE)
  u16	groupVersions[1].version	1
  u16	groupVersions[1].tool_id	41
  u16	groupVersions[1].tool_version	AA
  u16	groupVersions[1].foodgroup	4 (ICBM)
  u16	groupVersions[1].version	1
  u16	groupVersions[1].tool_id	41
  u16	groupVersions[1].tool_version	AA

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.

Field	Size	Value
u08	flapHeader.startMarker	'*'
u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
u16	flapHeader.sequenceNumber	XX
u16	flapHeader.payloadLength	YY
u16	snacHeader.foodgroup	4 (ICBM)
u16	snacHeader.type	20 (ICBM__CLIENT_EVENT)
u16	snacHeader.flags	0
u32	snacHeader.requestId	ZZ
Array of u08	cookie	'12345678'
u16	channel	1 (ICBM__CHANNELS_IM)
u08	loginId.len	13
Array of u08	loginId.value	'ChattingChuck'
u16	event	2 (ICBM__EVENTS_TYPING)

Step #2 - Sending IM

Field	Size	Value
u08	flapHeader.startMarker	'*'
u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
u16	flapHeader.sequenceNumber	XX
u16	flapHeader.payloadLength	YY
u16	snacHeader.foodgroup	4 (ICBM)
u16	snacHeader.type	6 (ICBM__CHANNEL_MSG_TOHOST)
u16	snacHeader.flags	0
u32	snacHeader.requestId	ZZ
Array of u08	cookie	'12345678'
u16	channel	1 (ICBM__CHANNELS_IM)
u08	destLoginId.len	13
Array of u08	destLoginId.value	'ChattingChuck'
u16	icbmTlvs[0].tag	3 (ICBM__TAGS_REQUEST_HOST_ACK)
u16	icbmTlvs[0].len	0
u16	icbmTlvs[1].tag	2 (ICBM__TAGS_IM_DATA)
u16	icbmTlvs[1].len	15
u16	icbmTlvs[1].imData[0].tag	0x0501 (ICBM__IM_DATA_TAGS_IM_CAPABILITIES)
u16	icbmTlvs[1].imData[0].len	1
u08	icbmTlvs[1].imData[0].value	1
u16	icbmTlvs[1].imData[1].tag	0x0101 (ICBM__IM_DATA_TAGS_IM_TEXT)
u16	icbmTlvs[1].imData[1].len	6
u16	icbmTlvs[1].imData[1].encoding	0 (ICBM__IM_SECTION_ENCODINGS_ASCII)
u16	icbmTlvs[1].imData[1].language	0
u08	icbmTlvs[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.

Field	Size	Value
u08	flapHeader.startMarker	'*'
u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
u16	flapHeader.sequenceNumber	XX
u16	flapHeader.payloadLength	YY
u16	snacHeader.foodgroup	4 (ICBM)
u16	snacHeader.type	20 (ICBM__CLIENT_EVENT)
u16	snacHeader.flags	0
u32	snacHeader.requestId	ZZ
Array of u08	cookie	'12345678'
u16	channel	1 (ICBM__CHANNELS_IM)
u08	loginId.len	10
Array of u08	loginId.value	'GabbyGrace'
u16	event	2 (ICBM__EVENTS_TYPING)

Step #4 - Receiving IM

Field	Size	Value
u08	flapHeader.startMarker	'*'
u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
u16	flapHeader.sequenceNumber	XX
u16	flapHeader.payloadLength	YY
u16	snacHeader.foodgroup	4 (ICBM)
u16	snacHeader.type	7 (ICBM__CHANNEL_MSG_TOCLIENT)
u16	snacHeader.flags	0
u32	snacHeader.requestId	ZZ
Array of u08	cookie	'12345678'
u16	channel	1 (ICBM__CHANNELS_IM)
u08	info.loginId.len	10
Array of u08	info.loginId.value	'GabbyGrace'
u16	info.evil	0
u16	info.attrs.num	1
u16	info.attrs[0].tag	1 (OSERVICE__NICK_INFO_TAGS_NICK_FLAGS)
u16	info.attrs[0].len	2
u16	info.attrs[0].value	0x10
u16	icbmTlvs[0].tag	2 (ICBM__TAGS_IM_DATA)
u16	icbmTlvs[0].len	15
u16	icbmTlvs[0].imData[0].tag	0x0501 (ICBM__IM_DATA_TAGS_IM_CAPABILITIES)
u16	icbmTlvs[0].imData[0].len	1
u08	icbmTlvs[0].imData[0].value	1
u16	icbmTlvs[0].imData[1].tag	0x0101 (ICBM__IM_DATA_TAGS_IM_TEXT)
u16	icbmTlvs[0].imData[1].len	6
u16	icbmTlvs[0].imData[1].encoding	0 (ICBM__IM_SECTION_ENCODINGS_ASCII)
u16	icbmTlvs[0].imData[1].language	0
u08	icbmTlvs[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:

Field	Size	Value
u08	flapHeader.startMarker	'*'
u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
u16	flapHeader.sequenceNumber	XX
u16	flapHeader.payloadLength	YY
u16	snacHeader.foodgroup	2 (LOCATE)
u16	snacHeader.type	21 (LOCATE__USER_INFO_QUERY2)
u16	snacHeader.flags	0
u32	snacHeader.requestId	ZZ
u32	type2	0x00000400 (LOCATE__QUERY_TYPE_HTML_INFO)
u08	loginId.len	13
Array of u08	loginId.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:

Field	Size	Value
u08	flapHeader.startMarker	'*'
u08	flapHeader.frameType	2 (FLAP__FRAME_TYPE_DATA)
u16	flapHeader.sequenceNumber	XX
u16	flapHeader.payloadLength	YY
u16	snacHeader.foodgroup	2 (LOCATE)
u16	snacHeader.type	6 (LOCATE__USER_INFO_REPLY)
u16	snacHeader.flags	0
u32	snacHeader.requestId	ZZ
u08	info.displayId.len	13
Array of u08	info.displayId.value	'ChattingChuck'
u16	info.evil	0
u16	info.attrs.num	1
u16	info.attrs[0].tag	1 (OSERVICE__NICK_INFO_TAGS_NICK_FLAGS)
u16	info.attrs[0].len	2
u16	info.attrs[0].value	0
u16	locateInfo[0].tag	13 (LOCATE__TAGS_HTML_INFO_TYPE)
u16	locateInfo[0].len	9
Array of u08	locateInfo[0].value	'text/html'
u16	locateInfo[1].tag	14 (LOCATE__TAGS_HTML_INFO_DATA)
u16	locateInfo[1].len	100
Array of u16	locateInfo[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"