IM Integration With XMPP4r : Part 2

In the first part, we talked less about XMPP4r and more about XMPP, this time it will be the other way around.

Now that we know that XMPP messages are XML bits of information exchanged between a client and a server via a TCP connection, we are more able to understand the purpose of XMPP4r.

What is XMPP4r?

Here is the most simple definition I came out with : XMPP4r is a ruby library that acts as a XMPP Client. Understand it that way and you won’t be confuse about what XMPP4r is supposed to do. Like any other jabber client (google talk, pidgin, etc), Xmpp4r sends, receives and manages XML messages called stanzas.

In a sense, XMPP4r is like GoogleTalk without the GUI. (And, of course, XMPP4r is not already implemented… you have to code the behavior of the client yourself). With GoogleTalk, you connect on a Jabber Server by pressing the connect button. With XMPP4r, you connect on a Jabber server that way :

The first line simply creates a new instance of the Client class. This instance represents the user itself. The 2nd line tries to establish a connection between the user and the Jabber server ( The 3rd line tries to authenticate the user using the following mechanisms.

  • Non-SASL digest

Now about the 4th line. Remember when I talked about stanzas in the first part? Well, at the 4th line, we sent our first stanza to our Jabber Server… a presence stanza. We did this because we want our server to know we are there. That way, everyone in our buddy list will know we are online and ready to chat!

Sending messages
So, what now? You are online, fine… but how can you exchange messages with people? That’s pretty simple…

Important note : You have to set the message type to “chat” because some clients will react differently depending of the message type. A Gajim user will hate you if you send him messages with a message type of “normal”, because Gajim popups a new window for every single “normal” messages it receives. On the other hand, it uses the same window for “chat” messages coming from the same user.

Ok so we know how to send a message to someone, but what if that someone is not in our buddy list? Well, simply put, it will not work. XMPP just doesn’t allow this and we all agree that it’s a good thing. Who like to be spammed?

Say we want to add to our buddy list, we do :

Ok so we sent our request… what about the response? Fortunately, the line above won’t wait for a result. As you can imagine, it could get pretty long… we don’t control the answer of the person at the other end after all. This leads me to talk to you about a key feature of xmpp4r : callbacks.

Registering Callbacks

Let’s get back to our subscription request we sent to John earlier. Since we said that our line of code would NOT wait for a response, we need some other way to get that response when it will come. (that’s pretty much what callbacks are for, right?)

Because we sent a subscription request, the callback “add_update_callback” will be called as soon as the user at the other end will reply. If you want to be notified when this happens, you have to register to this callback :

Xmpp4r provides callbacks for a lot of purposes. Now if I want to be notified of the messages sent to us by others, what do I have to use? The answer is add_message_callback!

There is also a very useful callback that lets you know when the availability of someone in your buddy list change.

Note that the various callbacks in xmpp4r run within their own thread.

Well, this is the end of the 2nd part. Next part should be about the Roster helper and I also want to criticize Xmpp4r about his stability (lack of) and somewhat incomplete documentation.

Woooh! Silly me… here is an important update

Don Park and Nilu had problems with this tutorial… and it’s probably because I forgot to talk about an essential part : The subscription. To receive messages from others, you have to accept their subscription requests first! Here is how

  1. require ‘xmpp4r/roster’ (a roster is an object representing your buddy list)
  2. roster =
  3. Implement the add_subscription_request_callback that way (if you want to accept everyone) :

You should be fine now.. sorry about that

UPDATE October 21st 2008
Some interesting remarks in the comments deserved a proper update :


I’m sure you have your answer already, but let me explain the “running in their own thread” thing :

The callbacks are invoked in the context of the “parser thread” which is the one doing the actual “listening” of the the XML stream. When something happens in the parser thread (e.g. message stanza received), callbacks are invoked from there. So the code you have in your various callbacks are effectively executed in the parser thread context.

Like Leonardo wrote, you have to write Thread.stop in your main thread when you have set all your callbacks and other initialization stuff.

It might sound confusing, but you have to write Thread.stop to keep the current thread alive. Thread.stop will simply put the current thread into sleep mode and leave all the scheduling time to the other threads (the parser thread in our case). If you don’t write Thread.stop, everything ends when the main thread has nothing left to do.