Net::XMPP.3pm

Langue: en

Version: 2008-11-06 (ubuntu - 07/07/09)

Section: 3 (Bibliothèques de fonctions)

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 = new Net::XMPP::Client();
 
 

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 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();
 
   GetChild()          - returns an array of Net::XMPP::Stanza objects
   GetChild(namespace)   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(namespace)     - creates a new Net::XMPP::Stanza object with
   NewChild(namespace,tag)   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(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() - removes the raw XML from the packet.
 
 

Removal functions

   RemoveChild()          - removes all of the namespaces child elements
   RemoveChild(namespace)   from the object.  If a namespace is provided,
                            then only the children with that namespace are
                            removed.
 
 

Test functions

   DefinedChild()          - returns 1 if there are any known namespaced
   DefinedChild(namespace)   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

Ryan Eatmon Currently maintained by Eric Hacker.

BUGS

Probably. There is at least one issue with XLM::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. This module is free software, you can redistribute it and/or modify it under the LGPL.