API: Event

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

These event types can be currently listened for:

• connector
• message
• presence
• iq

Not all properties are available on all events.

Event: connector

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

• event – “connector”
• direction – “in” or “out”
• state -

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

THE FOLLOWING SHOULD BE MERGED WITH THAT ABOVE, MAKING ANY NECESSARY CORRECTIONS

Events

Functions such as XMPP.send() and channel.on() invoke handlers
upon events. These handlers are in turn passed objects that describe
the event. Event objects have different properties depending on the
event they describe.

In general, all event objects have an account string property which
tells what on what session the event happened. It’s the JID
(@user@server/Resource@) of the account the session is asseciated
with.

If the event object represents an XMPP packet, it also has a
direction property, with a value of either "in" or "out".

If the event object represents an XMPP packet, it also has a stanza
property carrying the XML stanza, as an E4X object. It can be a
message,
presence or
iq (info/query)
stanza.

Examples

Event for a message packet:

• message.account: account on which message was received (or sent), as “username@servername.xxx/resource”
• message.stanza: XML stanza
• message.stanza.@type: message type: chat, error, groupchat, headline, normal
• message.stanza.body: message body
• message.stanza.body.@xml:lang: Language code of message body
• message.stanza.subject: message subject
• message.stanza.subject.@xml:lang: Language code of message subject
• message.stanza.thread: message thread

Event for a presence packet:

• presence.account: account on which presence notification was received (or sent), as “username@servername.xxx/resource”
• presence.stanza: XML stanza
• presence.stanza.@type: presence type – if present, could be: ‘unavailable’, ‘subscribe’, ‘subscribed’, ‘unsubscribe’, ‘unsubscribed’, ‘probe’, ‘error’)
• presence.stanza.show: presence show – if present, could be: ‘away’, ‘chat’, ‘dnd’ (Do Not Disturb), ‘xa’ (eXtended Away)
• presence.stanza.status: presence status – if present, human-readable status message
• presence.stanza.status: presence status.@xml:lang – if present, represents the language code for the status message
• presence.stanza.priority: presence priority – if present, an integer between -128 and +127

Event for an iq packet:

• iq.account: account on which Info/Query was received (or sent), as “username@servername.xxx/resource”
• iq.stanza: XML stanza
• iq.stanza.@type: iq type (get, set, result, or error)

Event for error packet:

(To be completed.)

Event for a transport connection:

(To be completed.)

See also API: Channel under channel.on()…