ADVANCED macromedia COLDFUSION MX 7 Application Development [Electronic resources] نسخه متنی

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.

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.