Net::X...:Roster(3pm)

📦
version 1.05 · 8 versions
, in opensuse-leap 16.0

💅 NAME 💅

Net::XMPP::Roster — the XMPP Roster object, bestie. It's giving "your whole buddy list, but make it a Perl module."

(Also, hi, this is the manual page for Net::X...:Roster(3pm) from the User Contributed Perl Documentation — yes the title got crunched by the terminal, it's fine, we move.)

✨ SYNOPSIS ✨

Okay so Net::XMPP::Roster is a module that hands a developer an easy interface to an XMPP roster. It's got high level functions to query, update, and manage a user's roster. Literally everything you need, no cap.

Net::XMPP::Roster is a module that provides a developer an easy
interface to an XMPP roster.  It provides high level functions to query,
update, and manage a user's roster.

🦋 DESCRIPTION 🦋

The Roster object is on a mission: give you an easy to use API for interfacing with a user's roster. And the way it does this?? When you instantiate it, it automatically registers with the connection to receive the correct packets so that it can track all roster updates, and presence packets. It's self-sufficient. Main character energy. You don't even have to ask. 🫶

🌸 Basic Functions 🌸

my $Client = Net::XMPP::Client->new(...);

my $Roster = Net::XMPP::Roster->new(connection=>$Client);
  or
my $Roster = $Client->Roster();

$Roster->clear();

if ($Roster->exists('bob@jabber.org')) { ... }
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('bob@jabber.org')) { ... }
if ($Roster->online(Net::XMPP::JID)) { ... }

my %hash = $Roster->query('bob@jabber.org');
my %hash = $Roster->query(Net::XMPP::JID);

my $name = $Roster->query('bob@jabber.org',"name");
my $ask  = $Roster->query(Net::XMPP::JID,"ask");

my $resource = $Roster->resource('bob@jabber.org');
my $resource = $Roster->resource(Net::XMPP::JID);

my %hash = $Roster->resourceQuery('bob@jabber.org',"Home");
my %hash = $Roster->resourceQuery(Net::XMPP::JID,"Club");

my $show   = $Roster->resourceQuery('bob@jabber.org',"Home","show");
my $status = $Roster->resourceQuery(Net::XMPP::JID,"Work","status");

my @resource = $Roster->resources('bob@jabber.org');
my @resource = $Roster->resources(Net::XMPP::JID);

$Roster->resourceStore('bob@jabber.org',"Home","gpgkey",key);
$Roster->resourceStore(Net::XMPP::JID,"logged on","2004/04/07 ...");

$Roster->store('bob@jabber.org',"avatar",avatar);
$Roster->store(Net::XMPP::JID,"display_name","Bob");

🔥 Advanced Functions 🔥

Okay these ones? You only need them if you want to manually control the Roster. Like, hand on the wheel. Delulu but valid. 🙈

$Roster->add('bob@jabber.org',
             name=>"Bob",
             groups=>["Friends"]
            );
$Roster->add(Net::XMPP::JID);

$Roster->addResource('bob@jabber.org',
                     "Home",
                     show=>"dnd",
                     status=>"Working"
                    );
$Roster->addResource(Net::XMPP::JID,"Work");

$Roster->remove('bob@jabber.org');
$Roster->remove(Net::XMPP::JID);

$Roster->removeResource('bob@jabber.org',"Home");
$Roster->removeResource(Net::XMPP::JID,"Work");

$Roster->handler(Net::XMPP::IQ);
$Roster->handler(Net::XMPP::Presence);

👑 METHODS 👑

🎀 Basic Functions 🎀

new

new(connection=>object)

This creates and initializes the Roster object. The connection object is required — the Roster literally cannot talk to the main connection object without it. And it needs to be an object that inherits from Net::XMPP::Connection. No substitutes, no randoms. 💅

clear

clear()

removes everything from the database. Total reset. Fresh start. We love a clean slate. ✨

exists

exists(jid)

return 1 if the JID exists in the database, undef otherwise. The jid can either be a string, or a Net::XMPP::JID object — your call, both slay.

groupExists

groupExists(group)

return 1 if the group exists in the database, undef otherwise. Vibe check for groups. 🦋

groups

groups()

Returns a list of all of the roster groups. All of them. The whole squad. 🌈

jids

jids([type, [group]])

returns a list of all of the matching JIDs. The valid types are:

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

online

online(jid)

return 1 if the JID is online, undef otherwise. The jid can either be a string, or a Net::XMPP::JID object. Ooh she's active. 👀

query

query(jid, [key])

return a hash representing all of the data in the DB for this JID. 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. One key, one value, zero drama.

resource

resource(jid)

return the string representing the resource with the highest priority for the JID. The jid can either be a string, or a Net::XMPP::JID object. Highest priority gets the crown. 👑

resourceQuery

resourceQuery(jid,
              resource,
              [key])

return a hash representing all of the data the DB for the resource for this JID. 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.

resources

resources(jid)

returns the list of resources for the JID in order of highest priority to lowest priority. The jid can either be a string, or a Net::XMPP::JID object. Ranking them fr fr. 🔥

resourceStore

resourceStore(jid,
              resource,
              key,
              value)

store the specified value in the DB under the specified key for the resource for this JID. The jid can either be a string, or a Net::XMPP::JID object.

store

store(jid, key, value)

store the specified value in the DB under the specified key for this JID. The jid can either be a string, or a Net::XMPP::JID object.

💜 Advanced Functions 💜

add

add(jid,
    ask=>string,
    groups=>arrayref,
    name=>string,
    subscription=>string)

Manually adds the JID to the Roster with the specified roster item settings. Heads up though — this does not handle subscribing to other users, only manipulating the Roster object. The jid can either be a string or a Net::XMPP::JID. Don't get it twisted. 🙈

addResource

addResource(jid,
            resource,
            priority=>int,
            show=>string,
            status=>string)

Manually add the resource to the JID in the Roster with the specified presence settings. Again: this does not handle subscribing to other users, only manipulating the Roster object. The jid can either be a string or a Net::XMPP::JID.

remove

remove(jid)

Removes all reference to the JID from the Roster object. The jid can either be a string or a Net::XMPP::JID. Blocked, deleted, gone — but like, from the Roster object specifically. 💀

removeResource

removeResource(jid,
               resource)

Removes the resource from the jid in the Roster object. The jid can either be a string or a Net::XMPP::JID.

handler

handler(packet)

Take either a Net::XMPP::IQ or Net::XMPP::Presence packet and parse them according to the rules of the Roster object. Quick note though: it will only waste CPU time if you pass in IQs or Presences that are not roster related. So like… don't do that. Be efficient bestie. 😭

🍓 AUTHOR 🍓

Originally authored by Ryan Eatmon.

Previously maintained by Eric Hacker.

Currently maintained by Darian Anthony Patrick.

This module is free software, you can redistribute it and/or modify it under the LGPL 2.1.

And that's the whole page, bestie! 🎀 This masterpiece of documentation is perl v5.42.0, dated 2016-01-12 — she's vintage, she's iconic, she ate and left no crumbs. Go forth and roster. 💖✨

📦 where this page comes from