.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 .\" ======================================================================== .\" .IX Title "AnyEvent::XMPP::IM::Roster 3" .TH AnyEvent::XMPP::IM::Roster 3 2024-07-13 "perl v5.38.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 AnyEvent::XMPP::IM::Roster \- Instant messaging roster for XMPP .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 6 \& my $con = AnyEvent::XMPP::IM::Connection\->new (...); \& ... \& my $ro = $con\->roster; \& if (my $c = $ro\->get_contact (\*(Aqtest@example.com\*(Aq)) { \& $c\->make_message ()\->add_body ("Hello there!")\->send; \& } .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This module represents a class for roster objects which contain contact information. .PP It manages the roster of a JID connected by an AnyEvent::XMPP::IM::Connection. It manages also the presence information that is received. .PP You get the roster by calling the \f(CW\*(C`roster\*(C'\fR method on an AnyEvent::XMPP::IM::Connection object. There is no other way. .SH METHODS .IX Header "METHODS" .IP \fBis_retrieved\fR 4 .IX Item "is_retrieved" Returns true if this roster was fetched from the server or false if this roster hasn't been retrieved yet. .ie n .IP "\fBnew_contact ($jid, \fR\fB$name\fR\fB, \fR\fB$groups\fR\fB, \fR\fB$cb\fR\fB)\fR" 4 .el .IP "\fBnew_contact ($jid, \fR\f(CB$name\fR\fB, \fR\f(CB$groups\fR\fB, \fR\f(CB$cb\fR\fB)\fR" 4 .IX Item "new_contact ($jid, $name, $groups, $cb)" This method sends a roster item creation request to the server. \f(CW$jid\fR is the JID of the contact. \&\f(CW$name\fR is the nickname of the contact, which can be undef. \f(CW$groups\fR should be a array reference containing the groups this contact should be in. .Sp The callback in \f(CW$cb\fR will be called when the creation is finished. The first argument will be the \f(CW\*(C`AnyEvent::XMPP::IM::Contact\*(C'\fR object if no error occured. The second argument will be an AnyEvent::XMPP::Error::IQ object if the request resulted in an error. .Sp Please note that the contact you are given in that callback might not yet be on the roster (\f(CW\*(C`is_on_roster\*(C'\fR still returns a false value), if the server did send the roster push after the iq result of the roster set, so don't rely on the fact that the contact is on the roster. .ie n .IP "\fBdelete_contact ($jid, \fR\fB$cb\fR\fB)\fR" 4 .el .IP "\fBdelete_contact ($jid, \fR\f(CB$cb\fR\fB)\fR" 4 .IX Item "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. .Sp \&\f(CW$cb\fR will be called when the request was finished. The first argument to the callback might be a AnyEvent::XMPP::Error::IQ object if the request resulted in an error. .IP "\fBget_contact ($jid)\fR" 4 .IX Item "get_contact ($jid)" Returns the contact on the roster with the JID \f(CW$jid\fR. (If \f(CW$jid\fR is not bare the resource part will be stripped before searching) .Sp \&\fBNOTE:\fR This method will also return contacts that we have only presence for. To be sure the contact is on the users roster you need to call the \f(CW\*(C`is_on_roster\*(C'\fR method on the contact. .Sp The return value is an instance of AnyEvent::XMPP::IM::Contact. .IP \fBget_contacts\fR 4 .IX Item "get_contacts" Returns the contacts that are on this roster as AnyEvent::XMPP::IM::Contact objects. .Sp 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 \&\f(CW\*(C`get_contacts_off_roster\*(C'\fR method. See below. .IP \fBget_contacts_off_roster\fR 4 .IX Item "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 AnyEvent::XMPP::IM::Contact objects. .Sp See also documentation of \f(CW\*(C`get_contacts\*(C'\fR method of AnyEvent::XMPP::IM::Roster above. .IP \fBget_own_contact\fR 4 .IX Item "get_own_contact" This method returns a AnyEvent::XMPP::IM::Contact object which stands for ourself. It will be used to keep track of our own presences. .IP \fBdebug_dump\fR 4 .IX Item "debug_dump" This prints the roster and all it's contacts and their presences. .SH AUTHOR .IX Header "AUTHOR" Robin Redeker, \f(CW\*(C`\*(C'\fR, JID: \f(CW\*(C`\*(C'\fR .SH "SEE ALSO" .IX Header "SEE ALSO" AnyEvent::XMPP::IM::Connection, AnyEvent::XMPP::IM::Contact, AnyEvent::XMPP::IM::Presence .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2007, 2008 Robin Redeker, all rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.