Instant Messaging API code snippet

On the post I made yesterday I presented a code snippet for sending an email in your application. Today I am including a code snippet that lets you send and receive messages using an Instant Messaging application.

All this snippet really does is provide a simple and convenient wrapper for the AIM Developer SDK. I have read the license that is included and it seems pretty open and allows for the redistribution of source and binaries.

The wrapper is provided with a single header file and single CPP for implementation as all true snippets should be. However, since it is dependent on the AIM SDK it does require the AIM SDK header files, link libraries, and run-time DLL components (all included in this download).

This download includes a fully built executable console chat-client as well as the source code and project files to build it. Obviously this is a Windows only feature (as was the SendMail submission yesterday).

The wrapper uses a version of the PIMPL pattern that I have become pretty happy with. It exposes just two standard C style methods, one to create an 'InstantMessage' interface and one to release it. The pointer you get back is a pure-virtual interface that only exposes the public methods and nothing more.

When constructing the InstantMessage system you will need to pass a pointer to an 'InstantMessageInterface' so that you can receive incoming messages. You will also need to pump the InstantMessage class to give it a chance to process incoming messages and state change events.

The public interface is completely generic and could, theoretically, be mapped to other instant messaging systems. The main use-case for this implementation is for server status monitoring. I am using it to have live servers fire of chat messages to me based on state changes and other important events.

Here is a link to the the zip file containing the source code, binaries, and everything you need to embed instant messaging capabilities (using AIM) in your application.

Here is the header file for the Instant Messaging wrapper layer
------------------------------------------------

#ifndef INSTANT_MESSAGE_H

#define INSTANT_MESSAGE_H

// This is a wrapper API to handle instant messaging on top of AOL instant messenger or AIM
// Requires the AIM instant message SDK to build.
//
// Please be aware of all of the licensing issues associated with using the AIM SDK
//
// This wrapper was written by John W. Ratcliff. Please send bug-fixes feedback to jratcliff@infiniplex.net

enum InstantMessageState
{
IMS_NONE,
IMS_OFFLINE,
IMS_DISCONNECTED,
IMS_QUERYING_DCS,
IMS_CONNECTING,
IMS_CHALLENGING,
IMS_VALIDATING,
IMS_SECURE_ID,
IMS_SECURET_ID_NEXT_KEY,
IMS_TRANSFERRING,
IMS_NEGOTIATING,
IMS_STARTING,
IMS_ONLINE,
IMS_WILL_SHUTDOWN,
IMS_SHUTDOWN,
IMS_PAUSED,
};


class InstantMessageInterface
{
public:
virtual void notifyInstantMessageState(InstantMessageState state) = 0;
virtual void receiveInstantMessage(const wchar_t *from,const wchar_t *message) = 0;
};

class InstantMessage
{
public:

virtual bool connect(const char *userName,const char *password) = 0; // connect using this user id and password.
virtual bool disconnect(void) = 0; // dissconnected
virtual bool pump(void) = 0; // pump the instant message system on this thread, handles event processing.

virtual const char * getInstantMessageStateStr(InstantMessageState state) = 0; // conver the instant message enum into a string.

virtual bool sendInstantMessage(const wchar_t *userId,const wchar_t *msg) = 0; // send an instant message to a buddy (unicode string)
virtual bool sendInstantMessage(const char *userId,const char *fmt,...) = 0; // send an instant message to a buddy using the printf style syntax

};


InstantMessage * createInstantMessage(InstantMessageInterface *imi);
void releaseInstantMessage(InstantMessage *im);

#endif