NAME

       Net::XMPP - XMPP Perl Library

SYNOPSIS

       Net::XMPP provides a Perl user with access to the Extensible Messaging and Presence
       Protocol (XMPP).

       For more information about XMPP visit:

       <http://www.xmpp.org>

DESCRIPTION

       Net::XMPP is a convenient tool to use for any perl script that would like to utilize the
       XMPP 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::XMPP is a wrapper around the rest of the official Net::XMPP::xxxxxx
       packages.

       There is are example scripts in the example directory that provide you with examples of
       very simple XMPP 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 of this writing threading in
       Perl is not quite up to par yet.  This issue will be revisted in the future.

EXAMPLES

         use Net::XMPP;
         my $client = Net::XMPP::Client->new();

METHODS

       The Net::XMPP 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 equivalent 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();

       GetChild
           Returns an array of Net::XMPP::Stanza objects that represent all of the stanzas in the
           object that are namespaced.  If you specify a namespace then only stanza objects with
           that XMLNS are returned.

             @xObj = $obj->GetChild();
             @xObj = $obj->GetChild("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
       NewChild
             NewChild(namespace)
             NewChild(namespace,tag)

           Creates a new Net::XMPP::Stanza object with the specified namespace and root tag of
           whatever the namespace says its root tag should be.  Optionally you may specify
           another root tag if the default is not desired, or the namespace requres you to set
           one.

             $xObj = $obj->NewChild("my:namespace");
             $xObj = $obj->NewChild("my:namespace","foo");

           ie. <foo xmlns='my:namespace'...></foo>

       InsertRawXML
             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->NewChild(..);
             $x->InsertRawXML("test");

             $query = $iq->GetChild(..);
             $query->InsertRawXML("test");

       ClearRawXML
             ClearRawXML()

           Removes the raw XML from the packet.

   Removal functions
       RemoveChild
             RemoveChild()
             RemoveChild(namespace)

           Removes all of the namespaces child elements from the object.  If a namespace is
           provided, then only the children with that namespace are removed.

   Test functions
       DefinedChild
             DefinedChild()
             DefinedChild(namespace)

           Returns 1 if there are any known namespaced stanzas in the packet, 0 otherwise.
           Optionally you can specify a namespace and determine if there are any stanzas with
           that namespace.

             $test = $obj->DefinedChild();
             $test = $obj->DefinedChild("my:namespace");

PACKAGES

       For more information on each of these packages, please see the man page for each one.

   Net::XMPP::Client
       This package contains the code needed to communicate with an XMPP 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::XMPP::Protocol
       A collection of high-level functions that Client uses to make their lives easier.  These
       methods are inherited by the Client.

   Net::XMPP::JID
       The XMPP 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::XMPP::Message
       Everything needed to create and read a <message/> received from the server.

   Net::XMPP::Presence
       Everything needed to create and read a <presence/> received from the server.

   Net::XMPP::IQ
       IQ is a wrapper around a number of modules that provide support for the various Info/Query
       namespaces that XMPP recognizes.

   Net::XMPP::Stanza
       This module represents a namespaced stanza that is used to extend a <message/>,
       <presence/>, and <iq/>.

       The man page for Net::XMPP::Stanza contains a listing of all supported namespaces, and the
       methods that are supported by the objects that represent those namespaces.

   Net::XMPP::Namespaces
       XMPP allows for any stanza to be extended by any bit of XML.  This module contains all of
       the internals for defining the XMPP based extensions defined by the IETF.  The
       documentation for this module explains more about how to add your own custom namespace and
       have it be supported.

AUTHOR

       Originally authored by Ryan Eatmon.

       Previously maintained by Eric Hacker.

       Currently maintained by Darian Anthony Patrick.

BUGS

       See unpatched issues at <https://rt.cpan.org/Dist/Display.html?Queue=Net-XMPP>.

       There is at least one issue with XML::Stream providing different node structures depending
       on how the node is created. Net::XMPP should now be able to handle this, but who knows
       what else lurks.

COPYRIGHT

       This module is free software, you can redistribute it and/or modify it under the LGPL 2.1.