All incoming event messages must be handled by one or more listener CFCs. You specify the listener CFCs when you configure an event gateway in the ColdFusion Administrator. Specify at least one CFC in the administrator. Some gateway types can use more than one CFC. By default, the ColdFusion event gateway service delivers events by calling the onIncomingMessage method of the CFC.

The event gateway developer must inform the event gateway application developer of methods that the listener CFC must implement (could be only the onIncomingMessage method) and of the structure and contents of the event message data, contained in the CFEvent instance, that the listener CFC must handle. Outgoing messages have the same event message data structure as incoming messages.

Many gateways let the listener CFCs send a response by calling the cfreturn function, but ColdFusion does not require a return value. Listener CFCs can also use the SendGatewayMessage function, which provides more flexibility than the cfreturn tag.

ColdFusion CFM pages cannot receive event messages. However, they can send messages using an event gateway. Therefore, an event gateway application that initiates outgoing messages could use one or more SendGatewayMessage functions to send the messages. An application that sends an SMS message to notify users when a package ships, for example, could use the SendGatewayMessage function to send the notification.

The Gateway Instances page in the ColdFusion Administrator associates a specific event gateway instance with one or more listener CFCs that processes messages from the event gateway. It tells the ColdFusion event gateway service to send messages received by the event gateway to the listener CFC. It also lets you specify a configuration file for the event gateway instance and whether to start the event gateway instance (and therefore any responder application) when ColdFusion starts. For more information on using the Administrator, see the ColdFusion Administrator online Help.

A ColdFusion event gateway provides an information conduit: at its most basic, it receives and dispatches event messages. In some cases, however, an event gateway must provide additional functionality. An instant messaging event gateway, for example, must provide such services as managing buddies and providing status information. To support such use, an event gateway can enable access to a GatewayHelper object. The event gateway developer writes a Java class that provides the necessary utility routines as Java methods, and ColdFusion application developers can get an instance of the class by calling the CFML GetGatewayHelper method. The application calls the GatewayHelper object methods using normal ColdFusion object access techniques. The ColdFusion instant messaging event gateways and the example socket event gateway provide GatewayHelper objects.