Ruby's license (see the LICENSE file) or GNU GPL, at your option.
Website::http://home.gna.org/xmpp4r/
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.
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.
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 ==
'http://jabber.org/protocol/disco#info'
But instead check for the query's class:
iq.query.kind_of?(Jabber::IqQueryDiscoInfo)
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.
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.
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 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'
Dumping your Jabber stream can be enabled this way:
Jabber::debug = true