What is it?

A lightweight javascript library and components to allow for interfacing with the host WIM APIs.

• aimapi-core.js - 45.4 KB (14.5KB Packed)
• swfsocket.swf (optional) - 2.9 KB
• scriptiframe.js (optional) - 9.7 KB

Events and Transactions

The API is based around the notion of events and transactions.

• Events are things that host wants the API to know.
• Transactions are things the API tells the host.

Events

• IM Events: im, dataIM, sentIM, sentDataIM, offlineIM
• Presence Events: buddylist, presence, myInfo
• Misc Events: sessionEnded, typing, userAddedToBuddylist
• Upcoming Events (possibly): imserv

Using Events

The API uses one of three ways to get events from the host:

• Long polling with dynamic script nodes
• Long polling with an iframe
• A socket with Flash

Original Flavor

The original way of listening for host events was with a long polling script node.

• Tends to run memory usage through the roof after a while if you don't clean up after yourself.
• Randomly crash browsers in exciting ways if you do clean up after yourself.
• Doesn't work well in Firefox.

This is the third and final fallback method for listening for host events.

scriptiframe.js

This method uses an iframe to long poll for host events.

• Isn't as memory intensive as script polling.
• Doesn't work in Opera.

This will only be a fallback from sockets if scriptiframe.js exists.

swfsocket.swf

A headless SWF that waits for events on a socket connection.

• Lightweight: only 4k
• Requires Flash 9 and swfobject.js
• Not abusive to browser memory consumption.
• Doesn't interfere with the browser's HTTP stack.

This is the preferred method for listening for host events.

An Example Event

({
fetchBaseURL:"http://205.188.211.117/aim/fetchEvents?aimsid=003.1085843290.2143459418:iheartwim&seqNum=7&rnd=1245180775.324854", 
timeToNextFetch:500, 
events:[{
    type:"im", 
    eventData:{
        source:{
            aimId:"myTestSN", 
            displayId:"myTestSN", 
            friendly:"myTestSNFriendly", 
            state:"online", 
            onlineTime:15252, 
            userType:"aim", 
            beboProfile:1,
            buddyIcon:"http://api.oscar.aol.com/expressions/getAsset?t=myTestSN&f=native&id=0010a432a5ef70cde4603055078d5f91a61a&type=buddyIcon", 
            presenceIcon:"http://o.aolcdn.com/aim/img/online.gif"
        }, 
        message:"hey", 
        autoresponse:0, 
        timestamp:1245180775
    },
    seqNum:6}
]})

Event Properties of Interest

• fetchBaseURL: The URI to open a listener connection to
• timeToNextFetch: Time, in milliseconds, before you should open a new connection to the host.
• seqNum: Sequential event order identifier. This can be used to go back in time for older events if needed.

How do I access that data?

The API offers support for registering multiple callbacks for transactions and events.

• AIM.params.callbacks.listener.im.push("yourApp.callbacks.im")
• AIM.params.callbacks.startSession.push(yourApp.callbacks.startSession)

Events route through AIM.core.listen, and transactions through AIM.core.acceptData. Each delegates the data to the callbacks you have registered in the order you've registered them.

Note: You can register callbacks by string or function. String registration exists so you can define callbacks before they exist.

API Specific Events

There are several API related events that an application can register for:

• deadConnection: If the API determines that it has lost its connection
• transactionTimeout: When a transaction doesn't respond with AIM.params.TRANSACTION_TIMEOUT
• socketClosed: swfsocket encountered an issue that resulted in it closing down its socket

Defining Custom Callbacks

Applications can use the callback architecture for their own transactions.

1. Define AIM.params.callbacks.newCallBackType as an array
2. Set up a transactionObject with a type parameter that matches newCallBackType
3. Pass transactionObject to AIM.core.requestData

Transactions

• Authentication: getToken and startSession
• Presence: setState, setStatus, etc
• Misc: setTypingStatus, reportAction, removeBuddy, etc

Transaction Example

Request:

http://api.oscar.aol.com/im/sendIM?aimsid=056.1598172945.0816096482:iheartgromit&message=hey!&t=myTestSN&f=json&
c=AIM%2Ecore%2EacceptData&offlineIM=1&r=12&nocache=1245336904000

Response:

AIM.core.acceptData({
        "response":{
            "statusCode":200,
            "statusText":"Ok",
            "requestId":"12",
            "data":{
                "subCode":{
                    "error":0
                 }
             }
        }
    })

Mapping an Asynchronous Request to its Response

When a transaction is made, a parameter called "r" is passed up along with the request.

The value of this parameter is passed back in the response as requestId. This allows the client to tie them together.

Working with Transaction Responses

Transaction responses always come with a statusCode. Some common ones:

• 200: Everything is great!
• 450: Rights denied. Generally means the user isn't authenticated
• 607: Rate limited

All of these map back to the Open Services ARC Standards defined here: http://wiki.office.aol.com/wiki/Open_Services#Status_Codes

Other Notable Transaction Parameters

• f: Response format. Valid values are json, xml, amf0, amf3 and occasionally qs. We always use json.
• c: Callback. What the json response will be wrapped in.
• aimsid: The AIM session id, often interchangable with an authentication token. (arg is "a")
• nocache: This is a random number who's only purpose is to prevent the browser from caching the response. Every outgoing transaction has this parameter appended. The host does nothing with it.

Getting Started

A typical application would define the following vars:

• AIM.params.wimKey: The developer key from dev.aim.com
• AIM.core.subscriptions: The events your application is interested in hearing about.
• AIM.params.useSWFListener: Tells the API to use swfsocket.swf
• And all of the callbacks you need.

AIM.params.DEBUG

Setting this to true in your application will result in a very verbose log being written to the page that details nearly everything the API is up to.

Other interesting things ...

• Anonymous Sessions
• sentIM Event
• dataIM

Example

Coming soon!

Where can I get it?

• Google Code: http://code.google.com/p/aimapi-core/
• SVN: /webaim/aimapi-core/