Using the GatewayHelper object

The CFML GetGatewayHelper function returns a GatewayHelper object with several methods that manage your gateway and buddy list. The GatewayHelper methods let you do the following:

Get and set gateway configuration information and get gateway statistics.
Get and set the gateway online status.
Manage the gateway's buddy list
Manage permissions for others to get information about the gateway status.

The following sections briefly describe the class methods. For detailed information about each method, see "IM Gateway GatewayHelper class methods" in the CFML Reference.

Gateway configuration information and statistics methods

The following table describes the methods that you can use to get and set configuration information and get gateway statistics:

Method	Description
`getName`	Returns the gateway's user name.
`getNickName`	Returns the gateway's display name (nickname).
`getProtocolName`	Returns the name of the instant messaging protocol (JABBER for XMPP, or SAMETIME).
`numberOfMessagesReceived`	Returns the number of messages received by the gateway since it was started.
`numberOfMessagesSent`	Returns the number of messages sent by the gateway since it was started.
`setNickName`	Sets the gateway's display name (nickname).

Gateway online status methods

The following table describes the methods that you can use to get and set the gateway's online availability status (presence information):

Method	Description
`getCustomAwayMessage`	Returns the gateway's custom away message if it has been set by the `setStatus` method.
`getStatusAsString`	Returns the online status of the gateway.
`getStatusTimeStamp`	Returns the date/time that the gateway changed its online status.
`isOnline`	Returns True if the gateway is connected to the IM server; otherwise, returns false.
`setStatus`	Changes the gateway's online status; for example, to away or idle.

Gateway buddy management methods

The following table describes the methods that you can use to manage the gateway's buddy list:

Method	Description
`addBuddy`	Adds a buddy to the gateway's buddy list and tells the IM server to send the gateway messages with the buddy's online state.
`getBuddyInfo`	Gets information about the specified user from the buddy list, deny list, and permit list.
`getBuddyList`	Returns the gateway's buddy list.
`removeBuddy`	Removes the specified user name from the gateway's buddy list and tells the IM server to stop sending the gateway messages with the user's online state.

Gateway permission management methods

The IM gateways can manage the information that other users can get about the gateway's online status.

Note: XMPP permission management is included in the XMPP 1.0 specification, but several XMPP servers that were available at the time of the ColdFusion release do not support permission management.

The following table describes the gateway permission management methods:

Method	Description
`addDeny`	Tells the IM server to add the specified user to the gateway's deny list. If the `permitMode` is DENY_SOME, these users cannot receive messages on the gateway's state.
`addPermit`	Tells the IM server to add the specified user to the server's permit list. If the `permitMode` is PERMIT_SOME, these users receive messages on the gateway's state.
`getDenyList`	Returns the list of users that the server has been told not to send state information to.
`getPermitList`	Returns the list of users that the server has been told to send state information to.
`getPermitMode`	Gets the gateway's permit mode from the IM server. The permit mode determines whether all users can get the gateway's online state information, or whether the server uses a permit list or a deny list to control which users get state information.
`removeDeny`	Removes the user from the gateway's deny list.
`removePermit`	Removes the user from the gateway's permit list.
`setPermitMode`	Sets the gateway's permit mode on the IM server.

GatewayHelper example

This example lets you use the XMPP or SameTime GatewayHelper class to get and set status and other information, including managing buddy lists and view permissions lists.

<cfapplication name="gateway_tool" sessionmanagement="yes">

<!--- Set the gateway buddy name to default values.--->
<cfparam name="session.gwid" default="XMPP Buddy Manager">
<cfparam name="session.buddyid" default="hlichtin2@mousemail">

<!--- Reset gateway and buddy ID if form was submitted. --->
<cfif isdefined("form.submitbuddy")>
    <cfset session.buddyid=form.buddyid>
    <cfset session.gwid=form.gwid>
</cfif>

<!--- Display the current gateway and buddy ID. --->
<h3>Using the GatewayHelper</h3>
<!--- Form to display and reset gateway and Buddy ID. --->
<cfform action="#cgi.script_name#" method="post" name="changeIDs">
    Current buddy ID: <cfinput type="text" name="buddyid" value="#session.buddyid#"><br>
    Current gateway ID: <cfinput type="text" name="gwid" value="#session.gwid#"><br>
    <cfinput name="submitbuddy" value="Change gateway/buddy" type="submit">
</cfform>

<!--- When a buddy is set, display the links and forms to get and set
        information etc. Where form input is required, the form uses a GET method
        so all selections are represented by a url.cmd variable. --->
    
<cfoutput>
<h3>Select one of the following to get or set.</h3>
<ul>
    <li><a href="#cgi.script_name#?cmd=buddyinfo">buddyinfo</a>
    <li>LIST: <a href="#cgi.script_name#?cmd=buddylist">buddylist</a> | 
        <a href="#cgi.script_name#?cmd=permitlist">permitlist</a> | 
        <a href="#cgi.script_name#?cmd=denylist">denylist</a>
    <li>ADD: <a href="#cgi.script_name#?cmd=addbuddy">addbuddy</a> | 
        <a href="#cgi.script_name#?cmd=addpermit">addpermit</a> | 
        <a href="#cgi.script_name#?cmd=adddeny">adddeny</a>
    <li>REMOVE: <a href="#cgi.script_name#?cmd=removebuddy">removebuddy</a> | 
        <a href="#cgi.script_name#?cmd=removepermit">removepermit</a> | 
            <a href="#cgi.script_name#?cmd=removedeny">removedeny</a>
    <!--- NOTE: This list does not include OFFLINE because the gateway resets itself to online. --->
    <li>setStatus (XMPP): 
        <cfloop list="ONLINE,AWAY,DND,NA,FREE_TO_CHAT" index="e">
            <a href="#cgi.script_name#?cmd=setstatus&status=#e#">#e#</a> | 
        </cfloop>
    <li>setStatus (Sametime): 
        <cfloop list="ONLINE,AWAY,DND,IDLE" index="e">
            <a href="#cgi.script_name#?cmd=setstatus&status=#e#">#e#</a> | 
        </cfloop>
    <li>
        <form action="#cgi.script_name#" method="get">
            setStatus with CustomAwayMessage: 
            <input type="hidden" name="cmd" value="setstatus2">
            <select name="status">
                <cfloop list="ONLINE,OFFLINE,AWAY,DND,IDLE,INVISIBLE,NA,OCCUPIED,FREE_TO_CHAT,ONPHONE,ATLUNCH,BUSY,NOT_AT_HOME,NOT_AT_DESK,NOT_IN_OFFICE,ON_VACATION,STEPPED_OUT,CUSTOM_AWAY" index="e">
                    <option value="#e#">#e#</option>
                </cfloop>
            </select>
            <input type="text" name="custommsg" value="(custom away massage)" size="30"/>
            <input type="submit"/>
        </form>
    <li>
        <form action="#cgi.script_name#" method="get">
            setNickName: 
            <input type="hidden" name="cmd" value="setnickname">
            <input type="text" name="nickname" value="(enter nickname)">
            <input type="submit">
        </form>
--->
    <li>INFO: <a href="#cgi.script_name#?cmd=getname">getname</a> | 
        <a href="#cgi.script_name#?cmd=getnickname">getnickname</a> | 
        <a href="#cgi.script_name#?cmd=getcustomawaymessage">getcustomawaymessage</a> | 
        <a href="#cgi.script_name#?cmd=getprotocolname">getprotocolname</a> | 
        <a href="#cgi.script_name#?cmd=getstatusasstring">getstatusasstring</a> | 
        <a href="#cgi.script_name#?cmd=isonline">isonline</a>
    <li>MESSAGE COUNT: 
        <a href="#cgi.script_name#?cmd=numberofmessagesreceived">numberofmessagesreceived</a> | 
        <a href="#cgi.script_name#?cmd=numberofmessagessent">numberofmessagessent</a>
    <li>RUNNING TIME: <a href="#cgi.script_name#?cmd=getsignontimestamp">getsignontimestamp</a> | 
        <a href="#cgi.script_name#?cmd=getstatustimestamp">getstatustimestamp</a>
    <li>setPermitMode: 
        <cfloop list="PERMIT_ALL,DENY_ALL,PERMIT_SOME,DENY_SOME,IGNORE_IN_LIST,IGNORE_NOT_IN_LIST"
                index="e"><a href="#cgi.script_name#?cmd=setpermitmode&mode=#e#">#e#</a> | 
        </cfloop> <span class="note">doesn't work for XMPP</span>
    <li><a href="#cgi.script_name#?cmd=getpermitmode">getpermitmode</a>
    <li>setPlainTextMode: 
        <cfloop list="PLAIN_TEXT,RICH_TEXT" index="e">
            <a href="#cgi.script_name#?cmd=setplaintextmode&mode=#e#">#e#</a> | 
        </cfloop>
    <li><a href="#cgi.script_name#?cmd=getplaintextmode">getplaintextmode</a>
</ul>
</cfoutput>

<!--- The url.cmd value exists if one of the previous links or forms has been submitted, and identifies the type of request. --->
<cfoutput>
<cfif isdefined("url.cmd")>
    <!--- Get the GatewayHelper for the gateway. --->
    <cfset helper = getGatewayHelper(session.gwid)>
    <!--- Need to get the buddy list if requested the list or full buddy information. --->
    <cfswitch expression="#LCase(url.cmd)#">
        <cfcase value="buddylist,buddyinfo">
            <cfset ret=helper.getBuddyList()>
        </cfcase>
        <cfcase value="denylist">
            <cfset ret=helper.getDenyList()>
        </cfcase>
        <cfcase value="permitlist">
            <cfset ret=helper.getPermitList()>
        </cfcase>
        <cfcase value="addbuddy">
            <cfset ret=helper.addBuddy("#session.buddyid#", 
                "#session.buddyid#", "")>
        </cfcase>
        <cfcase value="addpermit">
            <cfset ret=helper.addPermit("#session.buddyid#", 
                "#session.buddyid#", "")>
        </cfcase>
        <cfcase value="adddeny">
            <cfset ret=helper.addDeny("#session.buddyid#", 
                "#session.buddyid#", "")>
        </cfcase>
        <cfcase value="removebuddy">
            <cfset ret=helper.removeBuddy("#session.buddyid#", "")>
        </cfcase>
        <cfcase value="removepermit">
            <cfset ret=helper.removePermit("#session.buddyid#", "")>
        </cfcase>
        <cfcase value="removedeny">
            <cfset ret=helper.removeDeny("#session.buddyid#", "")>
        </cfcase>
        <cfcase value="setstatus">
            <cfset ret=helper.setStatus(url.status, "")>
        </cfcase>
        <cfcase value="setstatus2">
            <cfset ret=helper.setStatus(url.status, url.custommsg)>
        </cfcase>
        <cfcase value="getcustomawaymessage">
            <cfset ret=helper.getCustomAwayMessage()>
        </cfcase>
        <cfcase value="getname">
            <cfset ret=helper.getName()>
        </cfcase>
        <cfcase value="getnickname">
            <cfset ret=helper.getNickname()>
        </cfcase>
        <cfcase value="getprotocolname">
            <cfset ret=helper.getProtocolName()>
        </cfcase>
        <cfcase value="getsignontimestamp">
            <cfset ret=helper.getSignOnTimeStamp()>
        </cfcase>
        <cfcase value="getstatusasstring">
            <cfset ret=helper.getStatusAsString()>
        </cfcase>
        <cfcase value="getstatustimestamp">
            <cfset ret=helper.getStatusTimeStamp()>
        </cfcase>
        <cfcase value="isonline">
            <cfset ret=helper.isOnline()>
        </cfcase>
        <cfcase value="numberofmessagesreceived">
            <cfset ret=helper.numberOfMessagesReceived()>
        </cfcase>
        <cfcase value="numberofmessagessent">
            <cfset ret=helper.numberOfMessagesSent()>
        </cfcase>
        <cfcase value="setnickname">
            <cfset ret=helper.setNickName(url.nickname)>
        </cfcase>
        <cfcase value="setpermitmode">
            <cfset ret=helper.setPermitMode(url.mode)>
        </cfcase>
        <cfcase value="getpermitmode">
            <cfset ret=helper.getPermitMode()>
        </cfcase>
        <cfcase value="setplaintextmode">
            <cfset ret=helper.setPlainTextMode(url.mode)>
        </cfcase>
        <cfcase value="getplaintextmode">
            <cfset ret=helper.getPlainTextMode()>
        </cfcase>
        <cfdefaultcase>
            <cfset ret[1]="Error; Invalid command. You shouldn't get this.">
        </cfdefaultcase>
    </cfswitch>
    <br>
    <!--- Display the results returned by the called GatewayHelper method. --->
    <strong>#url.cmd#</strong><br>
    <cfdump var="#ret#">
    <br>
    <!--- If buddy information was requested, loop through buddy list to get 
        information for each buddy and display it. --->
    <cfif comparenocase(url.cmd, "buddyinfo") is 0 and arraylen(ret) gt 0>
    <b>Buddy info for all buddies</b><br>
        <cfloop index="i" from="1" to="#arraylen(ret)#">
            <cfdump var="#helper.getBuddyInfo(ret[i])#" label="#ret[i]#"></cfloop>
    </cfif>
</cfif>
</cfoutput>

Adobe ColdFusion 8