NAME

Net::XMPP2::IM::Roster - Instant messaging roster for XMPP

SYNOPSIS

   my $con = Net::XMPP2::IM::Connection->new (...);
   ...
   my $ro  = $con->roster;
   if (my $c = $ro->get_contact ('test@example.com')) {
      $c->make_message ()->add_body ("Hello there!")->send;
   }

DESCRIPTION

This module represents a class for roster objects which contain contact information.

It manages the roster of a JID connected by an Net::XMPP2::IM::Connection. It manages also the presence information that is received.

You get the roster by calling the roster method on an Net::XMPP2::IM::Connection object. There is no other way.

METHODS

is_retrieved

Returns true if this roster was fetched from the server or false if this roster hasn't been retrieved yet.

new_contact ($jid, $name, $groups, $cb)

This method sends a roster item creation request to the server. $jid is the JID of the contact. $name is the nickname of the contact, which can be undef. $groups should be a array reference containing the groups this contact should be in.

The callback in $cb will be called when the creation is finished. The first argument will be an Net::XMPP2::Error::IQ object if the request resulted in an error.

delete_contact ($jid, $cb)

This method will send a request to the server to delete this contact from the roster. It will result in cancelling all subscriptions.

$cb will be called when the request was finished. The first argument to the callback might be a Net::XMPP2::Error::IQ object if the request resulted in an error.

get_contact ($jid)

Returns the contact on the roster with the JID $jid. (If $jid is not bare the resource part will be stripped before searching)

The return value is an instance of Net::XMPP2::IM::Contact.

get_contacts

Returns the contacts that are on this roster as Net::XMPP2::IM::Contact objects.

NOTE: This method only returns the contacts that have a roster item. If you haven't retrieved the roster yet the presence information is still stored but you have to get the contacts without a roster item with the get_contacts_off_roster method. See below.

get_contacts_off_roster

Returns the contacts that are not on the roster but for which we have received presence. Return value is a list of Net::XMPP2::IM::Contact objects.

See also documentation of get_contacts method of Net::XMPP2::IM::Roster above.

subscribe ($jid)

This method sends a subscription request to $jid. If the optional $not_mutual paramenter is true the subscription will not be mutual.

debug_dump

This prints the roster and all it's contacts and their presences.

AUTHOR

Robin Redeker, <elmex at ta-sa.org>, JID: <elmex at jabber.org>

SEE ALSO

Net::XMPP2::IM::Connection, Net::XMPP2::IM::Contact, Net::XMPP2::IM::Presence

COPYRIGHT & LICENSE

Copyright 2007 Robin Redeker, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.