Net::Jabber - Jabber Perl Library
Net::Jabber provides a Perl user with access to the Jabber Instant Messaging protocol. For more information about Jabber visit: http://www.jabber.org
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.
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();
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:
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.
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.
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");
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/>.
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.
By Ryan Eatmon in May of 2001 for http://jabber.org/
This module is free software, you can redistribute it and/or modify it under the same terms as Perl itself.