Skip to content
This repository has been archived by the owner on Nov 18, 2021. It is now read-only.

Common tasks

Jump to bottom
bard edited this page Sep 13, 2010 · 1 revision

Making xmpp4moz available to your code

Write the following in your XUL overlay:


<script type="application/x-javascript" src="chrome://xmpp4moz/content/xmpp.js"/>

Sending out XMPP stanzas

To send a message stanza to @contact@server.org@ using the account
@foo@bar.org/SamePlace@:


XMPP.send('foo@bar.org/SamePlace',
          <message to="contact@server.org"><body>hello!</body></message>);

Listening to XMPP events

To listen to XMPP events, you need a channel. You’ll usually
create this in the onload handler of the application or extension, and
release it in the onunload handler:

Example:


var channel;

function init() {
    // initialization...

    channel = XMPP.createChannel();

    // more initialization...
}

function finish() {
    // finalization...

    channel.release();
}

Selecting and reacting to XMPP events

Once you’re listening to XMPP traffic, you’ll want to pick a subset of
it and react on certain patterns.

For example, to display every incoming message with an alert(), you
can register the following listener:


function init() {
    channel = XMPP.createChannel();

    channel.on({
        event     : 'message',
        direction : 'in',
        }, function(message) {
            alert(message.stanza.body);
        });
}

To do something whenever the user sets an “away” status, i.e. a presence packet with this content:


<show>away</show>

You can use something like this:


channel.on({
    event     : 'presence',
    direction : 'out',
    stanza    : function(s) {
        return s.show == 'away';
    }},
    function(presence) {
        onUserAway(presence);
    });
}

The above highlights a very important practice: most of the time, you
don’t want to react on a user interface event (such the user selecting
an “away” option from a menu), but rather on the resulting XMPP event.

The reason is that there could be many ways for the user to trigger an
“away” action in the UI (a menu, a button, a command line), and you
cannot keep track of them all; but they all result in sending out a
presence stanza, so that is what you want to watch out for.

To do something after a session has been brought up, provide a function
as a second parameter to up():


    XMPP.up(account,
            function() {
                alert('connected!');
            });

account can be a string containing the full JID of the configured
account:


    var account = 'foo@bar.org/SamePlace';
    XMPP.up(account);

It can also be an empty object, in which case the user will be
prompted to select an account, and the jid property of the object
will be set to the selected account afterwards:


    var account = {};
    XMPP.up(account,
            function() {
                alert('connected with ' + account.jid + '!');
            });

Synchronizing with existing state

Since XMPP sessions are independent of applications, it may easily
happen that an application is loaded when one or more session are
already connected.

Applications will then have to “peek into the past” if, for example,
they want to display the latest known status of user or contacts.
This is done using the cache.

For example, to retrieve online contacts as soon as your application
is started (note that online contacts are those who sent a
presence stanza with no “type” attribute):


function init() {
    // initialization ...

    var contactPresences = XMPP.cache.fetch({
        event     : 'presence',
        direction : 'in',
        stanza    : function(s) {
            return s.@type == undefined;
        }
    });

    var onlineContacts = '';
    for each(var presence in contactPresences) {
        onlineContacts += presence.stanza.@from + '\n';
    }
    alert('contacts now online:\n' + onlineContacts);
}

Connecting and disconnecting

Connecting the account ‘foo@bar.org/SamePlace’ (assuming it has been configured by the user):


XMPP.up('foo@bar.org/SamePlace');

Connecting an account chosen by the user (a dialog will appear with a list of available accounts):


XMPP.up();

Connecting an account and remembering which one the user has chosen:


var account = {};
XMPP.up(account);

Disconnecting an account:


XMPP.down(account);

Connecting an arbitrary account, bypassing preferences:


XMPP.up({
        jid: 'foo@bar.org/SamePlace', 
        password: 'secret'
    });

If the connection server is different than the part after ‘@’ in the
account, it must be specified (this is the case for GMail):


XMPP.up({
        jid: 'user@gmail.com/SamePlace',
        password: 'secret', 
        connectionHost: 'talk.google.com'
    });

Setting presence

Setting status for account @foo@bar.org/SamePlace@:


XMPP.send('foo@bar.org/SamePlace',
          <presence>
          <show>dnd</show>
          <status>coding...</status>
          </presence>);
Clone this wiki locally