.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::XMPP::Protocol 3pm"
.TH Net::XMPP::Protocol 3pm "2017-01-22" "perl v5.24.1" "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::Protocol \- XMPP Protocol Module
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Net::XMPP::Protocol is a module that provides a developer easy
access to the \s-1XMPP\s0 Instant Messaging protocol.  It provides high
level functions to the Net::XMPP Client object.  These functions are
inherited by that modules.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Protocol.pm seeks to provide enough high level APIs and automation of
the low level APIs that writing a \s-1XMPP\s0 Client in Perl is trivial.  For
those that wish to work with the low level you can do that too, but
those functions are covered in the documentation for each module.
.PP
Net::XMPP::Protocol provides functions to login, send and receive
messages, set personal information, create a new user account, manage
the roster, and disconnect.  You can use all or none of the functions,
there is no requirement.
.PP
For more information on how the details for how Net::XMPP is written
please see the help for Net::XMPP itself.
.PP
For more information on writing a Client see Net::XMPP::Client.
.SS "Modes"
.IX Subsection "Modes"
Several of the functions take a mode argument that let you specify how
the function should behave:
.IP "block" 4
.IX Item "block"
send the packet with an \s-1ID,\s0 and then block until an answer
comes back.  You can optionally specify a timeout so that
you do not block forever.
.IP "nonblock" 4
.IX Item "nonblock"
send the packet with an \s-1ID,\s0 but then return that id and
control to the master program.  Net::XMPP is still
tracking this packet, so you must use the CheckID function
to tell when it comes in.  (This might not be very
useful...)
.IP "passthru" 4
.IX Item "passthru"
send the packet with an \s-1ID,\s0 but do \s-1NOT\s0 register it with
Net::XMPP, then return the \s-1ID. \s0 This is useful when
combined with the XPath function because you can register
a one shot function tied to the id you get back.
.SS "Basic Functions"
.IX Subsection "Basic Functions"
.Vb 3
\&    use Net::XMPP qw( Client );
\&    $Con = Net::XMPP::Client\->new();                  # From
\&    $status = $Con\->Connect(hostname=>"jabber.org"); # Net::XMPP::Client
\&
\&    $Con\->SetCallBacks(send=>\e&sendCallBack,
\&                       receive=>\e&receiveCallBack,
\&                       message=>\e&messageCallBack,
\&                       iq=>\e&handleTheIQTag);
\&
\&    $Con\->SetMessageCallBacks(normal=>\e&messageNormalCB,
\&                              chat=>\e&messageChatCB);
\&
\&    $Con\->SetPresenceCallBacks(available=>\e&presenceAvailableCB,
\&                               unavailable=>\e&presenceUnavailableCB);
\&
\&    $Con\->SetIQCallBacks("custom\-namespace"=>
\&                                             {
\&                                                 get=>\e&iqCustomGetCB,
\&                                                 set=>\e&iqCustomSetCB,
\&                                                 result=>\e&iqCustomResultCB,
\&                                             },
\&                                             etc...
\&                                            );
\&
\&    $Con\->SetXPathCallBacks("/message[@type=\*(Aqchat\*(Aq]"=>&messageChatCB,
\&                            "/message[@type=\*(Aqchat\*(Aq]"=>&otherMessageChatCB,
\&                            ...
\&                           );
\&
\&    $Con\->RemoveXPathCallBacks("/message[@type=\*(Aqchat\*(Aq]"=>&otherMessageChatCB);
\&
\&    $Con\->SetDirectXPathCallBacks("/anything"=>&anythingCB,
\&                                  "/anotherthing[@foo=\*(Aqbar\*(Aq]"=>&anotherthingFooBarCB,
\&                                  ...
\&                                 );
\&
\&    $Con\->RemoveDirectXPathCallBacks("/message[@type=\*(Aqchat\*(Aq]"=>&otherMessageChatCB);
\&
\&    $error = $Con\->GetErrorCode();
\&    $Con\->SetErrorCode("Timeout limit reached");
\&
\&    $status = $Con\->Process();
\&    $status = $Con\->Process(5);
\&
\&    $Con\->Send($object);
\&    $Con\->Send("<tag>XML</tag>");
\&
\&    $Con\->Send($object,1);
\&    $Con\->Send("<tag>XML</tag>",1);
\&
\&    $Con\->Disconnect();
.Ve
.SS "\s-1ID\s0 Functions"
.IX Subsection "ID Functions"
.Vb 10
\&    $id         = $Con\->SendWithID($sendObj);
\&    $id         = $Con\->SendWithID("<tag>XML</tag>");
\&    $receiveObj = $Con\->SendAndReceiveWithID($sendObj);
\&    $receiveObj = $Con\->SendAndReceiveWithID($sendObj,
\&                                             10);
\&    $receiveObj = $Con\->SendAndReceiveWithID("<tag>XML</tag>");
\&    $receiveObj = $Con\->SendAndReceiveWithID("<tag>XML</tag>",
\&                                             5);
\&    $yesno      = $Con\->ReceivedID($id);
\&    $receiveObj = $Con\->GetID($id);
\&    $receiveObj = $Con\->WaitForID($id);
\&    $receiveObj = $Con\->WaitForID($id,
\&                                  20);
.Ve
.SS "Namespace Functions"
.IX Subsection "Namespace Functions"
.Vb 7
\&    $Con\->AddNamespace(ns=>"foo:bar",
\&                       tag=>"myfoo",
\&                       xpath=>{Foo=>{ path=> "foo/text()" },
\&                               Bar=>{ path=> "bar/text()" },
\&                               FooBar=>{ type=> "master" },
\&                              }
\&                      );
.Ve
.SS "Message Functions"
.IX Subsection "Message Functions"
.Vb 5
\&    $Con\->MessageSend(to=>"bob@jabber.org",
\&                      subject=>"Lunch",
\&                      body=>"Let\*(Aqs go grab some...\en",
\&                      thread=>"ABC123",
\&                      priority=>10);
.Ve
.SS "Presence Functions"
.IX Subsection "Presence Functions"
.Vb 4
\&    $Con\->PresenceSend();
\&    $Con\->PresenceSend(type=>"unavailable");
\&    $Con\->PresenceSend(show=>"away");
\&    $Con\->PresenceSend(signature=>...signature...);
.Ve
.SS "Subscription Functions"
.IX Subsection "Subscription Functions"
.Vb 2
\&    $Con\->Subscription(type=>"subscribe",
\&                       to=>"bob@jabber.org");
\&
\&    $Con\->Subscription(type=>"unsubscribe",
\&                       to=>"bob@jabber.org");
\&
\&    $Con\->Subscription(type=>"subscribed",
\&                       to=>"bob@jabber.org");
\&
\&    $Con\->Subscription(type=>"unsubscribed",
\&                       to=>"bob@jabber.org");
.Ve
.SS "Presence \s-1DB\s0 Functions"
.IX Subsection "Presence DB Functions"
.Vb 1
\&    $Con\->PresenceDB();
\&
\&    $Con\->PresenceDBParse(Net::XMPP::Presence);
\&
\&    $Con\->PresenceDBDelete("bob\e@jabber.org");
\&    $Con\->PresenceDBDelete(Net::XMPP::JID);
\&
\&    $Con\->PresenceDBClear();
\&
\&    $presence  = $Con\->PresenceDBQuery("bob\e@jabber.org");
\&    $presence  = $Con\->PresenceDBQuery(Net::XMPP::JID);
\&
\&    @resources = $Con\->PresenceDBResources("bob\e@jabber.org");
\&    @resources = $Con\->PresenceDBResources(Net::XMPP::JID);
.Ve
.SS "\s-1IQ \s0 Functions"
.IX Subsection "IQ Functions"
.SS "Auth Functions"
.IX Subsection "Auth Functions"
.Vb 4
\&    @result = $Con\->AuthSend();
\&    @result = $Con\->AuthSend(username=>"bob",
\&                             password=>"bobrulez",
\&                             resource=>"Bob");
.Ve
.SS "Register Functions"
.IX Subsection "Register Functions"
.Vb 4
\&    %hash   = $Con\->RegisterRequest();
\&    %hash   = $Con\->RegisterRequest(to=>"transport.jabber.org");
\&    %hash   = $Con\->RegisterRequest(to=>"transport.jabber.org",
\&                                    timeout=>10);
\&
\&    @result = $Con\->RegisterSend(to=>"somewhere",
\&                                 username=>"newuser",
\&                                 resource=>"New User",
\&                                 password=>"imanewbie",
\&                                 email=>"newguy@new.com",
\&                                 key=>"some key");
.Ve
.SS "Roster Functions"
.IX Subsection "Roster Functions"
.Vb 1
\&    $Roster = $Con\->Roster();
\&
\&    %roster = $Con\->RosterParse($iq);
\&    %roster = $Con\->RosterGet();
\&    $Con\->RosterRequest();
\&    $Con\->RosterAdd(jid=>"bob\e@jabber.org",
\&                    name=>"Bob");
\&    $Con\->RosterRemove(jid=>"bob@jabber.org");
.Ve
.SS "Roster \s-1DB\s0 Functions"
.IX Subsection "Roster DB Functions"
.Vb 1
\&    $Con\->RosterDB();
\&
\&    $Con\->RosterDBParse(Net::XMPP::IQ);
\&
\&    $Con\->RosterDBAdd("bob\e@jabber.org",
\&                      name=>"Bob",
\&                      groups=>["foo"]
\&                     );
\&
\&    $Con\->RosterDBRemove("bob\e@jabber.org");
\&    $Con\->RosterDBRemove(Net::XMPP::JID);
\&
\&    $Con\->RosterDBClear();
\&
\&    if ($Con\->RosterDBExists("bob\e@jabber.org")) { ...
\&    if ($Con\->RosterDBExists(Net::XMPP::JID)) { ...
\&
\&    @jids = $Con\->RosterDBJIDs();
\&
\&    if ($Con\->RosterDBGroupExists("foo")) { ...
\&
\&    @groups = $Con\->RosterDBGroups();
\&
\&    @jids = $Con\->RosterDBGroupJIDs("foo");
\&
\&    @jids = $Con\->RosterDBNonGroupJIDs();
\&
\&    %hash = $Con\->RosterDBQuery("bob\e@jabber.org");
\&    %hash = $Con\->RosterDBQuery(Net::XMPP::JID);
\&
\&    $value = $Con\->RosterDBQuery("bob\e@jabber.org","name");
\&    $value = $Con\->RosterDBQuery(Net::XMPP::JID,"groups");
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "Basic Functions"
.IX Subsection "Basic Functions"
.IP "\fIGetErrorCode()\fR" 4
.IX Item "GetErrorCode()"
returns a string that will hopefully contain some
useful information about why a function returned
an undef to you.
.IP "SetErrorCode" 4
.IX Item "SetErrorCode"
.Vb 1
\&  SetErrorCode(string)
.Ve
.Sp
set a useful error message before you return
an undef to the caller.
.IP "SetCallBacks" 4
.IX Item "SetCallBacks"
.Vb 6
\&  SetCallBacks(message=>function, 
\&                 presence=>function,
\&                 iq=>function,      
\&                 send=>function,    
\&                 receive=>function, 
\&                 update=>function)
.Ve
.Sp
sets the callback functions for
the top level tags listed.  The
available tags to look for are
<message/>, <presence/>, and
<iq/>.  If a packet is received
with an \s-1ID\s0 which is found in the
registered \s-1ID\s0 list (see RegisterID
below) then it is not sent to
these functions, instead it
is inserted into a \s-1LIST\s0 and can
be retrieved by some functions
we will mention later.
.Sp
send and receive are used to
log what \s-1XML\s0 is sent and received.
update is used as way to update
your program while waiting for
a packet with an \s-1ID\s0 to be
returned (useful for \s-1GUI\s0 apps).
.Sp
A major change that came with
the last release is that the
session id is passed to the
callback as the first argument.
This was done to facilitate
the Server module.
.Sp
The next argument depends on
which callback you are talking
about.  message, presence, and iq
all get passed in Net::XMPP
objects that match those types.
send and receive get passed in
strings.  update gets passed
nothing, not even the session id.
.Sp
If you set the function to undef,
then the callback is removed from
the list.
.IP "SetPresenceCallBacks" 4
.IX Item "SetPresenceCallBacks"
.Vb 1
\&  SetPresenceCallBacks(type=>function etc...)
.Ve
.Sp
sets the callback functions for
the specified presence type.
The function takes types as the
main key, and lets you specify
a function for each type of
packet you can get.
.Sp
.Vb 8
\&  "available"
\&  "unavailable"
\&  "subscribe"
\&  "unsubscribe"
\&  "subscribed"
\&  "unsubscribed"
\&  "probe"
\&  "error"
.Ve
.Sp
When it gets a <presence/>
packet it checks the type=''
for a defined callback.  If
there is one then it calls the
function with two arguments:
.Sp
.Vb 2
\&  the session ID, and the
\&  Net::XMPP::Presence object.
.Ve
.Sp
If you set the function to
undef, then the callback is
removed from the list.
.Sp
\&\s-1NOTE:\s0 If you use this, which is a cleaner method,
then you must *NOT* specify a callback for
presence in the SetCallBacks function.
.Sp
.Vb 2
\& Net::XMPP defines a few default
\& callbacks for various types:
\&
\& "subscribe" \-
\&   replies with subscribed
\&
\& "unsubscribe" \-
\&   replies with unsubscribed
\&
\& "subscribed" \-
\&   replies with subscribed
\&
\& "unsubscribed" \-
\&   replies with unsubscribed
.Ve
.IP "SetMessageCallBacks" 4
.IX Item "SetMessageCallBacks"
.Vb 1
\&    SetMessageCallBacks(type=>function, etc...)
.Ve
.Sp
sets the callback functions for
the specified message type. The
function takes types as the
main key, and lets you specify
a function for each type of
packet you can get.
.Sp
.Vb 5
\& "normal"
\& "chat"
\& "groupchat"
\& "headline"
\& "error"
.Ve
.Sp
When it gets a <message/> packet
it checks the type='' for a
defined callback. If there is
one then it calls the function
with two arguments:
.Sp
.Vb 2
\&  the session ID, and the
\&  Net::XMPP::Message object.
.Ve
.Sp
If you set the function to
undef, then the callback is
removed from the list.
.Sp
\&\s-1NOTE:\s0 If you use this, which is a cleaner method,
then you must *NOT* specify a callback for
message in the SetCallBacks function.
.IP "SetIQCallBacks" 4
.IX Item "SetIQCallBacks"
.Vb 6
\&  SetIQCallBacks(namespace=>{      
\&                     get=>function,  
\&                     set=>function,  
\&                     result=>function
\&                   },                
\&                   etc...)
.Ve
.Sp
sets the callback functions for
the specified namespace. The
function takes namespaces as the
main key, and lets you specify a
function for each type of packet
you can get.
.Sp
.Vb 3
\&  "get"
\&  "set"
\&  "result"
.Ve
.Sp
When it gets an <iq/> packet it
checks the type='' and the
xmlns='' for a defined callback.
If there is one then it calls
the function with two arguments:
the session \s-1ID,\s0 and the
Net::XMPP::xxxx object.
.Sp
If you set the function to undef,
then the callback is removed from
the list.
.Sp
\&\s-1NOTE:\s0 If you use this, which is a cleaner method,
then you must *NOT* specify a callback for
iq in the SetCallBacks function.
.IP "SetXPathCallBacks" 4
.IX Item "SetXPathCallBacks"
.Vb 1
\&  SetXPathCallBacks(xpath=>function, etc...)
.Ve
.Sp
registers a callback function
for each xpath specified.  If
Net::XMPP matches the xpath,
then it calls the function with
two arguments:
.Sp
.Vb 2
\&  the session ID, and the
\&  Net::XMPP::Message object.
.Ve
.Sp
Xpaths are rooted at each
packet:
.Sp
.Vb 3
\&  /message[@type="chat"]
\&  /iq/*[xmlns="jabber:iq:roster"][1]
\&  ...
.Ve
.IP "RemoveXPathCallBacks" 4
.IX Item "RemoveXPathCallBacks"
.Vb 1
\& RemoveXPathCallBacks(xpath=>function, etc...)
.Ve
.Sp
unregisters a callback
function for each xpath
specified.
.IP "SetDirectXPathCallBacks" 4
.IX Item "SetDirectXPathCallBacks"
.Vb 1
\& SetDirectXPathCallBacks(xpath=>function, etc...)
.Ve
.Sp
registers a callback function
for each xpath specified.  If
Net::XMPP matches the xpath,
then it calls the function with
two arguments:
.Sp
.Vb 2
\&  the session ID, and the
\&  XML::Stream::Node object.
.Ve
.Sp
Xpaths are rooted at each
packet:
.Sp
.Vb 3
\&  /anything
\&  /anotherthing/foo/[1]
\&  ...
.Ve
.Sp
The big difference between this
and regular XPathCallBacks is
the fact that this passes in
the \s-1XML\s0 directly and not a
Net::XMPP based object.
.IP "RemoveDirectXPathCallBacks" 4
.IX Item "RemoveDirectXPathCallBacks"
.Vb 1
\&  RemoveDirectXPathCallBacks(xpath=>function, etc...)
.Ve
.Sp
unregisters a callback
function for each xpath
specified.
.IP "Process" 4
.IX Item "Process"
.Vb 10
\&    Process(integer)
\&takes the timeout period as an argument.  If no
\&timeout is listed then the function blocks until
\&a packet is received.  Otherwise it waits that
\&number of seconds and then exits so your program
\&can continue doing useful things.  NOTE: This is
\&important for GUIs.  You need to leave time to
\&process GUI commands even if you are waiting for
\&packets.  The following are the possible return
\&values, and what they mean:
\&
\&    1   \- Status ok, data received.
\&    0   \- Status ok, no data received.
\&  undef \- Status not ok, stop processing.
.Ve
.Sp
\&\s-1IMPORTANT:\s0 You need to check the output of every
Process.  If you get an undef then the connection
died and you should behave accordingly.
.IP "Send" 4
.IX Item "Send"
.Vb 2
\&    Send(object, ignoreActivity) 
\&    Send(string, ignoreActivity)
.Ve
.Sp
takes either a Net::XMPP::xxxxx object or
an \s-1XML\s0 string as an argument and sends it to
the server.  If you set ignoreActivty to 1,
then the XML::Stream module will not record
this packet as couting towards user activity.
.SS "\s-1ID\s0 Functions"
.IX Subsection "ID Functions"
.IP "SendWithID" 4
.IX Item "SendWithID"
.Vb 2
\&    SendWithID(object)
\&    SendWithID(string)
.Ve
.Sp
takes either a Net::XMPP::xxxxx object or an
\&\s-1XML\s0 string as an argument, adds the next
available \s-1ID\s0 number and sends that packet to
the server.  Returns the \s-1ID\s0 number assigned.
.IP "SendAndReceiveWithID" 4
.IX Item "SendAndReceiveWithID"
.Vb 2
\&    SendAndReceiveWithID(object, timeout)
\&    SendAndReceiveWithID(string, timeout)
.Ve
.Sp
uses SendWithID and WaitForID to
provide a complete way to send and
receive packets with IDs.  Can take
either a Net::XMPP::xxxxx object
or an \s-1XML\s0 string.  Returns the
proper Net::XMPP::xxxxx object
based on the type of packet
received.  The timeout is passed
on to WaitForID, see that function
for how the timeout works.
.IP "ReceivedID" 4
.IX Item "ReceivedID"
.Vb 1
\& ReceivedID(integer)
.Ve
.Sp
returns 1 if a packet has been received with
specified \s-1ID, 0\s0 otherwise.
.IP "GetID" 4
.IX Item "GetID"
.Vb 1
\&    GetID(integer)
.Ve
.Sp
returns the proper Net::XMPP::xxxxx object based
on the type of packet received with the specified
\&\s-1ID. \s0 If the \s-1ID\s0 has been received the GetID returns 0.
.IP "WaitForID" 4
.IX Item "WaitForID"
.Vb 1
\&  WaitForID(integer, timeout)
.Ve
.Sp
blocks until a packet with the \s-1ID\s0 is received.
Returns the proper Net::XMPP::xxxxx object
based on the type of packet received.  If the
timeout limit is reached then if the packet
does come in, it will be discarded.
.Sp
\&\s-1NOTE: \s0 Only <iq/> officially support ids, so sending a <message/>, or
<presence/> with an id is a risk.  The server will ignore the
id tag and pass it through, so both clients must support the
id tag for these functions to be useful.
.SS "Namespace Functions"
.IX Subsection "Namespace Functions"
.IP "AddNamespace" 4
.IX Item "AddNamespace"
.Vb 3
\&    AddNamespace(ns=>string, 
\&                 tag=>string,
\&                 xpath=>hash)
.Ve
.Sp
This function is very complex.
It is a little too complex to
discuss within the confines of
this small paragraph.  Please
refer to the man page for
Net::XMPP::Namespaces for the
full documentation on this
subject.
.SS "Message Functions"
.IX Subsection "Message Functions"
.IP "MessageSend" 4
.IX Item "MessageSend"
.Vb 1
\&    MessageSend(hash)
.Ve
.Sp
takes the hash and passes it to SetMessage in
Net::XMPP::Message (refer there for valid
settings).  Then it sends the message to the
server.
.SS "Presence Functions"
.IX Subsection "Presence Functions"
.IP "PresenceSend" 4
.IX Item "PresenceSend"
.Vb 2
\&  PresenceSend()
\&  PresenceSend(hash, signature=>string)
.Ve
.Sp
No arguments will send an empty
Presence to the server to tell it
that you are available.  If you
provide a hash, then it will pass
that hash to the \fISetPresence()\fR
function as defined in the
Net::XMPP::Presence module.
Optionally, you can specify a
signature and a jabber:x:signed
will be placed in the <presence/>.
.SS "Subscription Functions"
.IX Subsection "Subscription Functions"
.IP "Subscription" 4
.IX Item "Subscription"
.Vb 1
\& Subscription(hash)
.Ve
.Sp
taks the hash and passes it to SetPresence in
Net::XMPP::Presence (refer there for valid
settings).  Then it sends the subscription to
server.
.Sp
The valid types of subscription are:
.Sp
.Vb 4
\&  subscribe    \- subscribe to JID\*(Aqs presence
\&  unsubscribe  \- unsubscribe from JID\*(Aqs presence
\&  subscribed   \- response to a subscribe
\&  unsubscribed \- response to an unsubscribe
.Ve
.SS "Presence \s-1DB\s0 Functions"
.IX Subsection "Presence DB Functions"
.IP "PresenceDB" 4
.IX Item "PresenceDB"
.Vb 1
\& PresenceDB()
.Ve
.Sp
Tell the object to initialize the callbacks to
automatically populate the Presence \s-1DB.\s0
.IP "PresenceDBParse" 4
.IX Item "PresenceDBParse"
.Vb 1
\&  PresenceDBParse(Net::XMPP::Presence)
.Ve
.Sp
for every presence that you
receive pass the Presence
object to the \s-1DB\s0 so that
it can track the resources
and priorities for you.
Returns either the presence
passed in, if it not able
to parsed for the \s-1DB,\s0 or the
current presence as found by
the PresenceDBQuery
function.
.IP "PresenceDBDelete" 4
.IX Item "PresenceDBDelete"
.Vb 1
\&  PresenceDBDelete(string|Net::XMPP::JID)
.Ve
.Sp
delete thes \s-1JID\s0 entry from the \s-1DB.\s0
.IP "PresenceDBClear" 4
.IX Item "PresenceDBClear"
.Vb 1
\& PresenceDBClear()
.Ve
.Sp
delete all entries in the database.
.IP "PresenceDBQuery" 4
.IX Item "PresenceDBQuery"
.Vb 1
\&  PresenceDBQuery(string|Net::XMPP::JID)
.Ve
.Sp
returns the NX::Presence
that was last received for
the highest priority of
this \s-1JID. \s0 You can pass
it a string or a \s-1NX::JID\s0
object.
.IP "PresenceDBResources" 4
.IX Item "PresenceDBResources"
.Vb 1
\&  PresenceDBResources(string|Net::XMPP::JID)
.Ve
.Sp
returns an array of
resources in order
from highest priority
to lowest.
.SS "\s-1IQ\s0 Functions"
.IX Subsection "IQ Functions"
.SS "Auth Functions"
.IX Subsection "Auth Functions"
.IP "AuthSend" 4
.IX Item "AuthSend"
.Vb 3
\&    AuthSend(username=>string,
\&             password=>string,
\&             resource=>string)
.Ve
.Sp
takes all of the information and
builds a Net::XMPP::IQ::Auth packet.
It then sends that packet to the
server with an \s-1ID\s0 and waits for that
\&\s-1ID\s0 to return.  Then it looks in
resulting packet and determines if
authentication was successful for not.
The array returned from AuthSend looks
like this:
.Sp
.Vb 1
\&  [ type , message ]
.Ve
.Sp
If type is \*(L"ok\*(R" then authentication
was successful, otherwise message
contains a little more detail about the
error.
.SS "IQ::Register Functions"
.IX Subsection "IQ::Register Functions"
.IP "RegisterRequest" 4
.IX Item "RegisterRequest"
.Vb 2
\& RegisterRequest(to=>string,  timeout=>int)
\& RegisterRequest()
.Ve
.Sp
send an <iq/> request to the specified
server/transport, if not specified it
sends to the current active server.
The function returns a hash that
contains the required fields.   Here
is an example of the hash:
.Sp
\&\f(CW$hash\fR{fields}    \- The raw fields from
                   the iq:register.
                   To be used if there
                   is no x:data in the
                   packet.
.Sp
\&\f(CW$hash\fR{instructions} \- How to fill out
                      the form.
.Sp
\&\f(CW$hash\fR{form}   \- The new dynamic forms.
.Sp
In \f(CW$hash\fR{form}, the fields that are
present are the required fields the
server needs.
.IP "RegisterSend" 4
.IX Item "RegisterSend"
.Vb 1
\&  RegisterSend(hash)
.Ve
.Sp
takes the contents of the hash and passes it
to the SetRegister function in the module
Net::XMPP::Query jabber:iq:register namespace.
This function returns an array that looks like
this:
.Sp
.Vb 1
\&  [ type , message ]
.Ve
.Sp
If type is \*(L"ok\*(R" then registration was
successful, otherwise message contains a
little more detail about the error.
.SS "Roster Functions"
.IX Subsection "Roster Functions"
.IP "Roster" 4
.IX Item "Roster"
.Vb 1
\&    Roster()
.Ve
.Sp
returns a Net::XMPP::Roster object.  This will automatically
intercept all of the roster and presence packets sent from
the server and give you an accurate Roster.  For more
information please read the man page for Net::XMPP::Roster.
.IP "RosterParse" 4
.IX Item "RosterParse"
.Vb 1
\&    RosterParse(IQ object)
.Ve
.Sp
returns a hash that contains the roster
parsed into the following data structure:
.Sp
.Vb 2
\&  $roster{\*(Aqbob@jabber.org\*(Aq}\->{name}
\&                      \- Name you stored in the roster
\&
\&  $roster{\*(Aqbob@jabber.org\*(Aq}\->{subscription}
\&                      \- Subscription status
\&                        (to, from, both, none)
\&
\&  $roster{\*(Aqbob@jabber.org\*(Aq}\->{ask}
\&                      \- The ask status from this user
\&                        (subscribe, unsubscribe)
\&
\&  $roster{\*(Aqbob@jabber.org\*(Aq}\->{groups}
\&                      \- Array of groups that
\&                        bob@jabber.org is in
.Ve
.IP "RosterGet" 4
.IX Item "RosterGet"
.Vb 1
\&  RosterGet()
.Ve
.Sp
sends an empty Net::XMPP::IQ::Roster tag to the
server so the server will send the Roster to the
client.  Returns the above hash from RosterParse.
.IP "RosterRequest" 4
.IX Item "RosterRequest"
.Vb 1
\&  RosterRequest()
.Ve
.Sp
sends an empty Net::XMPP::IQ::Roster tag to the
server so the server will send the Roster to the
client.
.IP "RosterAdd" 4
.IX Item "RosterAdd"
.Vb 1
\&    RosterAdd(hash)
.Ve
.Sp
sends a packet asking that the jid be
added to the roster.  The hash format
is defined in the SetItem function
in the Net::XMPP::Query jabber:iq:roster
namespace.
.IP "RosterRemove" 4
.IX Item "RosterRemove"
.Vb 1
\& RosterRemove(hash)
.Ve
.Sp
sends a packet asking that the jid be
removed from the roster.  The hash
format is defined in the SetItem function
in the Net::XMPP::Query jabber:iq:roster
namespace.
.SS "Roster \s-1DB\s0 Functions"
.IX Subsection "Roster DB Functions"
.IP "RosterDB" 4
.IX Item "RosterDB"
.Vb 1
\&    RosterDB()
.Ve
.Sp
Tell the object to initialize the callbacks to
automatically populate the Roster \s-1DB. \s0 If you do this,
then make sure that you call \fIRosterRequest()\fR instead of
\&\fIRosterGet()\fR so that the callbacks can catch it and
parse it.
.IP "RosterDBParse" 4
.IX Item "RosterDBParse"
.Vb 1
\&    RosterDBParse(IQ object)
.Ve
.Sp
If you want to manually control the
database, then you can pass in all iq
packets with jabber:iq:roster queries to
this function.
.IP "RosterDBAdd" 4
.IX Item "RosterDBAdd"
.Vb 1
\&  RosterDBAdd(jid,hash)
.Ve
.Sp
Add a new \s-1JID\s0 into the roster \s-1DB. \s0 The \s-1JID\s0
is either a string, or a Net::XMPP::JID
object.  The hash must be the same format as
the has returned by RosterParse above, and
is the actual hash, not a reference.
.IP "RosterDBRemove" 4
.IX Item "RosterDBRemove"
.Vb 1
\&  RosterDBRemove(jid)
.Ve
.Sp
Remove a \s-1JID\s0 from the roster \s-1DB.\s0 The \s-1JID\s0 is
either a string, or a Net::XMPP::JID object.
.IP "RosterDBClear" 4
.IX Item "RosterDBClear"
Remove all JIDs from the roster \s-1DB.\s0
.IP "RosterDBExists" 4
.IX Item "RosterDBExists"
.Vb 1
\& RosterDBExists(jid)
.Ve
.Sp
return 1 if the \s-1JID\s0 exists in the roster \s-1DB,\s0
undef otherwise.  The \s-1JID\s0 is either a string,
or a Net::XMPP::JID object.
.IP "RosterDBJIDs" 4
.IX Item "RosterDBJIDs"
.Vb 1
\&  RosterDBJIDs()
.Ve
.Sp
returns a list of Net::XMPP::JID objects that
represents all of the JIDs in the \s-1DB.\s0
.IP "RosterDBGroups" 4
.IX Item "RosterDBGroups"
returns the complete list of roster groups in the
roster.
.IP "RosterDBGroupExists" 4
.IX Item "RosterDBGroupExists"
.Vb 1
\&    RosterDBGroupExists(group)
.Ve
.Sp
return 1 if the group is a group in the
roster \s-1DB,\s0 undef otherwise.
.IP "RosterDBGroupJIDs" 4
.IX Item "RosterDBGroupJIDs"
.Vb 1
\&    RosterDBGroupJIDs(group)
.Ve
.Sp
returns a list of Net::XMPP::JID objects
that represents all of the JIDs in the
specified roster group.
.IP "RosterDBNonGroupJIDs" 4
.IX Item "RosterDBNonGroupJIDs"
returns a list of Net::XMPP::JID objects
that represents all of the JIDs not in a
roster group.
.IP "RosterDBQuery" 4
.IX Item "RosterDBQuery"
.Vb 1
\&  RosterDBQuery(jid)
.Ve
.Sp
returns a hash containing the data from the
roster \s-1DB\s0 for the specified \s-1JID. \s0 The \s-1JID\s0 is
either a string, or a Net::XMPP::JID object.
The hash format the same as in RosterParse
above.
.IP "RosterDBQuery" 4
.IX Item "RosterDBQuery"
.Vb 1
\&  RosterDBQuery(jid,key)
.Ve
.Sp
returns the entry from the above hash for
the given key.  The available keys are:
  name, ask, subsrcription and groups
The \s-1JID\s0 is either a string, or a
Net::XMPP::JID object.
.SH "AUTHOR"
.IX Header "AUTHOR"
Originally authored by Ryan Eatmon.
.PP
Previously maintained by Eric Hacker.
.PP
Currently maintained by Darian Anthony Patrick.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This module is free software, you can redistribute it and/or modify it
under the \s-1LGPL 2.1.\s0