.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::XMPP 3pm"
.TH Net::XMPP 3pm 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Net::XMPP \- XMPP Perl Library
.SH SYNOPSIS
.IX Header "SYNOPSIS"
Net::XMPP provides a Perl user with access to the Extensible
Messaging and Presence Protocol (XMPP).
.PP
For more information about XMPP visit:
.PP
<http://www.xmpp.org>
.SH DESCRIPTION
.IX Header "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.
.PP
There is are example scripts in the example directory that provide you
with examples of very simple XMPP programs.
.PP
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.
.SH EXAMPLES
.IX Header "EXAMPLES"
.Vb 2
\&  use Net::XMPP;
\&  my $client = Net::XMPP::Client\->new();
.Ve
.SH METHODS
.IX Header "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.
.PP
There are a few functions that are the same across all of the objects:
.SS "Retrieval functions"
.IX Subsection "Retrieval functions"
.IP GetXML 4
.IX Item "GetXML"
Returns the XML string that represents the data contained
in the object.
.Sp
.Vb 1
\&  $xml  = $obj\->GetXML();
.Ve
.IP GetChild 4
.IX Item "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.
.Sp
.Vb 2
\&  @xObj = $obj\->GetChild();
\&  @xObj = $obj\->GetChild("my:namespace");
.Ve
.IP GetTag 4
.IX Item "GetTag"
Return the root tag name of the packet.
.IP GetTree 4
.IX Item "GetTree"
Return the XML::Stream::Node object that contains the data.
See XML::Stream::Node for methods you can call on this
object.
.SS "Creation functions"
.IX Subsection "Creation functions"
.IP NewChild 4
.IX Item "NewChild"
.Vb 2
\&  NewChild(namespace)
\&  NewChild(namespace,tag)
.Ve
.Sp
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.
.Sp
.Vb 2
\&  $xObj = $obj\->NewChild("my:namespace");
\&  $xObj = $obj\->NewChild("my:namespace","foo");
.Ve
.Sp
ie. <foo xmlns='my:namespace'...></foo>
.IP InsertRawXML 4
.IX Item "InsertRawXML"
.Vb 1
\&  InsertRawXML(string)
.Ve
.Sp
puts the specified string raw into the XML
packet that you call this on.
.Sp
.Vb 2
\&  $message\->InsertRawXML("<foo></foo>")
\&    <message...>...<foo></foo></message>
\&
\&  $x = $message\->NewChild(..);
\&  $x\->InsertRawXML("test");
\&
\&  $query = $iq\->GetChild(..);
\&  $query\->InsertRawXML("test");
.Ve
.IP ClearRawXML 4
.IX Item "ClearRawXML"
.Vb 1
\&  ClearRawXML()
.Ve
.Sp
Removes the raw XML from the packet.
.SS "Removal functions"
.IX Subsection "Removal functions"
.IP RemoveChild 4
.IX Item "RemoveChild"
.Vb 2
\&  RemoveChild()
\&  RemoveChild(namespace)
.Ve
.Sp
Removes all of the namespaces child elements
from the object.  If a namespace is provided,
then only the children with that namespace are
removed.
.SS "Test functions"
.IX Subsection "Test functions"
.IP DefinedChild 4
.IX Item "DefinedChild"
.Vb 2
\&  DefinedChild()
\&  DefinedChild(namespace)
.Ve
.Sp
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.
.Sp
.Vb 2
\&  $test = $obj\->DefinedChild();
\&  $test = $obj\->DefinedChild("my:namespace");
.Ve
.SH PACKAGES
.IX Header "PACKAGES"
For more information on each of these packages, please see the man page
for each one.
.SS Net::XMPP::Client
.IX Subsection "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.
.SS Net::XMPP::Protocol
.IX Subsection "Net::XMPP::Protocol"
A collection of high-level functions that Client uses to make their
lives easier.  These methods are inherited by the Client.
.SS Net::XMPP::JID
.IX Subsection "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.
.SS Net::XMPP::Message
.IX Subsection "Net::XMPP::Message"
Everything needed to create and read a <message/> received from the
server.
.SS Net::XMPP::Presence
.IX Subsection "Net::XMPP::Presence"
Everything needed to create and read a <presence/> received from the
server.
.SS Net::XMPP::IQ
.IX Subsection "Net::XMPP::IQ"
IQ is a wrapper around a number of modules that provide support for
the various Info/Query namespaces that XMPP recognizes.
.SS Net::XMPP::Stanza
.IX Subsection "Net::XMPP::Stanza"
This module represents a namespaced stanza that is used to extend a
<message/>, <presence/>, and <iq/>.
.PP
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.
.SS Net::XMPP::Namespaces
.IX Subsection "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.
.SH AUTHOR
.IX Header "AUTHOR"
Originally authored by Ryan Eatmon.
.PP
Previously maintained by Eric Hacker.
.PP
Currently maintained by Darian Anthony Patrick.
.SH BUGS
.IX Header "BUGS"
See unpatched issues at <https://rt.cpan.org/Dist/Display.html?Queue=Net\-XMPP>.
.PP
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.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
This module is free software, you can redistribute it and/or modify it
under the LGPL 2.1.