Welcome to Jabber4R
The Jabber Client Library for Ruby

The purpose of this library is to allow Ruby applications to talk to a Jabber instant messenging system.

Jabber is an open-source instant messaging service. An interesting facet of Jabber is its ability to represent multiple resources connecting to a single account at the same time. One could connect to the account account@jabber.org from home and from work and from a PDA all at the same time. Each connection is viewed as a resource. Messages can be sent to an account (and the server will decide which resource gets it based on the resource's priority) or to an account+resource. The fully qualified account and resource name is account@host/resource.

This library was created to allow a Ruby application to connect to (or create a) Jabber account as an additional resource. Although it was not the original intent to serve as the infrastructure of a complete UI-based IM client...it supports everything except the groupchat protocol. It currently supports:


What can you do with this? You could write a ruby application that allows you to query it by IM for status, control, etc. You could use this as a communications channel backbone for a Ruby application, which is what we did with ACME.

Download
Main project page

The library is fully rdoc'ed and rdoc can be used to generate web-browsable documentation.

Examples:


Connecting to an account, sending a message, and disconnecting
require 'jabber4r/jabber4r'
begin
  session = Jabber::Session.bind('account@host/resource', 'password')
  session.new_message('rich_kilmer@jabber.org').set_subject('hello').set_body('This is really cool').send
rescue Exception=>error
  puts error
ensure
  session.release if session
end
Connecting to an account, sending a message, waiting for a reply, and disconnecting
require 'jabber4r/jabber4r'
begin
  session = Jabber::Session.bind('account@host/resource', 'password')
  #NOTE: send the first message and wait for a reply (i.e. send(true) )
  message = session.new_chat_message('rich_kilmer@jabber.org').set_body('hey').send(true)
  #NOTE: reply to the reply with an echo of the message, but don't wait
  message.reply.set_body("You said #{message.body}").send
rescue Exception=>error
  puts error
ensure
  session.release if session
end
 
Connecting to an account, echoing back each received message, and disconnecting when a shutdown message is received
 
require "jabber4r/jabber4r"
begin
  session = Jabber::Session.bind("account@host/resource", "password")
  myThread = Thread.current
  mlid = session.add_message_listener do |message|
    message.reply.set_body("Echo: #{message.body}").send
    myThread.wakeup if message.body=="shutdown"
  end
  Thread.stop
  session.delete_message_listener(mlid)
rescue Exception=>error
  puts error
ensure
  session.release if session
end
Connecting to an account, outputting roster changes, and disconnecting when a shutdown message is received
require "jabber4r/jabber4r"
begin
  session = Jabber::Session.bind("account@host/resource", "password")
  myThread = Thread.current
  #NOTE: Just like before, a "shutdown" message stops the session
  mlid = session.add_message_listener do |message|
    myThread.wakeup if message.body=="shutdown"
  end
  listenerid = session.add_roster_listener do |event, object|
    case event
      when Jabber::Roster::ITEM_ADDED
        puts "Added item: #{object.to_s}"
      when Jabber::Roster::ITEM_DELETED
        puts "Deleted item: #{object.to_s}"
      when Jabber::Roster::RESOURCE_ADDED
        puts "Added resource: #{object.to_s}"
      when Jabber::Roster::RESOURCE_DELETED
        puts "Deleted resource: #{object.to_s}"
      when Jabber::Roster::RESOURCE_UPDATED
        puts "Updated resource: #{object.to_s}"
    end
  end
  Thread.stop
rescue Exception=>error
  puts error
ensure
  session.release if session
end

Credits
Bishop Broderson - reported XML encoding bug