NAME
Net::Jabber - Jabber Perl Library
SYNOPSIS
Net::Jabber provides a Perl user with access to the Jabber
Instant Messaging protocol.
For more information about Jabber visit:
http://www.jabber.orgDESCRIPTION
Net::Jabber is a convenient tool to use for any perl script
that would like to utilize the Jabber Instant Messaging
protocol. While not a client in and of itself, it provides
all of the necessary back-end functions to make a CGI client
or command-line perl client feasible and easy to use.
Net::Jabber is a wrapper around the rest of the official
Net::Jabber::xxxxxx packages.
There is are example scripts in the example directory that
provide you with examples of very simple Jabber programs.
NOTE: The parser that XML::Stream::Parser provides, as are most Perl
parsers, is synchronous. If you are in the middle of parsing a
packet and call a user defined callback, the Parser is blocked until
your callback finishes. This means you cannot be operating on a
packet, send out another packet and wait for a response to that packet.
It will never get to you. Threading might solve this, but as we all
know threading in Perl is not quite up to par yet. This issue will be
revisted in the future.EXAMPLES
In an attempt to cut down on memory usage, not all of the modules
are loaded at compile time. You have to tell the Net::Jabber
module which "set" of modules you want to work with when you
use the module:
use Net::Jabber qw(Client Component Server);
Depending on what you are trying to write, specify one of the
above when you use the module. (You can specify more than one,
but it is unlikely that you will need too.)
For a client:
use Net::Jabber qw(Client);
my $client = new Net::Jabber::Client();
For a component:
use Net::Jabber qw(Component);
my $component = new Net::Jabber::Component();
For a server:
use Net::Jabber qw(Server);
my $server = new Net::Jabber::Server();METHODS
The Net::Jabber module does not define any methods that you will call
directly in your code. Instead you will instantiate objects that
call functions from this module to do work. The three main objects
that you will work with are the Message, Presence, and IQ modules.
Each one corresponds to the Jabber equivilant and allows you get and
set all parts of those packets.
There are a few functions that are the same across all of the objects:Retrieval functions
GetXML() - returns the XML string that represents the data contained
in the object.
$xml = $obj->GetXML();
GetX() - returns an array of Net::Jabber::X objects that
GetX(namespace) represent all of the <x/> style namespaces in the
object. If you specify a namespace then only X
objects with that XMLNS are returned.
@xObj = $obj->GetX();
@xObj = $obj->GetX("my:namespace");
GetTag() - return the root tag name of the packet.
GetTree() - return the XML::Stream::Node object that contains the
data. See XML::Stream::Node for methods you can call
on this object.Creation functions
NewX(namespace) - creates a new Net::Jabber::X object with the
NewX(namespace,tag) specified namespace and root tag of <x/>.
Optionally you may specify another root tag
if <x/> is not desired.
$xObj = $obj->NewX("my:namespace");
$xObj = $obj->NewX("my:namespace","foo");
ie. <foo xmlns='my:namespace'...></foo>
InsertRawXML(string) - puts the specified string raw into the XML
packet that you call this on.
$message->InsertRawXML("<foo></foo>")
<message...>...<foo></foo></message>
$x = $message->NewX(..);
$x->InsertRawXML("test");
$query = $iq->GetQuery(..);
$query->InsertRawXML("test");
ClearRawXML() - removes the raw XML from the packet.Test functions
DefinedX() - returns 1 if there are any <x/> tags in the
DefinedX(namespace) packet, 0 otherwise. Optionally you can
specify a namespace and determine if there
are any <x/> with that namespace.
$test = $obj->DefinedX();
$test = $obj->DefinedX("my:namespace");PACKAGES
For more information on each of these packages, please see
the man page for each one.
Net::Jabber::Client - this package contains the code needed to
communicate with a Jabber server: login, wait for messages,
send messages, and logout. It uses XML::Stream to read the
stream from the server and based on what kind of tag it
encounters it calls a function to handle the tag.
Net::Jabber::Component - this package contains the code needed
to write a server component. A component is a program tha handles
the communication between a jabber server and some outside
program or communications pacakge (IRC, talk, email, etc...)
With this module you can write a full component in just
a few lines of Perl. It uses XML::Stream to communicate with
its host server and based on what kind of tag it encounters it
calls a function to handle the tag.
Net::Jabber::Server - this package contains the code needed
to instantiate a lightweight Jabber server. This module is
still under development, but the goal is to have this be a
fully functioning Jabber server that can interact with a real
server using the server to server protocol, as well as accept
client and component connections. The purpose being that some
programs might be better suited if they ran and did all of the
talking on their own. Also this just seemed like a really cool
thing to try and do.
Net::Jabber::Protocol - a collection of high-level functions
that Client, Component, and Server use to make their lives easier.
These functions are included through AUTOLOAD.
Net::Jabber::JID - the Jabber IDs consist of three parts:
user id, server, and resource. This module gives you access
to those components without having to parse the string
yourself.
Net::Jabber::Message - everything needed to create and read
a <message/> received from the server.
Net::Jabber::Presence - everything needed to create and read
a <presence/> received from the server.
Net::Jabber::IQ - IQ is a wrapper around a number of modules
that provide support for the various Info/Query namespaces that
Jabber recognizes.
Net::Jabber::Query - this module represents anything that can
be called a <query/> for an <iq/>.
Net::Jabber::X - this module represents anything that can
be called an <x/>.ADD CUSTOM MODULES
The way that this module set is coded is a little different than
the typical module. Since XML is a very structured thing, and
Jabber is an XML stream the modules have been coded to reuse
code where ever possible. Generic functions in Jabber.pm provide
access for all of the other modules which drive the functions via
hash structures that define the functions using AUTOLOAD. Confused?
I can understand if you are, I was too while trying to code this.
But after I got the hang of it is really simple to add in a new
Jabber module.
For more information on this topic, please read the man page for
Net::Jabber::Namespaces.AUTHOR
By Ryan Eatmon in May of 2001 for http://jabber.org/
COPYRIGHT
This module is free software, you can redistribute it and/or modify it under the same terms as Perl itself.