# Net::XMPP - phpMan

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