Sending outgoing messages

You use the SendGatewayMessage CFML function or the return value of a CFC listener method to send outgoing messages. The ColdFusion IM gateway accepts the following outgoing message commands:

Command

Description

submit

(Default) Sends a normal message to another IM user.

accept

Accepts an add buddy request. Adds the buddy to the list of IDs that get your presence information and sends an acceptance message to the buddy ID.

decline

Declines an add buddy request and sends a rejection message to the buddy ID.

noact

Tells the gateway to take no action. The gateway logs a message that indicates that it took no action, and contains the gateway type, gateway ID, and buddy ID.

The message structure that you return in the gateway listener CFC function or use as the second parameter in the CFML SendGatewayMessage function can have the following fields. The table lists the fields and the commands in which they are used, and describes each field’s use.

Field

Commands

Description

buddyID

All

The destination user ID.

command

All

The command; if omitted, ColdFusion treats the message as a submit command.

message

submit

A text message to send to the destination user.

reason

accept, decline

A text description of the reason for the action or other message to send to the add buddy requestor.

In typical use, a ColdFusion application uses the accept, decline, and noact commands in the return value of the onAddBuddyRequest method, and uses the submit command (or no command, because submit is the default command) in SendGatewayMessage CFML functions and the return value of the onIncomingMessage CFC method.

The SendGatewayMessage CFML function can send any command, and can be used to send an accept or decline message. One possible use is in an application where someone must review all buddy requests before they are added. In this case, the onAddBuddyRequest CFC method could initially send a noact command in its return value, and save the request information in a database. Administrators could use a separate ColdFusion application to review the request information. This application could use the SendGatewayMessage function with an accept or decline command to act on the request and inform the requestor.

The following example onIncomingMessage method of a listener CFC echoes incoming IM messages to the message originator:

<cffunction name="onIncomingMessage" output="no"> 
    <cfargument name="CFEvent" type="struct" required="yes"> 
    <cfset retValue.MESSAGE = "echoing: " & CFEvent.DATA.message> 
    <cfset retValue.BuddyID = arguments.CFEVENT.DATA.SENDER> 
    <cfreturn retValue> 
</cffunction>