XMPP4R - XMPP Library for Ruby

License

Ruby's license (see the LICENSE file) or GNU GPL, at your option.

Website::http://home.gna.org/xmpp4r/

Introduction

XMPP4R is a XMPP/Jabber library for Ruby. It can be used to build scripts using Jabber, full-featured Jabber clients, and components. It is written with extensibility in mind.

XML management

All the XML parsing is REXML's, and XML stanzas like <message/> (class Jabber::Message) or <iq/> (class Jabber::Iq) are indirect derivatives from REXML's Element class. This provide a maximum flexibity: the user can access attributes and childs using either the XMPP4R's helpers or directly using REXML's methods.

Automatic element casting

Because there are special classes derived from REXML::Element to ease development on the protocol level, Elements must be cast to them. This is done via REXML::Element#import. This method is also used in import class methods of some Element classes.

The first occurance of this feature is in Jabber::Stream::receive:

This is not only useful for stanzas but all other XML processing, too:

The following conversion facilities are only executed if the respective library parts are loaded. See below for more details on Non-basic features.

To use this, don't check for: iq.queryns == 'http://jabber.org/protocol/disco#info'

But instead check for the query's class: iq.query.kind_of?(Jabber::IqQueryDiscoInfo)

Where to begin?

Because it is built in an extensible way, it might be hard for newcomers to understand where to look at documentation for a specific method. For example, Client inherits from Connection, which itself inherits from Stream.

A newcomer should have a look at the Jabber::Client and Jabber::Component classes, and their parent classes Jabber::Connection and Jabber::Stream. The best way to understand how to use them is probably to look at the examples in the examples/ dir.

Non-basic features

require 'xmpp4r' only includes basic functionality for Connections, Authentication, Stream processing, Callbacks, Stanza handling and Debugging to keep the library's footprint small.

There is code for features that aren't required by a basic client. These must be additionally included to use them.

Protocol-level features

You're highly advised to read the according RFCs and JEPs if you intend to use them. The benefit will be that you'll understand the protocols and be going to be more efficient when programming with them.

Helpers

Helpers are intended to give more simplistic interfaces to various tasks of Jabber clients at the cost of flexibility. But you won't need that level of flexibility in most cases.

Debugging

Dumping your Jabber stream can be enabled this way:

Jabber::debug = true