onBuddyStatus

Description

Handles incoming messages indicating online status (presence) changes of users on the gateway’s buddy list.

Syntax

onBuddyStatus(CFEvent)

See also

onIncomingMessage, onAddBuddyRequest, onAddBuddyResponse, onIMServerMessage

Parameters

The method must take one parameter, a CFEvent structure with the following fields:

Field

Description

gatewayType

Gateway type, either XMPP or SAMETIME.

gatewayID

The ID of the Gateway instance, as configured in ColdFusion Administrator.

originatorID

The IM ID (buddy name) of the message originator.

cfcMethod

This CFC method; by default, onIMServerMessage.

data.BUDDYNAME

The sender’s buddy name, or ID; identical to the originatorID.

data.BUDDYNICKNAME

The buddy’s display name or nickname.

data.BUDDYSTATUS

The buddy’s status; one of the following:

  • ONLINE

  • OFFLINE

  • AWAY

  • DO NOT DISTURB

  • NOT AVAILABLE

  • FREE TO CHAT

  • IDLE

XMPP only

  • NOT AVAILABLE

  • FREE TO CHAT

  • IDLE

Sametime only

  • IDLE

Use the IMGatewayHelpergetCustomAwayMessage method to get any custom message that the buddy sent when changing status.

data.BUDDYGROUP

The group that the buddy belongs to.

data.RECIPIENT

The recipient’s ID, as specified in the gateway’s configuration file.

data.TIMESTAMP

The date and time when the message was sent.
Note: You configure the buddy’s nickname and group when you use the gatewayHelper object addBuddy method to add a buddy.

Returns

The function does not return a value.

Example

The following example keeps an Application scope structure up-to-date with a buddy’s status. It also uses the gatewayhelper object getBuddyStatus method to get the buddy’s custom away message, if any.

<cffunction name="onBuddyStatus"> 
    <cfargument name="CFEvent" type="struct" required="YES"> 
    <!--- Get the gatewayhelper object and to get the info for this buddy. ---> 
    <!--- This is used to get the buddy's custom away message. ---> 
    <cfset helper = getGatewayHelper("MYIM")> 
    <cfset mybuddyinfo=helper.getBuddyInfo(CFEvent.Data.BUDDYNAME)> 
 
    <cflog file="#CFEvent.GatewayID#Status" type="Information"  
        text="in OnbuddyStatus, sender is #CFEvent.OriginatorID#"> 
    <cflock scope="APPLICATION" timeout="10" type="EXCLUSIVE"> 
        <cfscript> 
        // Create the status structures if they don't exist. 
            if (NOT StructKeyExists(Application, "buddyStatus")) { 
                Application.buddyStatus=StructNew(); 
            } 
            if (NOT StructKeyExists(Application.buddyStatus, 
                    CFEvent.Data.BUDDYNAME)) { 
                Application.buddyStatus[#CFEvent.Data.BUDDYNAME#]=StructNew(); 
            } 
            // Save the buddy status, timestamp, and custom away message 
            Application.buddyStatus[#CFEvent.Data.BUDDYNAME#].status= 
                CFEvent.Data.BUDDYSTATUS; 
            Application.buddyStatus[#CFEvent.Data.BUDDYNAME#].timeStamp= 
                CFEvent.Data.TIMESTAMP; 
            // The following assumes that the buddy is in only one group. 
            Application.buddyStatus[#CFEvent.Data.BUDDYNAME#].customAway= 
                mybuddyinfo[1].BUDDYCUSTOMAWAYMESSAGE; 
        </cfscript> 
    </cflock> 
    <!--- log the info, for debugging purposes only ---> 
    <cfset temp=Application.buddyStatus[#CFEvent.Data.BUDDYNAME#].status> 
    <cflog file="#CFEvent.GatewayID#Status" type="Information" text= 
        "Application.buddyStatus[#CFEvent.Data.BUDDYNAME#].status is #temp#"> 
    <cfset temp=Application.buddyStatus[#CFEvent.Data.BUDDYNAME#].timeStamp> 
        <cflog file="#CFEvent.GatewayID#Status" type="Information" text= 
            "Application.buddyStatus[#CFEvent.Data.BUDDYNAME#].timestamp is #temp#"> 
        <cflog file="#CFEvent.GatewayID#Status" type="Information" text= 
            "Buddy Custom Away Message is mybuddyinfo[1].BUDDYCUSTOMAWAYMESSAGE#"> 
</cffunchtion>