API: Channel

channel.on()

    listener = myChannel.on(pattern, handler);

Adds an observer which will trigger the handler according to a specific event pattern (once a connection is established, as via XMPP.up()), using an event object as the argument to the handler (see API: Event).

All event objects will have an account property with the user’s JID (and the deprecated session property with name property also set to the JID). They will all also have an event property that will vary depending on the nature of the event (see below).

The pattern object is defined with the same properties as on the event object, but set to the values for which one wishes to have the handler triggered (or, in the case of the stanza property, to a function which is passed the stanza and returns only those stanzas which desired). If the pattern object is an empty object, all events will be reported. A connector pattern might be:

    {event:'connector', state:'stream-open'}

while a stanza pattern might be:

    {event:'message', 
     direction:'in', 
     stanza: function (stanza) { 
          return stanza.subject.length() > 0; // Only return messages with a subject
      }
    }

Connector events

‘connector’ events, triggered at various stages of connecting to the server, will contain an event property which simply indicates ‘connector’. These events are less likely to need handlers defined but are nevertheless available.

They will also contain a state property which indicates the stage of connection:

• States which trigger internal events as well as channel observers: ‘active’ (XMPP.up() handler is invoked), ‘accept-stanza’ (triggers stanza-in event handlers and sends any reply handler for a XMPP.send() action), ‘error’ (closes the session and takes reports any authentication errors or bad security certificates), ‘disconnected’ (re-notifies observers for on any previously cached incoming presence stanzas, treating them now as though they had reported unavailable presence while the cache of formerly outgoing presence stanzas has their types changed into ‘unavailable’ type; the session is then closed)
• States which only trigger channel observers: ‘connecting’, ‘wait-stream’, ‘requesting-session’, ‘idle’, ‘requested-tls’, ‘auth-waiting-result’, ‘binding-resource’, ‘negotiating-tls’, and ‘stream-open’
• the source code also refers to ‘auth-waiting-challenge’, ‘authenticating’, and ‘connected’, but these are not part of any notifications

The order of observable events might follow such as the following:

connecting : wait-stream : stream-open : auth-waiting-result : wait-stream : stream-open : binding-resource : requesting-session : active : idle : (and then ‘accept-stanza’ alternating with ‘idle’ for any stanzas sent)

Stanza events

‘stanza’ events, on the other hand, are much more common, and indicate that a stanza (such as message, presence, or iq) has been received or sent. Their event property is not set to ‘stanza’, but rather to the specific kind of stanza being sent or received (e.g., ‘message’, ‘presence’, or ‘iq’).

Stanza events also possess a direction property which is set to ‘in’ or ‘out’ to indicate whether it is a stanza being received or sent, respectively. And stanza events contain a stanza property which is the stanza being received or sent.

Events are discussed further under API: Event.

channel.forget()

    myChannel.forget(listener);

Removes a particular channel listener.

channel.release()

    myChannel.release();

Removes service observers and caching of service discovery features (including channel observers or service discovery features added by createChannel()).

Changelog:

2006.09.08: version 3: bard: removed utilities since they’re not public