Jabber4R is copyrighted free software by Rich Kilmer <[email protected]> Please see LICENSE.txt for licensing information. Version: 0.8.0 Date: August 15, 2005

Overview

The purpose of this library is to allow Ruby applications to talk to a Jabber IM system. Jabber is an open-source instant messaging service, which can be learned about here.

http://www.jabber.org

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 [email protected] 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:

@host/resource

This library was created to allow a Ruby application to connect to an existing Jabber account as an additional resource. This is not meant to be a library to create a complete Ruby-based Jabber IM client. It currently does not support creation of accounts and managing presence subscriptions (do that with one of the other 30 Jabber clients out there). It was written for ease of use, not completeness. It does support:

  • Account registration

  • Connection to an account (digest/plain text)

  • Access to Roster (buddy list)

  • Tracking of presence of resources in the Roster (including local account resources)

  • Sending and receiving messages

  • Requesting VCards

  • Managing subscriptions

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 my intent).

Release Notes

  • Now have rake-based building and install.

Usage

require 'jabber4r/jabber4r' session = Jabber::Session.bind_digest("[email protected]", "secret") session.new_message("[email protected]").set_body("ruby speak!").send session.release

You can send and receive messages. I make use of chaining on messages so you can do this

session.add_message_listener do |message|
  message.reply.set_body(?Echo: #{message.body}?).send
end

If you want to send and wait for a reply message do:

answer=session.new_chat_message("[email protected]").set_body("Hello there").send(true)

Then execute:

puts answer.body
answer.reply.set_body("Thanks for the reply").send

The examples below demonstrate many features.

Please look at the doc directory (RDoc format) for detailed info on Jabber4R. The Jabber::Session class is kind of the main thing to focus on.

I have a test directory with a single unit test file (for testing the JID class).

I will work on many more. There is also a fun echo.rb file there that you can run to echo and messages back to the sender...and when they send 'shutdown' the session releases.

ruby echo.rb <jabberid> <password>

You can observe roster changes, but cannot manage subscriptions (the framework is there to do this, but it needs some work). You also cannot add an account (you must already have one). That's in the works as well.

Have fun!

Installation

To install, execute the following command:

> gem install jabber4r

That's it!

Examples

NOTE: Remember to change your account@host/resource and password to YOURs.

Connecting to an account, sending a message, and disconnecting:

require 'jabber4r/jabber4r' begin

session = Jabber::Session.bind('account@host/resource', 'password')
session.new_message('[email protected]').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('[email protected]').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