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

DESCRIPTION

  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.

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");

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>

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.