.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.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::Roster 3pm"
.TH Net::XMPP::Roster 3pm "2022-06-16" "perl v5.34.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::Roster \- XMPP Roster Object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Net::XMPP::Roster is a module that provides a developer an easy
interface to an \s-1XMPP\s0 roster.  It provides high level functions to
query, update, and manage a user's roster.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Roster object seeks to provide an easy to use \s-1API\s0 for interfacing
with a user's roster.  When you instantiate it, it automatically
registers with the connection to receivce the correct packets so
that it can track all roster updates, and presence packets.
.SS "Basic Functions"
.IX Subsection "Basic Functions"
.Vb 1
\&  my $Client = Net::XMPP::Client\->new(...);
\&
\&  my $Roster = Net::XMPP::Roster\->new(connection=>$Client);
\&    or
\&  my $Roster = $Client\->Roster();
\&
\&  $Roster\->clear();
\&
\&  if ($Roster\->exists(\*(Aqbob@jabber.org\*(Aq)) { ... }
\&  if ($Roster\->exists(Net::XMPP::JID)) { ... }
\&
\&  if ($Roster\->groupExists("Friends")) { ... }
\&
\&  my @groups = $Roster\->groups();
\&
\&  my @jids    = $Roster\->jids();
\&  my @friends = $Roster\->jids("group","Friends");
\&  my @unfiled = $Roster\->jids("nogroup");
\&
\&  if ($Roster\->online(\*(Aqbob@jabber.org\*(Aq)) { ... }
\&  if ($Roster\->online(Net::XMPP::JID)) { ... }
\&
\&  my %hash = $Roster\->query(\*(Aqbob@jabber.org\*(Aq);
\&  my %hash = $Roster\->query(Net::XMPP::JID);
\&
\&  my $name = $Roster\->query(\*(Aqbob@jabber.org\*(Aq,"name");
\&  my $ask  = $Roster\->query(Net::XMPP::JID,"ask");
\&
\&  my $resource = $Roster\->resource(\*(Aqbob@jabber.org\*(Aq);
\&  my $resource = $Roster\->resource(Net::XMPP::JID);
\&
\&  my %hash = $Roster\->resourceQuery(\*(Aqbob@jabber.org\*(Aq,"Home");
\&  my %hash = $Roster\->resourceQuery(Net::XMPP::JID,"Club");
\&
\&  my $show   = $Roster\->resourceQuery(\*(Aqbob@jabber.org\*(Aq,"Home","show");
\&  my $status = $Roster\->resourceQuery(Net::XMPP::JID,"Work","status");
\&
\&  my @resource = $Roster\->resources(\*(Aqbob@jabber.org\*(Aq);
\&  my @resource = $Roster\->resources(Net::XMPP::JID);
\&
\&  $Roster\->resourceStore(\*(Aqbob@jabber.org\*(Aq,"Home","gpgkey",key);
\&  $Roster\->resourceStore(Net::XMPP::JID,"logged on","2004/04/07 ...");
\&
\&  $Roster\->store(\*(Aqbob@jabber.org\*(Aq,"avatar",avatar);
\&  $Roster\->store(Net::XMPP::JID,"display_name","Bob");
.Ve
.SS "Advanced Functions"
.IX Subsection "Advanced Functions"
These functions are only needed if you want to manually control
the Roster.
.PP
.Vb 5
\&  $Roster\->add(\*(Aqbob@jabber.org\*(Aq,
\&               name=>"Bob",
\&               groups=>["Friends"]
\&              );
\&  $Roster\->add(Net::XMPP::JID);
\&
\&  $Roster\->addResource(\*(Aqbob@jabber.org\*(Aq,
\&                       "Home",
\&                       show=>"dnd",
\&                       status=>"Working"
\&                      );
\&  $Roster\->addResource(Net::XMPP::JID,"Work");
\&
\&  $Roster\->remove(\*(Aqbob@jabber.org\*(Aq);
\&  $Roster\->remove(Net::XMPP::JID);
\&
\&  $Roster\->removeResource(\*(Aqbob@jabber.org\*(Aq,"Home");
\&  $Roster\->removeResource(Net::XMPP::JID,"Work");
\&
\&  $Roster\->handler(Net::XMPP::IQ);
\&  $Roster\->handler(Net::XMPP::Presence);
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "Basic Functions"
.IX Subsection "Basic Functions"
.IP "new" 4
.IX Item "new"
.Vb 1
\&  new(connection=>object)
.Ve
.Sp
This creates and initializes the Roster
object.  The connection object is required
so that the Roster can interact with the
main connection object.  It needs to be an
object that inherits from Net::XMPP::Connection.
.IP "clear" 4
.IX Item "clear"
.Vb 1
\&  clear()
.Ve
.Sp
removes everything from the database.
.IP "exists" 4
.IX Item "exists"
.Vb 1
\&  exists(jid)
.Ve
.Sp
return 1 if the \s-1JID\s0 exists in the database, undef
otherwise.  The jid can either be a string, or a Net::XMPP::JID object.
.IP "groupExists" 4
.IX Item "groupExists"
.Vb 1
\&  groupExists(group)
.Ve
.Sp
return 1 if the group exists in the database, undef otherwise.
.IP "groups" 4
.IX Item "groups"
.Vb 1
\&  groups()
.Ve
.Sp
Returns a list of all of the roster groups.
.IP "jids" 4
.IX Item "jids"
.Vb 1
\&  jids([type, [group]])
.Ve
.Sp
returns a list of all of the matching JIDs.  The valid
types are:
.Sp
.Vb 4
\&                    all     \- return all JIDs in the roster. (default)
\&                    nogroup \- return all JIDs not in a roster group.
\&                    group   \- return all of the JIDs in the specified
\&                              roster group.
.Ve
.IP "online" 4
.IX Item "online"
.Vb 1
\&  online(jid)
.Ve
.Sp
return 1 if the \s-1JID\s0 is online, undef otherwise.  The
jid can either be a string, or a Net::XMPP::JID object.
.IP "query" 4
.IX Item "query"
.Vb 1
\&  query(jid, [key])
.Ve
.Sp
return a hash representing all of the data in the
\&\s-1DB\s0 for this \s-1JID.\s0  The jid can either be a string,
or a Net::XMPP::JID object.  If you specify a key,
then only the value for that key is returned.
.IP "resource" 4
.IX Item "resource"
.Vb 1
\&  resource(jid)
.Ve
.Sp
return the string representing the resource with the
highest priority for the \s-1JID.\s0  The jid can either be
a string, or a Net::XMPP::JID object.
.IP "resourceQuery" 4
.IX Item "resourceQuery"
.Vb 3
\&  resourceQuery(jid,     
\&                resource,
\&                [key])
.Ve
.Sp
return a hash representing all of the data
the \s-1DB\s0 for the resource for this \s-1JID.\s0  The
jid can either be a string, or a
Net::XMPP::JID object.  If you specify a
key, then only the value for that key is
returned.
.IP "resources" 4
.IX Item "resources"
.Vb 1
\&  resources(jid)
.Ve
.Sp
returns the list of resources for the \s-1JID\s0 in order
of highest priority to lowest priority.  The jid can
either be a string, or a Net::XMPP::JID object.
.IP "resourceStore" 4
.IX Item "resourceStore"
.Vb 4
\&  resourceStore(jid,     
\&                resource,
\&                key,     
\&                value)
.Ve
.Sp
store the specified value in the \s-1DB\s0 under
the specified key for the resource for this
\&\s-1JID.\s0  The jid can either be a string, or a
Net::XMPP::JID object.
.IP "store" 4
.IX Item "store"
.Vb 1
\&  store(jid, key, value)
.Ve
.Sp
store the specified value in the \s-1DB\s0 under the
specified key for this \s-1JID.\s0  The jid can either
be a string, or a Net::XMPP::JID object.
.SS "Advanced Functions"
.IX Subsection "Advanced Functions"
add(jid,                 \- Manually adds the \s-1JID\s0 to the Roster with the
    ask=>string,           specified roster item settings.  This does not
    groups=>arrayref       handle subscribing to other users, only
    name=>string,          manipulating the Roster object.  The jid
    subscription=>string)  can either be a string or a Net::XMPP::JID.
.PP
addResource(jid,            \- Manually add the resource to the \s-1JID\s0 in the
            resource,         Roster with the specified presence settings.
            priority=>int,    This does not handle subscribing to other
            show=>string,     users, only manipulating the Roster object.
            status=>string)   The jid can either be a string or a
                              Net::XMPP::JID.
.PP
remove(jid) \- Removes all reference to the \s-1JID\s0 from the Roster object.
              The jid can either be a string or a Net::XMPP::JID.
.PP
removeResource(jid,      \- Removes the resource from the jid in the
               resource)   Roster object.  The jid can either be a string
                           or a Net::XMPP::JID.
.PP
handler(packet) \- Take either a Net::XMPP::IQ or Net::XMPP::Presence
                  packet and parse them according to the rules of the
                  Roster object.  Note, that it will only waste \s-1CPU\s0 time
                  if you pass in IQs or Presences that are not roster
                  related.
.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