aimInfo

Wednesday, February 7, 2007

While all of us are working hard on getting the next AIM 6.1 beta out the door, and yes, it is coming soon, I thought I would share how exactly you can build your own AIM Widget.  Before we write code, the only requirements you need to have is AIM Lite (http://x.aim.com/laim), a compression program (WinZip), and your favorite text editor (Notepad, etc).  Now we need to decide what kind of widget we want to write.  Because you have access to the full AIM API, your widget can access any of the same functionality that the client can implement.

One thing that AIM Lite has not implemented is the playing of a sound when a buddy arrives or departs.  So lets build this widget.

Step 1 - Get an Open AIM plugin key
------------------------------------------------------
 - Go to http://developer.aim.com and get a developer key for the plugin.
 - Create a new folder for the widget files.  For example c:\BLSoundWidget

Step 2 - Create the plugin.xml file
------------------------------------------------------
 - Create a new notepad file and save it as "c:\BLSoundWidget\plugin.xml"
 - Paste the following XML into the notepad file:

<?xml version="1.0" encoding="utf-8" ?>
<widget
    uuid            = "<!---PLACE DEVELOPER KEY HERE---!>"
    name            = "Buddy List Sounds"
    version         = "0.1"
    description     = "Play a sound when a buddy signs on or off"
    vendor          = "<!---YOUR NAME GOES HERE---!>">
</widget>

 - Save the file.

Step 3 - Create the main.box file
------------------------------------------------------
 - In the c:\BLSoundWidget directory create a new folder called "content".
 - Open a new notepad file and save it as "c:\BLSoundWidget\content\main.box".
 - Main.box is the main entry point for the Open AIM engine (acccore.dll) to load the plugin.
 - In this widget, we will not need a user interface, but if we were, it would be created here.  For more information on how to build a user interface using Boxely, check out the documents here.
 - Paste the following code into the main.box file:

<?xml version="1.0" encoding="UTF-8"?>
<window
    xmlns="http://www.aol.com/boxely/box.xsd"
    xmlns:s="http://www.aol.com/boxely/style.xsd"
    xmlns:on="http://www.aol.com/boxely/reaction.xsd"
    on:constructed="onConstructed();"
    on:destroyed="onDestroyed();"
    s:height="0"
    s:width="0"
    hidden="true"
    collapsed="true"
    floating="true"
>
    <code id="main" language="jscript" src="main.js"/>
</window>

 - Basically this code will call onConstructed when the plugin is loaded, and onDestroyed when the plugin is unloaded. Finally, we tell AIM that it can find these two functions in a file called main.js.

Save the file.

Step 4 - Create the main.js file
------------------------------------------------------
 - Almost done...we just need to code up the javascript file that will play the sound at the appropriate time.
 - Create a notepad file and save it as "c:\BLSoundWidget\content\main.js".
 - We want to add code for onConstructed first.  Typically, in onConstructed, the scene will want to access the Open AIM register for events, and possibly add plugin commands.
 - AIMCC objects are accessed in the scene via scene.paramsDictionary. The "session" key hold the IAccSession object, and the "pluginInfo" key holds the IAccPluginInfo object for the plugin. There correspond to the IAccSession and IAccPluginInfo objects that are typically passed into the IAccPlugin::Init method.

 - Paste the following code:

function onConstructed()
{
    var session = scene.paramsDictionary.valueForKey("session");
    scene.connectObject(session, "session_");
}

 - We also want to clean up properly when the plugin is unloaded:

function onDestroyed()
{
    scene.disconnectObject("session_");
}

- Now we need to listen for when buddies arrive or depart on the buddy list.  The Open AIM event that does this is OnUserChange.  When the widget gets this event we will need to see if the buddy has signed on or off:

function session_OnUserChange(session, oldUser, newUser, property, result)
{
    var newState = newUser.State;
    var oldState = oldUser.State;
    if (newState >= 1)  // user signed online AccUserState_Online == 1
        appUtils.playSound(scene, "online.wav");
    else if (oldState >= 1) //user signed offline
    appUtils.playSound(scene, "offline.wav");
}

 - That's it, we will now play the wav file online when a user signs online, and offline when they sign off.

Step 5 - Packaging up the widget
------------------------------------------------------
 - Now we have to package up the widget so AIM Lite can install it. 
 - Zip up the desired files (including the required plugin.xml and main.box) into a ZIP file with an .awi extension
 - Double click on the awi file, and AIM Lite will load if it is not running currently, and load your plugin.

Step 6 - Deploy your plugin
------------------------------------------------------
 - After you have tested your plugin, and are ready to deploy it, you will want to go back to developer.aim.com to get a deploy key.
 - Modify the plugin.xml with the deploy key and repeat step 5 from above.
 - Before deploying the awi file, you will want to use the acchash tool, which is available as part of the Open AIM SDK.  Use the hash tool to generate a finger print and paste the fingerprint in the same place where you requested a deployment key.



Congrats you have just deployed your first Open AIM plugin.  The next step for your widget may be to add a command that launches a preference window where I can select my own wav file to play when a buddy signs on or off, but that is an exercise left to the reader.

You can check out what I built here.


gregsblog at 5:26:00 PM EST Blog about this entry |  Add to del.icio.us |  digg this

This entry has 0 comments: (Add your own)