BOTS!!!

An AIM Bot is a screen name that can respond automatically to the IMs it receives. I added more information to the article to the AIM Dev Site which explains the different types of BOTs AOL offers to consumers and partners. The two types are Enterprise BOTs and Consumer BOTs.

Here is a comparison chart that outlines the difference between an Enterprise BOT and a Consumer BOT.

We do have C++ and Java samples that demonstrate how to develop a BOT.

Open AIM SDK Custom Session C++ Sample

I just released a sample written in C++ that demonstrates the custom session feature in the Open AIM SDK 1.8.2. This code works in both Windows and Linux (tested on Ubuntu and CentOS). This sample is called acccssample, and you can download the source code here. The source code is cross platform, you can choose to build it in Windows using acccsample.vcproj, or use Makefile with g++ under Linux. This sample basically signs on and then allows the user to initiate the Custom Session as follows:

Usage:

acccssample.exe screenname password initiateflag where initiateflag = true or omit parameter.

You can run two instances of this app one to initiate a custom session and one which auto accepts the custom session to test this.

On the initiating side, when you see the below prompt, initiate a custom session with a buddy who is set to receive the custom session:

Enter c:s screenname to initiate a custom session with a buddy

Here are some code snips with some explanation:

// First, assert capability, which is a GUID of your choice that both the initiator and the recipient recognize
// You can do this as soon as your client goes online.
void OnStateChange(IAccSession* piSession, AccSessionState state, AccResult hr)
{
    if (state == AccSessionState_Online)
    {
        HRESULT hr = piSession->AddCapabilities(CAccVariant(kCSCapability));
        printf(“AddCapabilities, hr=%08X\n”, hr);
    }
}

// start a custom session with the buddy
void StartCustomSession(xp_str buddy)
{
    // for demo purposes we only support one session at a time
    if (m_customSess == NULL)
    {
        printf(“Start Custom Session”);
        CAccVariant val = 0;
        val.vt = VT_INT;
        val.intVal = 0;
        const CAccBstr uuid_CAccBstr(“{39BB91C6-5134-4662-AFB3-188D42FD95AC}”);
        xp_str uuid1(uuid_CAccBstr);
        HRESULT hr = m_sp->CreateCustomSession(uuid1, &m_customSess);
        m_customSess->put_Property(AccCustomSessionProp_Mode, val);
        m_customSess->Invite(buddy, OLESTR(“Join me in this custom session”), &m_transid);
    }
else
    printf(“Custom Session already exists…”);
}

// Accept the Custom Session at the receiving end.
void OnSecondarySessionStateChange(IAccSession* piSession, IAccSecondarySession* piSecSession, AccSecondarySessionState state, AccResult hr)
{
// always accept incoming custom sessions
if (state == AccSecondarySessionState_ReceivedProposal)
{
    CAccVariant v;
    piSecSession->get_Property(AccSecondarySessionProp_RemoteUserName, &v);
     AccSecondarySessionServiceId id;
     piSecSession->get_ServiceId(&id);
    CAccBstr x = CAccBstr(v.bstrVal);
    char tmp[255];
    x.GetUtf8(tmp, 255);
    printf(“{%s} has sent you a custom session proposal\n”, tmp);
    printf(“We are auto accepting the proposal for testing purposes…\n”);
     piSecSession->Accept();
    }
}

// send a test message to the buddy
void SendCustomMessage(xp_kstr msg)
    {
    // since this session is a message only session
    // we can just send an IM.
    CAccPtr im;
    HRESULT hr = m_sp->CreateIm(msg, OLESTR(“text/plain”), &im);
    m_customSess->SendData(NULL, 0, im);
}

Reading capabilities in c++

Here is sample C++ code which works in accsample deployed with the Open AIM SDK. You can copy and paste the below code and see the capabilities in a debugger.

void OnUserChange( IAccSession* session, IAccUser* oldUser, IAccUser*
newUser, AccUserProp Property, AccResult hr)
{
    CAccVariant cv;
    newUser->get_Property(AccUserProp_Capabilities, &cv);
    SAFEARRAY *psa = V_ARRAY( &cv );
    if(!psa)
    {
        printf(“Why can’t I get capabilities!!”);
    }
    int n = psa->rgsabound[0].cElements;
    for (int i = 0; i < n; i++)
    {
        CAccVariant item;
        long rgIndices[1];
        rgIndices[0] = i;
        SafeArrayGetElement(psa, rgIndices, &item);
    }
}

Check out the latest Open AIM Newsletter!

The Latest Open AIM Newsletter was released yesterday and is available here. You can subscribe to the newsletter here.

Going forward, we plan to send out a newsletter once a quarter and we’d like to include topics that you’d like to hear about. Please take a few moments and let us know what you’d like to see in the newsletter by posting comments in the Developer’s Dialogue forum.

Obtaining a Buddy Icon using Web AIM

In order to obtain a buddyIcon you would invole the following URL using HTTP:

http://api.oscar.aol.com/expressions/get?f=xml&t=[screenname]&type=buddyIcon

Where [screenname] is the person you’re looking to find the icon URL for. It will return an XML page that has all the info for screenname.

For example, check out the following link using a test screen name as the target argument for a test buddy who has an icon:

http://api.oscar.aol.com/expressions/get?f=xml&t=mtest004&type=buddyIcon

This should return an XML response with all the details, including the url field.

Response below. To view the icon, navigate to the URL field… http://api.oscar.aol.com/expressions/getAsset?t=mtest004&f=native&type=buddyIcon&id=0110b2e8a16872c770f2147cc10da91f419b

<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<expressions>
<expression>
<type>buddyIcon</type>
<url>

http://api.oscar.aol.com/expressions/getAsset?t=mtest004&f=native&type=buddyIcon&id=0110b2e8a16872c770f2147cc10da91f419b

</url>
<id>0110b2e8a16872c770f2147cc10da91f419b</id>
</expression>
</expressions>
</data>
</response>

Check out the following link using a test screen name as the target argument for a test buddy who does NOT have an icon:

Request:

http://api.oscar.aol.com/expressions/get?f=xml&t=mtest0002&type=buddyIcon

Response: Note that there is no expression or icon for this test Screenname.

<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<expressions/>
</data>
</response>

AIM 7 Beta 3 released!

Check it out!!! We just released a new AIM 7 Beta 3 with some cool new features! Please download and help us test drive this beta and send your valuable feedback, if you find any issues or have some ideas, you can click on the “Beta Feedback” link and leave a comment.

A major new and exciting feature is the Lifestream! From the release notes, here is what it basically offers…

Keep tabs on what’s going on with your buddies. We’ve added a convenient “Lifestream” tab to the Buddy List. There is so much to check out:

* Get AIM activities like status updates.
* Got friends on other networks? Add your Facebook or Twitter services and never miss an update.
* You can add your YouTube or Delicious accounts too.
* Leave a comment, like an item. Obviously, if your friends don’t have the beta they won’t know about the Lifestream so if you want to try out commenting back and forth with someone make sure they have the beta too.
* See only what you want, try out the handy filtering tool at the top of your Lifestream tab.
* Share photos on your lifestream. Look for Photos section on the right of the page and start uploading.
* Test out the rest of the site, including adding services (click settings at the top of your page), filtering, and more.

You can also upload pictures with your status messages from your PC that will appear next to your status message in AIM 7 and in the lifestream. For now, the pics will be shown next to your status only when viewed by AIM 7 and lifestream users.

New Open AIM Sample

I added a new sample called accfed to the Open AIM Dev site. This is a sample written in C++ that demonstrates how to log into Open AIM using federated tokens and a session secret obtained from a Web AIM application. You need to pass in the federated screenname and do not need a password, but instead pass in your DevId of the Web AIM application that is authenticated using Open Auth and the token and the session secret obtained from the response.

The DevId parameter has to match the DevId of the web application from which you obtain the Token and SessionSecret.

Usage: accfed myUserName myDevId myToken mySessionSecret

Example usage…

accfed mytestsn@myfederatedaccount.com ch1t2PGGC_d42BW1 %2FwQAAAAAAADhcsw5R7qRa5Q094F%2FKh9zooQ
VkorkmECTTU9MSkvjRzg%2Bj%2FhO8D5pOnJGU45qo
KT%2BcF%2FVkzLAYEbAzxdchHc07DpCgrNCKqarreIFue
WpsXLupdnQ51KBLdKZc99YuGevgKJEeiUiFNJMNJM%3D NpW6vM371VSvtK7w

The above methodology is only relevant for AOL partners who are either pursuing or already have a federated partner arrangement so that their non AIM credentials can authenticate into AIM.

The Open Auth documentation for the ClientLogin API is here. This API is ONLY available for use with desktop applications are not web based applications.

There are more documents and samples on the main Open Auth site too.

Open AIM SDK 1.8.2 released!

The new Open AIM SDK 1.8.2 supports Windows, Linux, Mac OSX and Mobile! Check out the new cool features of this release and try out the samples! You can download the SDK here.

You can do a lot with the SDK, build your own BOTs, write custom clients, AIM Widgets, Mobile applications using the Web AIM SDK and if you choose to partner with AOL to develop products, check out the AIM Partner Site.

You can check out the AIM Gallery to see what other developers have published.

Functional changes from the Open AIM SDK 1.6.8 to 1.8.2:

- Added aimcc.alerts.aware, aimcc.alerts.enabled and AccAlertProtocol.

- Added AccSessionProp_FederatedAuthToken and AccSessionProp_FederatedAuthKey.

- Added IAccUser::ReportForSpim() and AccReportSpimInitiation.

- Added AccUserProp_BuddyFeedFaviconUrl, AccUserProp_CellNumber, AccUserProp_HomePhoneNumber, AccUserProp_OtherPhoneNumber, AccUserProp_SmsNumber and AccUserProp_WorkPhoneNumber.

- Added AccGroupProp_Blast and AccGroupProp_Permissions.

- Added AccAvTrackProp_Genres, AccAvTrackProp_AlbumName, AccAvTrackProp_AlbumLink, AccAvTrackProp_ArtistName, AccAvTrackProp_ArtistLink, AccAvTrackProp_PlaylistName, AccAvTrackProp_PlaylistLink, AccAvTrackProp_PodcastName, AccAvTrackProp_PodcastLink, AccAvTrackProp_SeriesName, AccAvTrackProp_SeriesLink, AccAvTrackProp_StartTime and AccAvTrackProp_Duration.

- Added AccUpgradeInfoProp_Hash.

- Added AccSessionProp_NewAccount.

- Added ACC_E_UNCONFIRMED_IDENTITY.

- Added preferences aimcc.buddies.[normalized escaped username].cellNumber, aimcc.buddies.[normalized escaped username].homePhoneNumber, aimcc.buddies.[normalized escaped username].otherPhoneNumber, aimcc.buddies.[normalized escaped username].smsNumber, aimcc.buddies.[normalized escaped username].workPhoneNumber, aimcc.buddyList.autoOfflineGroup, aimcc.connect.emailAccountType, aimcc.folders.morePlugins and aimcc.im.direct.receiveRtim.

- Updated Technote 13 with example XML AIM Module.

- Added Technote 14 about Real-Time IM.

- Added support for sending in standard IMs for some types of accounts.

- Added to languages supported for AccClientInfoProp_Language.

- Updated AccUserProp_BuddyFeedUrl.

- Improved aimcc.plugins.safemode implementation.

- Sending secondary session invitations is now throttled to avoid rate-limit errors.

- Changed result of getting unknown bart items from ACC_E_NO_DATA to ACC_E_MUST_REQUEST_DATA.

- Changed result of getting missing/empty bart items from S_OK/VT_EMPTY to ACC_E_NO_DATA

- Deprecated AccGroupProp_Shared.

- Deprecated AccSessionProp_AppearOffline.

- Deprecated AccUserProp_AwayMessage (use AccUserProp_RichStatusMessage).

- Deprecated AccSessionProp_MaxAwayMessageLength (use AccSessionProp_MaxRichStatusMessageLength).

- Deprecated AccGroupProp_ReadOnly (use AccGroupProp_Permissions).

- Deprecated AccSessionProp_SuperIconTrigger and AccUserProp_SuperIconTrigger.

- On Win32, added AccPluginCleanup().

- On Win32, revamped AV device management, including dependency on setupapi.dll.

- On Win32, added support for VS2008.

- On Linux & Mac, added AccMessageAvailable().

- AccSupport:
- Added xp_s64 support to CAccVariant.

For more details on the fixes of this release, please refer to the release notes.

Building Open AIM SDK samples for Linux

I have had several queries on Open AIM Forum on building the Open AIM SDK samples for Linux, the SDK and samples can be downloaded here.

Once you untar the SDK and samples, you need to set LD_LIBRARY_PATH by exporting the following, adjusting the path to wherever your SDK is installed.

export LD_LIBRARY_PATH=/home/gmadkat1/accsdk_linux_rhe4×86_1_8_2/dist/release

You also need the Mozilla NSS libraries installed in order to run the samples, this is security software for SSL AIM sessions. More details found here.

You will need Apache Ant in order to build the Java samples. There is a Java BOT sample and a simple Java signon and signoff sample included for the Linux Distribution.

There also equivalent C++ samples for demonstrating a BOT and signon and off, they are easily built using make.

The binaries built above are put into the dist/release directory and can be run from there.

In order to run the Java samples, you need to do the following Java commands in Linux…

java -cp accjwrap.jar:. AccJSample myScreenname mypassword Key:dsdsdsd_deaZdsdd

java -cp accjwrap.jar:. accjbot myScreenname mypassword

AIM URL Documentation

I just added a new page on the AIM Developer site for documenting AIM URLs that are supported by the AIM 6.9 client. Look on the Documentation pane to the left of the http://dev.aol.com/aim site and follow the URL to the AIM URL Documentation.

The AIM URLs are a methodology used to send commands that are executed by the AIM 6.9 client for automatically creating an Instant Message, a chat room, or a Buddy List entry.

URLs can allow web pages to pass commands to AIM clients.

You can launch AIM: URLs in several ways:

1. In Windows, enter the command in the Run dialog from the Start Menu.
2. Click on a hyperlink in the IM history window.
3. Click on a hyperlink in a web page (or just type the URL in the browser’s URL field).

They will work when the user is already online with AIM, when the client is not launched and when the client is launched but not signed on it will prompt to do so.

The URLS documented are…

aim:AddBuddy
aim:AIMToday
aim:BuddyIcon
aim:CheckMail
aim:DockBuddyList
aim:GoAway
aim:GoChat
aim:GoIM
aim:GoTalk
aim:Prefs
aim:RegisterUser
aim:SetItem
aim:SetOption
aim:SetStatus

Here is a link to Gus’s website to some handy tools that help you create some of these AIM URLs.

AIM Presence icons on your website

A user asked us a question, they use fetchEvents method and get event BuddyListEvent, but presenceIcon is empty in the “Presence” in the response.

The AIM Host is configured to not send presence icons in buddylist events, this is because of the overall size of the response when users had large buddylists.

But you can check the state of the buddy, ie online or idle or offline and the icons are static and their location fixed, so you can easily access them programatically.

eg http://o.aolcdn.com/aim/img/online.gif

http://o.aolcdn.com/aim/img/offline.gif

http://o.aolcdn.com/aim/img/mobile.gif

http://o.aolcdn.com/aim/img/idle.gif

http://o.aolcdn.com/aim/img/away.gif

Web AIM SendIM error codes

I got a question recently asking the below, the following is not yet documented on the AIM Developer site so I am adding it here until it does make it to the site.

sendIM method response format is SendImSubCode.
It has 2 fields:
1. subError
2. subReason
Is there any documentation about subError codes?

Errors: Format below is Values and Description

0 No subcode supplied
1 Remote im is off
2 Remote restricted by PC
3 User tried to send a msg to a SMS user and is required to accept the
legal text first
4 Client tried to send msg to SMS user without the char counter being displayed
5 Client tried to send msg to SMS but SMS matrix said coco combination not
permitted
6 Client tried to send msg to user they can’t im
7 Required payment
8 Client tried to send to a SMS user, but host couldn’t determine country
9 An IM cannot be initiated by a BOT
10 An IM cannot is not allowed by consumer BOT to an user
11 An IM cannot is not allowed by consumer BOT due to usage limited
12 An IM is not allowed by consumer BOT due to daily usage limited
13 An IM is not allowed by consumer BOT due to monthly usage limited
14 User does not accept offline IMs
15 Exceed max storage limit
16 Multi file transfer request blocked by host

Modify your buddy icon in C#

One FAQ I run into is how to set preferences, specifically buddy icons using the Open AIM SDK. Here is some C# code that does the icon setting. You do need to have an image that meets the size restrictions for buddy icons, the easiest way to determine the size is to save your existing buddy icon and view it in Firefox to get the dimensions in pixels. You can then downsample your image and convert it to the size that is optimal. I tested this code using awshbuddy deployed with the Open AIM SDK. piSession is your primary session object which you can obtain from any DAccEvent callback and also save as a global. The same general idea below applies to a C++ client, pass in the image as a variant array to Prefs.SetValue and it will work.

System.Drawing.Image imgfile = System.Drawing.Image.FromFile(“c:\\mytestimages\\test.gif”);
MemoryStream ms = new MemoryStream();
imgfile.Save(ms, System.Drawing.Imaging.ImageFormat.Gif);
Byte[] buffer = new Byte[ms.Length - 1];
ms.Position = 0;
ms.Read(buffer, 0, buffer.Length);
piSession.Prefs.SetValue(“aimcc.personalityDefault.0.data”, ms.ToArray());
piSession.Prefs.SetValue(“aimcc.personalityDefault.1.data”, ms.ToArray());
ms.Close();

Check out aimapi-core

If you want to integrate AIM into your web app with javascript, AOL just released a new library to help you do this, it is the aimapi-core library. The theBoot.com website we had released recently which I had mentioned in the below post is created using this API.

You can also use this API if you want to integrate AIM into a Flash, Flex, or AIR app.

AIM 6.9 is released

Check it out! This is the product I was the development lead on before I moved to Open AIM so I feel a certain sense of nostalgia. You can download it off the AIM Website. My favorite feature, and one that I am happy to share, is that the old AIM Running Man is back.

Apart from performance improvements, you can get status updates from your friends on Twitter and other apps. And if you are looking to add buddies, find them easily with the new look up tools. More information available here. You can also find other reviews on Gus’s blog and Greg’s blog.

Stay tuned for a new Open AIM SDK, with the latest API additions that correspond to the AIM 6.9 release.

Obtaining the online state of a participant in an IM session

Another frequently asked query I run into is how to find the state of an IAccParticipant (Online, offline or idle)? Some DAccEvent callbacks like BeforeImSend pass in an IAccParticipant and not an IAccUser.
You can use the get_User method to get an IAccUser object for the participant and then get the state…

IAccParticipant* pPart;
IAccUser* pUser;
HRESULT res = pPart->get_User(&pUser);
if (pUser) // check result too
{
    CComVariant st;
    pUser->get_Property(AccUserProp_State, &st);
    xp_int state = st.intVal;
    switch (state)
    {
    case AccUserState_Away:
    case AccUserState_Idle:
    case AccUserState_Online:
    // do what you need
    break;
    case AccUserState_Offline:
    break;
    }
}

Socialthing and theBoot

Check out the following really cool site AOL just released… theBoot.com, there is a very good review of it on TechCrunch here. That is a comprehensive review and I do not have much to add to it!

After you visit theBoot, you will see a thin toolbar along the bottom that is labeled Socialthing on the bottom left and on the bottom right there is a sign in button which is for signing in using your AIM account. Once you sign in, your AIM username and password becomes your username and password for the site, and you can access your Buddy List and chat with your buddies. You can choose to always share your activity on the site with the privacy options.

If you comment on a story or do other actions, that comment or action appears not only in the site updates stream, but all of your buddies on AIM 6.9 will see a little info icon next to your name and you can see it if you expand on the AIM 6.9 client.

Please check it out and send comments and feedback! Below is a screenshot of the experience…

AIM 6.9 Beta 4 released

You can download it from here.

This release has some performance enhancements, and emphasizes on friend-finding tools, ways to follow your friends’ updates from sites like Twitter and YouTube, ability to display your photo in your Buddy Info. Please download, try it out and send us your feedback on the beta site or the message boards!

Here is a screenshot of how the new interface looks like…

I left my mind on the beach

I will post in a bit, was out all of last week on Sanibel Island, and need a brain reset back to AIM Land

AIM Presence and AIM URLs

If you want to detect presence of a Screenname on your website and send the person an IM, here is now to do it. Try the following in a browser for a Screenname that you know is valid, and you will see an icon to indicate if the user is online, offline, mobile, idle or away.

http://api.oscar.aol.com/presence/icon?k=ka17kh28wBBZ01b0&t=ScreennameToSendTo

Directs to the following depending on presence..

http://o.aolcdn.com/aim/img/offline.gif

http://o.aolcdn.com/aim/img/online.gif

http://o.aolcdn.com/aim/img/idle.gif

http://o.aolcdn.com/aim/img/mobile.gif

etc…

Now if you want to launch an AIM 6.8+ client to send them an IM, you can do the following AIM URL..

aim:goim?screenname=ScreennameToSendTo&message=Hi,yt?

There are some aimurl generator tools on my friend and co-worker, the AIM Architect Gus’s Website to help anyone create AIM URLs for goim, gochat, setstatus and more.

You can get more details on the aim url about page at here.

The pages let you enter the parameters and it generates the URL as you type.

Categories of groups in the AIM 6.8/6.9 client

In the AIM client buddy list, you can organize your buddies into Groups. The categories we support in AIM 6.8 and AIM 6.9 are explained here, I am seeing some confusion about this since we do not allow some groups to be deleted in the client, even programatically.

There are two categories of Groups, Private groups and Public Groups or alternatively, one of my blog readers suggested in a comment,  Standard vs Auto groups . A Private group would be a group unique to your Buddy List that you created, and you have total control over it. For example, “Work”, “Buddies”, “AIM Dev”, etc. You control who get’s added or removed or even if the group exists.

A Public group is one that is created by other means. This allows you to create or join a group via a webpage and it automatically added a Buddy List Group of all the members to your Buddy List. IM Blast Groups behave this way. You join the Blast Group. It gets added to your Buddy List. When you leave the group, the group is removed from your Buddy List.

“Bebo”, and “My WIMZI” are groups that can not be deleted.

Smart Groups – http://buddyinfo.aim.com/sg to manage them.
Wimzi – http://wimzi.aim.com/ – click on manage.
Bebo – Not currently deletable.
Blast – http://blast.aim.com – you can go to blast.aim.com and unsubscribe from the group which will make the group disappear from your Buddy List.

Web AIM Server API for pushing feeds

The Web AIM API lets developers incorporate core AIM functionality into any web page, including the ability to sign on, send and receive IMs, and obtain a user’s Buddy List. The API I am going to provide some detail on allows you to push a simple Buddy Feed Item so that your buddies can view them via the AIM 6.8 and 6.9 beta clients through your buddy info.

The usage of the API is detailed on the AIM Developer Site for the Web AIM Server API Reference.

There are 2 options for how to call this API and I will provide usage examples for both. I am not providing code here, since it is too voluminous for a blog post, but please contact the AIM Developer Forum for API usage and sample code.

The first option uses the aimsid parameter which is obtained by the http://api.oscar.aol.com/aim/startSession API, as a part of the response. You can invoke this API and save the aimsid for use below. I have shown the response below as well.

http://api.oscar.aol.com/buddyfeed/pushFeed?&f=xml&aimsid=051.0352240858.1661937412:mytestsn&feedDesc=Testing.&feedLink=ht

tp://www.aol.com&feedTitle=TestFeedTitle&itemDesc=TestingFeed!&itemGuid=StMsg1236891813000&itemLink=http://www.aol.com&it
emTitle=TestTitleFeed!&k=mo1XK7vb5IyNRmU9&nocache=1236891813000&r=10&ts=1237777627

<response xmlns=”http://developer.aim.com/xsd/buddyfeed.xsd”><statusCode>200</statusCode><statusText></statusText><requ
estId&gt10</requestId><data></data></response>

The second option uses the a= parameter for passing the token…

http://api.oscar.aol.com/buddyfeed/pushFeed?a=%2FwQAAAAAAABR%2BtiXoKOkbBhKHxjZMSWKiwKS2fvVKaR1fUQQQd12TENtC8bgQko99nIS42

hW98dzNsIQ7FkHmtLOBdrzYY6KWb4LGRblEN4kg6DRIfEEwHlP1CazdmDpK1N38Cu45Vu3EQQzr9hqdZpYMOC1K
59dJBZooqwCZM1CPuoX0tZLao88X5s%3D
&f=xml&feedDesc=TestingFeed.&feedLink=http%3A%2F%2Ffoo.aol.com&feedTitle=TestFeedTitle&itemDesc=TestFeed1&itemGuid=StMsg12368918
13000&itemLink=http%3A%2F%2Fwww.aol.com&itemTitle=TestTitle&k=mo1XK7vb5IyNRmU9&nocache=1236891813000&r=10&ts=1237773442

<response xmlns=”http://developer.aim.com/xsd/buddyfeed.xsd”><statusCode>200</statusCode><statusText></statusText><requ
estId&gt10</requestId><data></data></response>

Note that you do need to encode the url based parameters that are passed in for the token based request to work.

You can use this… java.net.URLEncoder.encode(“http://foo.aol.com”, “UTF-8″));

Buddy Status Text

Here is some sample C++ and Java code to sign on and set the status text of the logged in user. This is a code snip taken from the C++ and Java samples accsample & accjsample in the Open AIM SDK 1.68 and modified to set the status text for the user.

C++ Code snippet below…

CAccPtr sp;
HRESULT hr;
if (SUCCEEDED(hr = AccCreateSession(IID_IAccSession, (void**)&sp)) && SUCCEEDED(hr = Advise(sp)))
{
    CAccPtr spClientInfo;
    hr = sp->get_ClientInfo(&spClientInfo);
    if (SUCCEEDED(hr))
    {
        CAccVariant desc(“accsample (key=dummykeyreplacewithrealkey)”);
        spClientInfo->put_Property(AccClientInfoProp_Description, desc);
        if (SUCCEEDED(hr = sp->put_Identity(CAccBstr(userName))))
         hr = sp->SignOn(CAccBstr(password));
        sp->put_Property(AccSessionProp_StatusText, CAccVariant(“Testing setting a status”));

Java code below…

try {
    // Create main session object
    session = new AccSession();
    // Add event listener
    session.setEventListener(this);
    // set key
    AccClientInfo info = session.getClientInfo();
    info.setDescription(key);
    // set screen name
    session.setIdentity(username);
    session.signOn(password);
    session.setProperty(AccSessionProp.StatusText, new AccVariant(“i am trying this out”));
} catch (AccException e) {
    log(“Exception: ” + e.errorCode);
    e.printStackTrace();
}

If the user does not have a status set, the call will throw an exception and you need to catch it and act on it if you desire.

Here is some sample Java code to get a status of all your buddies on your Buddy list. There is a bug in the current Open AIM SDK 1.68 in which the getStatusText for a user with no status set returns ACC_E_TYPEMISMATCH but in the 1.8 branch, it is failing with ACC_E_NO_DATA, which makes more sense if there is no status set.

Java code below… this assumes you already have a buddy AccUser object called buddy below. For an example on traversing the buddy list, look at my post here.

try {
    AccBartItem b = buddy.getStatusText();
    String status = b.getDataObject().getString();
    System.out.println(” Status Message: “+ status);
    // alternatively…
    System.out.println(” Status Message: ” + new     String(buddy.getStatusText().getData()));
}
catch (AccException e) {
    log(“getStatusText failed” + e.errorCode);
    e.printStackTrace();
}

AIM 6.9 Beta 3 released

We just released a new AIM 6.9 client beta here.

Some of the changes in this release are new theming, changes to the profiles, addition of Bebo profiles integration into the client, status messages in the IM window, and the ability to express emoticons as text.
A cool new feature is AIM Blast, you can use this to IM your friends, coworkers, or customers all at once.

Some under the hood changes are the migration to using the VS2008 compiler and runtime, and some performance optimizations.

Sample code to add/remove buddies

This is asked frequently enough on the AIM Development forums that I decided to post some code for future reference. The Open AIM SDK and the Open AIM SDK Javadocs have all the details of the classes I am referring to below, including AccGroup, AccBuddyList and AccUser, so I will not go into detail explaining what they stand for. The primarysession object is easily available from any part of your application or plugin, including the event callbacks.

Here is some Java code to add a buddy… the same concept applies in C# or C++ too, but the syntax will differ as will the API usage.

AccBuddyList buddyList = primarysession.getBuddyList();
AccUser user;
AccGroup grp = buddyList.getGroupByName(“Family”);
user = grp.insertBuddy(“nameofbuddy”, 0);

And to remove a buddy…

AccUser buddy;
buddy = grp.getBuddyByName(“nameofbuddy”);
int index = grp.getBuddyPosition(buddy);
grp.removeBuddy(index);

AIM Module Plugin sample code

Here is sample code for an AIM Module Plugin (AMO) that allows you to add menus to the AIM 6.8 client to add some of your own functionality.

There is some documentation on how to develop AIM Module Plugins on the AIM Developer Site. You can also find some samples as a starting point there. There is also a useful set of posts in Gus’s blog on the topic.

The sample I want to cover in this post is available here.

This sample demonstrates how use the Open AIM SDK to retrieve the primary user’s buddy list and the users primary identity. This Module Plugin adds two menu items, one of them to the Actions menu which can be used to demonstrate the displaying of the BL, and the other on the right mouse click context menu when you select a buddy, so that you can do something custom with that selected buddy in your plugin.

Here is how you get the list of buddies you can multiple select in the AIM 6.8 buddy list…

var jsSelectedBuddies = window.external.client.selectedBuddies.toArray();

Here is how you send IMs programatically to all your selected buddies…

function sendIm(names)
{
  var s = client.primarySession;
  var im= s.createIm(‘yt?’, ‘text/plain’);
  for(var i=0; i   {
    var ims= s.createImSession(names[i]);
    ims.sendIm(im);
   }
}

Here is how you add menu items to the client. In the plugin.xml, the following adds 2 menu items, the first one to the Actions button drop down menu, and the second to the RMC menu on the selected buddy. There is a detailed description of the API and the flag values here.

<commands>
  </command id=”1″ text=”[AIMcc Sample] Show Buddy List” flags=”2″>
  </command id=”2″ text=”[AIMcc Sample] Send ‘yt?’” flags=”4″>
</commands>

Here is how you respond to menu items in the client…

function onCommandExec(cmd, names)
{
  if (cmd == 1)
   // act on the Actions menu item
  else if (cmd == 2)
   // act on the RMC menu item
}

Real-Time IM

Last year, we developed a feature in the AIM 6.8 client to make AIM more accessible to the deaf community in collaboration to Gallaudet’s Technology Access Program (TAP), more details are found here. The usage of this feature is documented here. This was a way for people to combine the familiarity of messaging on a TTY with the AIM service.

There has been some recent interest in how to make Open AIM clients implement the Real-Time IM feature that is deployed in the AIM 6.8 client. The basic idea is the you establish a direct connection to your buddy and you can both see what the other is typing as they are entering or backspacing or erasing text. For obvious reasons, this feature can be turned on and off and needs permission from your buddy to establish.

We just released a new Open AIM tech note on how to implement Real-Time IM here.

Android AIM Application… Hello IM!

A very cool AIM client for the Android phone developed by Multiple Facets has been released, there is information available on the client here. I found the AIM client remarkably easy to use and very intuitive within the framework of Android to do all the IM functionality that I am used to performing. The design is simple and the flow of control is smooth, navigating from the IM windows to the buddy list and organizing your sessions.

Without going into too much detail since the client is documented on its site above, here are some of the features…

• Adding multiple Screennames to sign on with and the ability to auto save passwords.
• Change your status to away or invisible.
• Add custom status messages and away messages.
• Add and edit groups and users.
• Allows setting of some preferences like sounds, privacy, notifications, icons etc.
• Keeps a list of recent conversations which you can select and navigate to.
• Shows a counter of the number of IMs received against your buddies name, I like this feature.

Launching IM windows and finding them

Here are some code snippets to do some frequently asked about tasks in the AIM Plugins.

The following command can be used from within your C++ AIM plugin to launch an IM Form and populate it for sending to a buddy…

::ShellExecute(NULL, “open”, “aim:goim?screenname=testsn1&message=Testing opening an IM Form”, NULL, NULL, SW_SHOW);

If you want to find and bring the AIM Buddy list window to the foreground, here is how to do it…

HWND blWindow = FindWindow(NULL, “AIM”);
if (blWindow != NULL)
{
    MessageBox(NULL, “Got AIM BL window”, “test”, MB_OK);
    ::ShowWindow(blWindow, SW_RESTORE);
    MessageBox(NULL, “Now show minimizing it”, “test”, MB_OK);
    ::ShowWindow(blWindow, SW_MINIMIZE);
    MessageBox(NULL, “Now show restoring it”, “test”, MB_OK);
    ::ShowWindow(blWindow, SW_RESTORE);
}

If you want to find an IM window, it is somewhat trickier since the title of the window is not fixed.
To check for an imform window, the following with lowercase and spaces stripped are good matches for the window title…
imwith|imswith|ims|newim|away|talkwith|videowith|pictureswith|chatroom

// OX_FRAME_CLASS is the classname that identifies the AIM windows
blWindow = FindWindow(OX_FRAME_CLASS, NULL);
if (blWindow != NULL)
{
    MessageBox(NULL, “Got an AIM Window”, “foo”, MB_OK);
    ::ShowWindow(blWindow, SW_RESTORE);
    char title1[1024];
    while (blWindow != NULL)
    {
    blWindow = GetNextWindow(blWindow, GW_HWNDNEXT);
    GetWindowText(blWindow, title1, 1024);
    // just a hacky example to illustrate one of the matching IM Window title searches
    if (!strnicmp(title1, “im with”, 7))
    ::ShowWindow(blWindow, SW_RESTORE);
    }
}

Retrieving the AIM Buddy List

I have had several users ask me this on the Open AIM Forum and am posting a snippet of working Java code that obtains a list of a user’s buddies after they are signed on. The buddies are organized similar to how they are displayed in the AIM 6.8 client, by groups. I tested this in one of our Java samples called accjsample, which is deployed with the Open AIM SDK. Once you have a AccSession object, you should be able to do the following…

AccBuddyList bl = primarysession.getBuddyList();
int ct = bl.getGroupCount();
log(“group count : “+ ct);
for (int i = 0; i < ct; i++)
{
    AccGroup group = bl.getGroupByIndex(i);
    log("group name: "+ group.getName());
    int ct1 = group.getBuddyCount();
    for (int j = 0; j < ct1; j++)
    {
        AccUser buddy = group.getBuddyByIndex(j);
        log(" Buddy name: "+ buddy.getName());
    }
}

The CoreWitness Plugin

This is one useful diagnostic plugin authored by Gus Verdun that I cannot say enough good things about. It has been covered in Gus and Greg’s blogs and I am reiterating it here, since it is an invaluable tool for all AIM Plugin and AIM Custom client developers. It shows all events sent by the Open AIM API and a lot more, you refer to the link above for details. You can run this plugin with accbuddy or any custom client as well as the AIM 6.8 client.

You can download it here.

Android and Open AIM

I got an Android development phone a few weeks ago and have been experimenting with it. You can order them here. It is a SIM-unlocked and hardware-unlocked device. Debugging on this phone is remarkably easy, just plug the phone into your serial port and the Android Eclipse plugin will detect and use the device instead of the Android emulator. There is a reasonably good introduction and tutorial to developing for the Android. There are several Android forums out there and also one on Google groups, all of which are useful sources of information.

You can use the Android Developer Guide and Web AIM API in order to develop Open AIM applications for this device.

A sample custom session AIM Module Plugin (AMO)

An AIM Module Plugin (AMO)  is specifically designed to take advantage of the new capabilities of AIM 6.8 clients and above, and will only work within those clients. With a Module Plugin you can enhance the AIM Client by changing UI elements by adding features such as a stock ticker or information from your favorite social networking site. Check out our FAQ for more information. We also have several samples available on our Dev Site at Open AIM Samples and on the AIM Gallery. The AIM Architect, Gus has a good introduction and pointers on his blog here.

An Open AIM Custom Session is covered in detail here, I would recommend referring to it before reading further.  The sample I am covering here is about creating a Message mode Custom Session which supports two participants, and allows messages to be sent peer-to-peer to a buddy.

{myGUID} is to be replaced with a valid UUID that is shared by both the sender and recipient and asserted as a capability on both ends for identification purposes.

When you load your AMO, do the following on the sending and receiving ends…

// assert custom capability, this capability is a UUID
window.external.client.primarySession.addCapabilities(“{39BB91C6-5134-4662-AFB3-188D42FD95AC}”);

You can add an HTML button or a menu to trigger starting the Custom session…

// create the custom session
customSession = window.external.client.primarySession.createCustomSession(“{myGUID}”);
customSession.mode = 2; //1 is stream 2 is message
customSession.invite(buddy, “Hello, join me in this session”);

On the recipient side… define the following callback which is invoked when the custom session is created.

function OnSecondarySessionStateChange(session, secondarySession, state, hr)
{
    // need to make sure that the secondary session is a
    // custom session and that the custom session is ours
    // 6 = AccSecondarySessionServiceId_Custom
    if (secondarySession.serviceId == 6)
    {
        // check the UUID
        if (secondarySession.uuid == “{myGUID}”)
        {
        // 50 = AccSecondarySessionState_ReceivedProposal
            if (secondarySession.state == 50)
            {
            secondarySession.accept();
            customSession = secondarySession;
        }

Then on the sending side once the secondary session is online….

function OnSecondarySessionStateChange(session, secondarySession, state, hr)
{
// 500 = AccSecondarySessionState_Online
    if (secondarySession.state == 500)
    {
        // make the content plain text for now
        var im = window.external.client.primarySession.createIm(“Testing sending a message”, “text/plain”);
        // send the data to the buddy
        customSession.sendData(“”, 0, im);
    }
}

Then define 2 more events…

// event to confirm the custom send worked
function OnCustomSendResult(session, customSession, receiver, im, result)
{
    // check the result for failure
}

// event for receiving a custom session message
function OnCustomDataReceived(session, customSession, sender, data)
{
// check the data comes from a session that we know about
    if (customSession.uuid == “{myGUID}”)
    {
    var content = data.getConvertedText(“text/plain”);
    // do something with the content here, just displaying it for now.
        statMessage.innerText = “Received custom data = ” + content;
    }
}

Hello AIM Blog!

Welcome to my blog. I have been wanting to launch a blog to address frequently asked questions from Open AIM users and issues I run into while developing custom clients or plugins.