Event selection API

(Comments about this page to bard?)

The following only applies to extensions and client applications, not to hybrid web/IM applications.

  1. Introduction
  2. Event types
    1. Event: transport
    2. Event: stream
    3. Event: message, iq, presence

Introduction

When a message comes in, when a contact changes presence, when the result of authentication arrives, an event is generated.

In order to listen to events, a channel must be created, through which events can surface from the XMPP bus to the application. 

var channel = XMPP.createChannel();

Events are selected using the on() method of the channel. To listen for incoming messages and pass them to a handler function, you would write: 

channel.on({event: 'message', direction: 'in'}, handleIncomingMessage);

To listen for outgoing presences: 

channel.on({event: 'presence', direction: 'out'}, handleOutgoingPresence);

To listen for incoming messages of the "error" type: 

channel.on({
    event: 'message',
    direction: 'in',
    stanza: function(s) {
        return s.@type == 'error';
    }},
    function(message) {
        window.alert('Error message received from ' + message.stanza.@from);
    });

The general form is: 

channel.on(pattern, handler);

When an XMPP event matches the given pattern, it is passed to the handler. (Note that the event does not stop there: other channels can listen for it.)

The general form of the pattern is: 

var pattern = {
    property1: matcher1,
    property2: matcher2,
    // ...
    propertyN: matcherN
};

Matcher can be an immediate value, and it will be checked for equality, as in "direction" below: 

channel.on({event: 'message', direction: 'in'},
           handler);

Matcher can also be a function, in which case it will be receive the event object and, if it returns true, is considered to match, as the function below: 

channel.on({event: 'message', stanza: function(s) {return s.@type == 'error'}},
           handler);

Event types

Five event types can be currently listened for:

  • transport
  • stream
  • message
  • presence
  • iq

Not all properties are available on all events.

Event: transport

Generated when the underlying transport (TCP only currently) connects or disconnects. Properties:

  • event - "transport"
  • state - "start" or "stop"

Event: stream

Generated when incoming or outgoing XML streams are open. Properties:

  • event - "stream"
  • direction - "in" or "out"
  • state - "open" or "close"

Event: message, iq, presence

Generated for incoming or outgoing XMPP stanzas. Properties:

  • event - "message" or "iq" or "presence"
  • direction - "in" or "out"
  • session - XMPP session the stanza belongs to
  • account - XMPP account the stanza belongs to (development branch)
  • stanza - XML (E4X) object containing the XML stanza