.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" 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 "2014-04-11" "perl v5.18.2" "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"
.Vb 4
\& Net::XMPP::Protocol is a module that provides a developer easy
\& access to the XMPP Instant Messaging protocol. It provides high
\& level functions to the Net::XMPP Client object. These functions are
\& inherited by that modules.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Vb 4
\& Protocol.pm seeks to provide enough high level APIs and automation of
\& the low level APIs that writing a XMPP 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.
\&
\& 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.
\&
\& For more information on how the details for how Net::XMPP is written
\& please see the help for Net::XMPP itself.
\&
\& For more information on writing a Client see Net::XMPP::Client.
.Ve
.SS "Modes"
.IX Subsection "Modes"
.Vb 2
\& Several of the functions take a mode argument that let you specify how
\& the function should behave:
\&
\& block \- send the packet with an ID, and then block until an answer
\& comes back. You can optionally specify a timeout so that
\& you do not block forever.
\&
\& nonblock \- send the packet with an ID, 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...)
\&
\& passthru \- send the packet with an ID, but do NOT register it with
\& Net::XMPP, then return the ID. This is useful when
\& combined with the XPath function because you can register
\& a one shot function tied to the id you get back.
.Ve
.SS "Basic Functions"
.IX Subsection "Basic Functions"
.Vb 3
\& use Net::XMPP qw( Client );
\& $Con = new Net::XMPP::Client(); # 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("XML");
\&
\& $Con\->Send($object,1);
\& $Con\->Send("XML",1);
\&
\& $Con\->Disconnect();
.Ve
.SS "\s-1ID\s0 Functions"
.IX Subsection "ID Functions"
.Vb 10
\& $id = $Con\->SendWithID($sendObj);
\& $id = $Con\->SendWithID("XML");
\& $receiveObj = $Con\->SendAndReceiveWithID($sendObj);
\& $receiveObj = $Con\->SendAndReceiveWithID($sendObj,
\& 10);
\& $receiveObj = $Con\->SendAndReceiveWithID("XML");
\& $receiveObj = $Con\->SendAndReceiveWithID("XML",
\& 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"
.Vb 3
\& GetErrorCode() \- returns a string that will hopefully contain some
\& useful information about why a function returned
\& an undef to you.
\&
\& SetErrorCode(string) \- set a useful error message before you return
\& an undef to the caller.
\&
\& SetCallBacks(message=>function, \- sets the callback functions for
\& presence=>function, the top level tags listed. The
\& iq=>function, available tags to look for are
\& send=>function, , , and
\& receive=>function, . If a packet is received
\& update=>function) with an ID which is found in the
\& registered ID list (see RegisterID
\& below) then it is not sent to
\& these functions, instead it
\& is inserted into a LIST and can
\& be retrieved by some functions
\& we will mention later.
\&
\& send and receive are used to
\& log what XML is sent and received.
\& update is used as way to update
\& your program while waiting for
\& a packet with an ID to be
\& returned (useful for GUI apps).
\&
\& 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.
\&
\& 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.
\&
\& If you set the function to undef,
\& then the callback is removed from
\& the list.
\&
\& SetPresenceCallBacks(type=>function \- sets the callback functions for
\& etc...) 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.
\& "available"
\& "unavailable"
\& "subscribe"
\& "unsubscribe"
\& "subscribed"
\& "unsubscribed"
\& "probe"
\& "error"
\& When it gets a
\& packet it checks the type=\*(Aq\*(Aq
\& for a defined callback. If
\& there is one then it calls the
\& function with two arguments:
\& the session ID, and the
\& Net::XMPP::Presence object.
\&
\& If you set the function to
\& undef, then the callback is
\& removed from the list.
\&
\& NOTE: If you use this, which is a cleaner method,
\& then you must *NOT* specify a callback for
\& presence in the SetCallBacks function.
\&
\& 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
\&
\&
\& SetMessageCallBacks(type=>function, \- sets the callback functions for
\& etc...) 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.
\& "normal"
\& "chat"
\& "groupchat"
\& "headline"
\& "error"
\& When it gets a packet
\& it checks the type=\*(Aq\*(Aq for a
\& defined callback. If there is
\& one then it calls the function
\& with two arguments:
\& the session ID, and the
\& Net::XMPP::Message object.
\&
\& If you set the function to
\& undef, then the callback is
\& removed from the list.
\&
\& NOTE: If you use this, which is a cleaner method,
\& then you must *NOT* specify a callback for
\& message in the SetCallBacks function.
\&
\&
\& SetIQCallBacks(namespace=>{ \- sets the callback functions for
\& get=>function, the specified namespace. The
\& set=>function, function takes namespaces as the
\& result=>function main key, and lets you specify a
\& }, function for each type of packet
\& etc...) you can get.
\& "get"
\& "set"
\& "result"
\& When it gets an packet it
\& checks the type=\*(Aq\*(Aq and the
\& xmlns=\*(Aq\*(Aq for a defined callback.
\& If there is one then it calls
\& the function with two arguments:
\& the session ID, and the
\& Net::XMPP::xxxx object.
\&
\& If you set the function to undef,
\& then the callback is removed from
\& the list.
\&
\& NOTE: If you use this, which is a cleaner method,
\& then you must *NOT* specify a callback for
\& iq in the SetCallBacks function.
\&
\& SetXPathCallBacks(xpath=>function, \- registers a callback function
\& etc...) for each xpath specified. If
\& Net::XMPP matches the xpath,
\& then it calls the function with
\& two arguments:
\& the session ID, and the
\& Net::XMPP::Message object.
\&
\& Xpaths are rooted at each
\& packet:
\& /message[@type="chat"]
\& /iq/*[xmlns="jabber:iq:roster"][1]
\& ...
\&
\& RemoveXPathCallBacks(xpath=>function, \- unregisters a callback
\& etc...) function for each xpath
\& specified.
\&
\& SetDirectXPathCallBacks(xpath=>function, \- registers a callback function
\& etc...) for each xpath specified. If
\& Net::XMPP matches the xpath,
\& then it calls the function with
\& two arguments:
\& the session ID, and the
\& XML::Stream::Node object.
\&
\& Xpaths are rooted at each
\& packet:
\& /anything
\& /anotherthing/foo/[1]
\& ...
\&
\& The big difference between this
\& and regular XPathCallBacks is
\& the fact that this passes in
\& the XML directly and not a
\& Net::XMPP based object.
\&
\& RemoveDirectXPathCallBacks(xpath=>function, \- unregisters a callback
\& etc...) function for each xpath
\& specified.
\&
\& 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.
\&
\& IMPORTANT: You need to check the output of every
\& Process. If you get an undef then the connection
\& died and you should behave accordingly.
\&
\& Send(object, \- takes either a Net::XMPP::xxxxx object or
\& ignoreActivity) an XML string as an argument and sends it to
\& Send(string, the server. If you set ignoreActivty to 1,
\& ignoreActivity) then the XML::Stream module will not record
\& this packet as couting towards user activity.
\&=head2 ID Functions
\&
\& SendWithID(object) \- takes either a Net::XMPP::xxxxx object or an
\& SendWithID(string) XML string as an argument, adds the next
\& available ID number and sends that packet to
\& the server. Returns the ID number assigned.
\&
\& SendAndReceiveWithID(object, \- uses SendWithID and WaitForID to
\& timeout) provide a complete way to send and
\& SendAndReceiveWithID(string, receive packets with IDs. Can take
\& timeout) either a Net::XMPP::xxxxx object
\& or an XML 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.
\&
\& ReceivedID(integer) \- returns 1 if a packet has been received with
\& specified ID, 0 otherwise.
\&
\& GetID(integer) \- returns the proper Net::XMPP::xxxxx object based
\& on the type of packet received with the specified
\& ID. If the ID has been received the GetID returns
\& 0.
\&
\& WaitForID(integer, \- blocks until a packet with the ID is received.
\& timeout) 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.
\&
\&
\& NOTE: Only officially support ids, so sending a , or
\& 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.
.Ve
.SS "Namespace Functions"
.IX Subsection "Namespace Functions"
.Vb 8
\& AddNamespace(ns=>string, \- This function is very complex.
\& tag=>string, It is a little too complex to
\& xpath=>hash) 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.
.Ve
.SS "Message Functions"
.IX Subsection "Message Functions"
.Vb 4
\& MessageSend(hash) \- 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.
.Ve
.SS "Presence Functions"
.IX Subsection "Presence Functions"
.Vb 10
\& PresenceSend() \- no arguments will send an empty
\& PresenceSend(hash, Presence to the server to tell it
\& signature=>string) that you are available. If you
\& provide a hash, then it will pass
\& that hash to the SetPresence()
\& 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 .
.Ve
.SS "Subscription Functions"
.IX Subsection "Subscription Functions"
.Vb 4
\& Subscription(hash) \- taks the hash and passes it to SetPresence in
\& Net::XMPP::Presence (refer there for valid
\& settings). Then it sends the subscription to
\& server.
\&
\& The valid types of subscription are:
\&
\& 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"
.Vb 2
\& PresenceDB() \- Tell the object to initialize the callbacks to
\& automatically populate the Presence DB.
\&
\& PresenceDBParse(Net::XMPP::Presence) \- for every presence that you
\& receive pass the Presence
\& object to the DB 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 DB, or the
\& current presence as found by
\& the PresenceDBQuery
\& function.
\&
\& PresenceDBDelete(string|Net::XMPP::JID) \- delete thes JID entry
\& from the DB.
\&
\& PresenceDBClear() \- delete all entries in the database.
\&
\& PresenceDBQuery(string|Net::XMPP::JID) \- returns the NX::Presence
\& that was last received for
\& the highest priority of
\& this JID. You can pass
\& it a string or a NX::JID
\& object.
\&
\& PresenceDBResources(string|Net::XMPP::JID) \- returns an array of
\& resources in order
\& from highest priority
\& to lowest.
.Ve
.SS "\s-1IQ\s0 Functions"
.IX Subsection "IQ Functions"
.SS "Auth Functions"
.IX Subsection "Auth Functions"
.Vb 10
\& AuthSend(username=>string, \- takes all of the information and
\& password=>string, builds a Net::XMPP::IQ::Auth packet.
\& resource=>string) It then sends that packet to the
\& server with an ID and waits for that
\& ID to return. Then it looks in
\& resulting packet and determines if
\& authentication was successful for not.
\& The array returned from AuthSend looks
\& like this:
\& [ type , message ]
\& If type is "ok" then authentication
\& was successful, otherwise message
\& contains a little more detail about the
\& error.
.Ve
.SS "IQ::Register Functions"
.IX Subsection "IQ::Register Functions"
.Vb 6
\& RegisterRequest(to=>string, \- send an request to the specified
\& timeout=>int) server/transport, if not specified it
\& RegisterRequest() sends to the current active server.
\& The function returns a hash that
\& contains the required fields. Here
\& is an example of the hash:
\&
\& $hash{fields} \- The raw fields from
\& the iq:register.
\& To be used if there
\& is no x:data in the
\& packet.
\& $hash{instructions} \- How to fill out
\& the form.
\& $hash{form} \- The new dynamic forms.
\&
\& In $hash{form}, the fields that are
\& present are the required fields the
\& server needs.
\&
\& RegisterSend(hash) \- 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:
\&
\& [ type , message ]
\&
\& If type is "ok" then registration was
\& successful, otherwise message contains a
\& little more detail about the error.
.Ve
.SS "Roster Functions"
.IX Subsection "Roster Functions"
.Vb 4
\& Roster() \- 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.
\&
\& RosterParse(IQ object) \- returns a hash that contains the roster
\& parsed into the following data structure:
\&
\& $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
\&
\& RosterGet() \- 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.
\&
\& RosterRequest() \- sends an empty Net::XMPP::IQ::Roster tag to the
\& server so the server will send the Roster to the
\& client.
\&
\& RosterAdd(hash) \- 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.
\&
\& RosterRemove(hash) \- 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.
.Ve
.SS "Roster \s-1DB\s0 Functions"
.IX Subsection "Roster DB Functions"
.Vb 5
\& RosterDB() \- Tell the object to initialize the callbacks to
\& automatically populate the Roster DB. If you do this,
\& then make sure that you call RosterRequest() instead of
\& RosterGet() so that the callbacks can catch it and
\& parse it.
\&
\& RosterDBParse(IQ object) \- If you want to manually control the
\& database, then you can pass in all iq
\& packets with jabber:iq:roster queries to
\& this function.
\&
\& RosterDBAdd(jid,hash) \- Add a new JID into the roster DB. The JID
\& 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.
\&
\& RosterDBRemove(jid) \- Remove a JID from the roster DB. The JID is
\& either a string, or a Net::XMPP::JID object.
\&
\& RosterDBClear() \- Remove all JIDs from the roster DB.
\&
\& RosterDBExists(jid) \- return 1 if the JID exists in the roster DB,
\& undef otherwise. The JID is either a string,
\& or a Net::XMPP::JID object.
\&
\& RosterDBJIDs() \- returns a list of Net::XMPP::JID objects that
\& represents all of the JIDs in the DB.
\&
\& RosterDBGroups() \- returns the complete list of roster groups in the
\& roster.
\&
\& RosterDBGroupExists(group) \- return 1 if the group is a group in the
\& roster DB, undef otherwise.
\&
\& RosterDBGroupJIDs(group) \- returns a list of Net::XMPP::JID objects
\& that represents all of the JIDs in the
\& specified roster group.
\&
\& RosterDBNonGroupJIDs() \- returns a list of Net::XMPP::JID objects
\& that represents all of the JIDs not in a
\& roster group.
\&
\& RosterDBQuery(jid) \- returns a hash containing the data from the
\& roster DB for the specified JID. The JID is
\& either a string, or a Net::XMPP::JID object.
\& The hash format the same as in RosterParse
\& above.
\&
\& RosterDBQuery(jid,key) \- returns the entry from the above hash for
\& the given key. The available keys are:
\& name, ask, subsrcription and groups
\& The JID is either a string, or a
\& Net::XMPP::JID object.
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Ryan Eatmon
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This module is free software, you can redistribute it and/or modify it
under the \s-1LGPL.\s0