xmpp4r.rb

Path: lib/xmpp4r.rb
Last Update: Tue Oct 04 07:44:20 UTC 2005

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:

  • <x/> children elements of <message/> and <presence/> are converted to Jabber::X
  • <error/> children elements of all three stanzas are converted to Jabber::Error
  • <query/> children elements of <iq/> are converted to Jabber::IqQuery
  • <vCard/> children elements of <iq/> are converted to Jabber::IqVcard

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 == ‘jabber.org/protocol/disco#info

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

Threaded and non-threaded modes

From the user point of view, the library can be used either in threaded mode, or in non-threaded mode, using a call to Jabber::Stream#process to receive pending messages.

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 heritates from Connection, which itself heritates 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’ does only include basic functionality as 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 are 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 order of flexibility for the most things.

Required files

xmpp4r/xmpp4r  

[Validate]