Each gateway type passes different members in the data member. It is necessary to comb the product documentation to determine which elements will be populated by the gateway type.

The Calling Logic
While the DirectoryWatcher gateway and other gateways like it are useful for extending ColdFusion's integration with various services and OS-level functions, their general lack of ability to interact with an application in a more imperative way is limiting. Fortunately, this is not the only means of using gateways. CFML has a couple of new functions for passing data back and forth between templates and components; the most direct way is through the sendGatewayMessage function.

sendGatewayMessage
The sendGatewayMessage function (http://livedocs.macromedia.com/coldfusion/7/ htmldocs/00000622.htm#153566) takes two arguments: gatewayID and messageStruct. The gatewayID argument is the name of a configured gateway instance. The messageStruct argument is a structure containing information to be sent to the indicated gateway instance - this structure will become the data structure member of the CFEvent argument to the listener CFC's event handling methods. This function may return a string value - the string returned from the listener CFC's event handling methods. The specific string value that is returned is dependent upon the gateway type of the instance to which the message is sent.

Again, as noted previously, the exact composition of the data structure member, the messageStruct argument of the sendGatewayMessage function, is specific to each gateway. The truly flexible thing about this mechanism is that while certain specific values are necessary, additional values can be passed without adversely affecting the basic functionality.

messageStruct
The structure argument passed to sendGatewayMessage not only contains various bits of data as might be required by the gateway type or that you might choose to pass, but it allows for four optional structure members as well (see Table 3).

We'll use some of these optional members in later examples both in this article and the series.

Putting It All Together
Once again, armed with a basic understanding of how events are handled and how to purposefully invoke them, let's put together a simple example.

One of the more exciting possibilities with event gateways is the ability to perform asynchronous actions, and to launch a subordinate task and not have to wait for it to complete before the parent logic can continue. Contriving a use for this facility for demonstration purposes seldom conveys its real power, but we'll have a go at it.

Popular sites often like to provide a subscription to visitors that offers timely information. Many sites have started to move toward RSS publication and some have started podcasting. But while RSS blurbs have become the condensed news and announcements for the ADD generation and podcasting the archive-able interviews and Internet soundbites, newsletters still remain a rich contextual way of sharing information. Naturally there are no special tricks to sending out newsletters or other mass mailings from ColdFusion. Launching a template that loops through a long list of e-mail addresses pretty much does the trick, though it tends to hang up a browser's output even when using CFFLUSH to provide user feedback, feedback that is seldom of interest to the person who has hit the submit button that initiates the mass mailing process. Wouldn't it be nice if after pressing the button, the administrative user could launch the mailing and then get back to doing other things in the administrative console or Intranet portal?

Enter EmailBlaster.

EmailBlaster
EmailBlaster is nothing more than a gateway instance for the asynchronous CFML gateway type, but it is an excellent example of a user-interactive gateway application. Configuring it is as simple as creating a new CFML instance that points to the EmailBlaster.cfc listener CFC (see Listing 1), the specifics of which can be seen in Figure 2.

The event handler in the listener CFC is a method called onIncomingMessage, which can be seen in Listing 1.

Herein we see the common action of extracting the data structure member from the incoming CFEvent argument. It is at this point that things start to become interesting as a structure member, emailData, is in turn extracted from it. A simple inference can be made about the nature of emailData when looking at the CFMAIL call on line 9; emailData is a query containing at least one column: address. In addition, the CFMAIL start tag shows two other structure members expected in the data structure: sender for the FROM attribute and subject for the mail's SUBJECT attribute.

All of this begs the question - how does a query and some string data get into the listener CFC? It gets passed in the messageStruct argument of a sendGatewayMessage call.

The Calling Logic
The other file in this pair is EmailBlaster.cfm (see Listing 2).

Despite the number of lines, there really isn't much happening in this template. Most of the action is focused upon creating the content that will get passed to the gateway instance, a structure containing a query and two strings. The query is composed of only a single column: address and populated with a single row of data and then added to the structure with the now-familiar name of emailData.

• Figure 1