Defining IM Gateways

Defining your IM gateway is fairly straightforward, You will need your CFC and a gateway configuration file which will tell the gateway how to connect to the IM server itself. Just to get things started, start by creating a stub CFC that will contain all of our methods. When compared to other gateways, the IM gateway has quite a few default methods.

• onIncomingMessage. This is your normal gateway method. It catches every incoming IM message and allows you to process it and respond to it. You might want to make sure that you always respond in some way to an incoming message otherwise your virtual IM user will appear to be ignoring your users.

• onAddBuddyRequest. This method is called when another user attempts to add your virtual IM user to their buddy list. Once they have added you to their list they can then see the presence state of your application. This can be very powerful especially in our helpdesk scenario as this could say if the helpdesk is manned and if it is busy or not at one glance to a buddy list.

• onAddBuddyResponse. When your gateway adds other users to its own buddy list, the responses to these requests will be handled here. Also if a user asks to be removed from your buddy list, you will need to handle it here as well.

• onBuddyStatus. Once you have other IM Users on your list, their status will be relayed to you every time it changes and captured in this method. You will need to capture and store this status information if you wish to use it in your application.

Listing 32.1 is an example of what your IM Gateway CFC should look like.

Listing 32.1. xmpp_stub.cfcEmpty XMPP Gateway CFC

 <cfcomponent>    <cffunction name="onIncomingMessage" hint="Standard message from IM users">       <cfargument name="CFEvent" type="struct" required="YES">    </cffunction>      <cffunction name="onAddBuddyRequest" hint="Requests from others to add the                 gateway ID to their buddy list.">       <cfargument name="CFEvent" type="struct" required="YES">    </cffunction>        <cffunction name="onAddBuddyResponse" hint="Responses from others to requests                from your gateway to add them to your buddy lists. Also used by                buddies to ask to be removed from your list.">       <cfargument name="CFEvent" type="struct" required="YES">    </cffunction>        <cffunction name="onBuddyStatus" hint="Presence status messages from other                users.">       <cfargument name="CFEvent" type="struct" required="YES">    </cffunction>        <cffunction name="onIMServerMessage" hint="Error and status messages from the                IM server.">       <cfargument name="CFEvent" type="struct" required="YES">    </cffunction> </cfcomponent> 

Even though our application may not use all of these events, it is good practice to code them all so that it is very clear to other users what is going on and what is not. You do not have to use the default names for any of these methods; you can replace them with your own names. This is done in the individual gateway configuration files.

To build our application, we will need to create our own gateway CFC. Take a copy of this file from the CD and call it im.cfc.

The Gateway Configuration File

One very simple thing that you will need to get prepared before you begin creating your gateway instance is the configuration file for your IM client

There are two example configuration files in your ColdFusion installation: one for XMPP and one for Lotus Sametime. They are found in the cf_root\WEB-INF\cfusion\gateway\config directory on J2EE configurations, and cf_root\gateway\config directory on standard server configurations.

To make life easier, here is the default setting that you will need for a standard XMPP connection. If you used different settings when you created your ColdFusion user, here is where you tell ColdFusion your settings. You will need to save this as helpdesk.cfg as we will need it when we create our gateway instance:

 userid=coldfusionserver@yourJiveServerNamw password=CFMX7 resourceName=ColdFusion serverip=yourJiveServerName serverport=5222 

TIP

Before you go to much further, make sure that you can log in as this user using a normal IM clientIt one of the most annoying things to get everything written only to find that your user does not exist. To do this, just add your server's IM account into your IM client as another user, and then you can send messages to yourself.

Figure 32.2. Send a message to yourself with PSI so you know that everything is working.

This file is also used to define optionally configurable items, including security settings and additional events. This can be really handy if you have one CFC controlling both XMPP and SameTime interactions.

Creating the Gateway Instance

Inside the ColdFusion administrator you will need to go to the Event Gateway Instances property page and add a new gateway instance. For this application we called our gateway "Helpdesk", our gateway cfc, "im.cfc", and our configuration file, "helpdesk.cfg", as shown in Figure 32.3.

Figure 32.3. The configuration page for our gateway.

There are two key details in creating your new instance, the first being the CFC that will handle all of your requests and the configuration file itself. Make sure you get these both right and you will be set.

TIP

At this point it would be wise to test your new gateway. Jump into the ColdFusion administrator and make sure that it starts.