File: xmpp4r.rb

# xmpp4r.rb

Path: | lib/xmpp4r.rb
Last Update: | Tue Aug 10 17:57:27 -0600 2010

# 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:

- `<message/>` stanzas are cast to Jabber::Message class
- `<presence/>` stanzas are cast to Jabber::Presence class
- `<iq/>` stanzas are cast to Jabber::Iq class

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::ErrorResponse
- `<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.

- Jabber::IqQuery elements are converted to Jabber::Roster::IqQueryRoster if their namespace is ‘jabber:iq:roster‘
- Jabber::IqQuery elements are converted to Jabber::Version::IqQueryVersion if their namespace is ‘jabber:iq:version‘
- Jabber::IqQuery elements are converted to Jabber::Discovery::IqQueryDiscoInfo if their namespace is ‘jabber.org/protocol/disco#info‘
- Jabber::IqQuery elements are converted to Jabber::Discovery::IqQueryDiscoItems if their namespace is ‘jabber.org/protocol/disco#items‘
- `<item/>` children elements of Jabber::Roster::IqQueryRoster are converted to Jabber::Roster::RosterItem
- `<identity/>` children elements of Jabber::IqQueryDiscoInfo are converted to Jabber::Discovery::DiscoIdentity
- `<feature/>` children elements of Jabber::IqQueryDiscoInfo are converted to Jabber::Discovery::DiscoFeature
- `<item/>` children elements of Jabber::IqQueryDiscoItems are converted to Jabber::Discovery::DiscoItem

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)`

## 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.

- Jabber::Bytestreams, Jabber::FileTransfer: `require ‘xmpp4r/bytestreams‘`
- Jabber::Dataforms: `require ‘xmpp4r/dataforms‘`
- Jabber::Delay: `require ‘xmpp4r/delay‘`
- Jabber::Discovery: `require ‘xmpp4r/discovery‘`
- Jabber::FeatureNegotiation: `require ‘xmpp4r/feature_negotiation‘`
- Jabber::MUC: `require ‘xmpp4r/muc‘`
- Jabber::Roster: `require ‘xmpp4r/roster‘`
- Jabber::Vcard: `require ‘xmpp4r/vcard‘`
- Jabber::Version: `require ‘xmpp4r/version‘`

### 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.

- Jabber::Roster::Helper: `require ‘xmpp4r/roster‘`
- Jabber::MUC::MUCBrowser, Jabber::MUC::MUCClient, Jabber::MUC::SimpleMUCClient: `require ‘xmpp4r/muc‘`
- Jabber::Version::SimpleResponder, Jabber::Version::Responder: `require ‘xmpp4r/version‘`
- Jabber::Vcard::Helper: `require ‘xmpp4r/vcard‘`
- Jabber::FileTransfer::Helper, Jabber::Bytestreams::SOCKS5BytestreamsServer: `require ‘xmpp4r/bytestreams‘`

## Debugging

Dumping your Jabber stream can be enabled this way:

      Jabber::debug = true

### Required files

xmpp4r/xmpp4r

[Validate]