.\" -*- 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::Connection 3" .TH AnyEvent::XMPP::IM::Connection 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::Connection \- "XML" stream that implements the XMPP RFC 3921. .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use AnyEvent::XMPP::Connection; \& \& my $con = AnyEvent::XMPP::Connection\->new; .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This module represents a XMPP instant messaging connection and implements RFC 3921. .PP This module is a subclass of \f(CW\*(C`AnyEvent::XMPP::Connection\*(C'\fR and inherits all methods. For example \f(CW\*(C`reg_cb\*(C'\fR and the stanza sending routines. .PP For additional events that can be registered to look below in the EVENTS section. .SH METHODS .IX Header "METHODS" .IP "\fBnew (%args)\fR" 4 .IX Item "new (%args)" This is the constructor. It takes the same arguments as the constructor of AnyEvent::XMPP::Connection along with a few others: .RS 4 .ie n .IP "dont_retrieve_roster => $bool" 4 .el .IP "dont_retrieve_roster => \f(CW$bool\fR" 4 .IX Item "dont_retrieve_roster => $bool" Set this to a true value if no roster should be requested on connection establishment. You can retrieve the roster later if you want to with the \f(CW\*(C`retrieve_roster\*(C'\fR method. .Sp The internal roster will be set even if this option is active, and even presences will be stored in there, except that the \f(CW\*(C`get_contacts\*(C'\fR method on the roster object won't return anything as there are no roster items. .ie n .IP "initial_presence => $priority" 4 .el .IP "initial_presence => \f(CW$priority\fR" 4 .IX Item "initial_presence => $priority" This sets whether the initial presence should be sent. \f(CW$priority\fR should be the priority of the initial presence. The default value for the initial presence \f(CW$priority\fR is 10. .Sp If you pass a undefined value as \f(CW$priority\fR no initial presence will be sent! .RE .RS 4 .RE .IP "\fBretrieve_roster ($cb)\fR" 4 .IX Item "retrieve_roster ($cb)" This method initiates a roster request. If you set \f(CW\*(C`dont_retrieve_roster\*(C'\fR when creating this connection no roster was retrieved. You can do that with this method. The coderef in \f(CW$cb\fR will be called after the roster was retrieved. .Sp The first argument of the callback in \f(CW$cb\fR will be the roster and the second will be a AnyEvent::XMPP::Error::IQ object when an error occurred while retrieving the roster. .IP \fBget_roster\fR 4 .IX Item "get_roster" Returns the roster object of type AnyEvent::XMPP::IM::Roster. .SH EVENTS .IX Header "EVENTS" These additional events can be registered on with \f(CW\*(C`reg_cb\*(C'\fR: .PP In the following events \f(CW$roster\fR is the AnyEvent::XMPP::IM::Roster object you get by calling \f(CW\*(C`get_roster\*(C'\fR. .PP NODE: The first argument to each callback is always the AnyEvent::XMPP::IM::Connection object itself. Also see Object::Event for more information about registering callbacks. .IP session_ready 4 .IX Item "session_ready" This event is generated when the session has been fully established and can be used to send around messages and other stuff. .ie n .IP "session_error => $error" 4 .el .IP "session_error => \f(CW$error\fR" 4 .IX Item "session_error => $error" If an error happened during establishment of the session this event will be generated. \f(CW$error\fR will be an AnyEvent::XMPP::Error::IQ error object. .ie n .IP "roster_update => $roster, $contacts" 4 .el .IP "roster_update => \f(CW$roster\fR, \f(CW$contacts\fR" 4 .IX Item "roster_update => $roster, $contacts" This event is emitted when a roster update has been received. \&\f(CW$contacts\fR is an array reference of AnyEvent::XMPP::IM::Contact objects which have changed. If a contact was removed it will return 'remove' when you call the \f(CW\*(C`subscription\*(C'\fR method on it. .Sp The first time this event is sent is when the roster was received for the first time. .ie n .IP "roster_error => $error" 4 .el .IP "roster_error => \f(CW$error\fR" 4 .IX Item "roster_error => $error" If an error happened during retrieval of the roster this event will be generated. \&\f(CW$error\fR will be an AnyEvent::XMPP::Error::IQ error object. .ie n .IP "presence_update => $roster, $contact, $old_presence, $new_presence" 4 .el .IP "presence_update => \f(CW$roster\fR, \f(CW$contact\fR, \f(CW$old_presence\fR, \f(CW$new_presence\fR" 4 .IX Item "presence_update => $roster, $contact, $old_presence, $new_presence" This event is emitted when the presence of a contact has changed. \&\f(CW$contact\fR is the AnyEvent::XMPP::IM::Contact object which presence status has changed. \&\f(CW$old_presence\fR is a AnyEvent::XMPP::IM::Presence object which represents the presence prior to the change. \&\f(CW$new_presence\fR is a AnyEvent::XMPP::IM::Presence object which represents the presence after to the change. The new presence might be undef if the new presence is 'unavailable'. .ie n .IP "presence_error => $error" 4 .el .IP "presence_error => \f(CW$error\fR" 4 .IX Item "presence_error => $error" This event is emitted when a presence stanza error was received. \&\f(CW$error\fR will be an AnyEvent::XMPP::Error::Presence error object. .ie n .IP "message => $msg" 4 .el .IP "message => \f(CW$msg\fR" 4 .IX Item "message => $msg" This event is emitted when a message was received. \&\f(CW$msg\fR is a AnyEvent::XMPP::IM::Message object. .ie n .IP "message_error => $error" 4 .el .IP "message_error => \f(CW$error\fR" 4 .IX Item "message_error => $error" This event is emitted when a message stanza error was received. \&\f(CW$error\fR will be an AnyEvent::XMPP::Error::Message error object. .ie n .IP "contact_request_subscribe => $roster, $contact, $message" 4 .el .IP "contact_request_subscribe => \f(CW$roster\fR, \f(CW$contact\fR, \f(CW$message\fR" 4 .IX Item "contact_request_subscribe => $roster, $contact, $message" This event is generated when the \f(CW$contact\fR wants to subscribe to your presence. .Sp If you want to accept or decline the request, call \&\f(CW\*(C`send_subscribed\*(C'\fR method of AnyEvent::XMPP::IM::Contact or \&\f(CW\*(C`send_unsubscribed\*(C'\fR method of AnyEvent::XMPP::IM::Contact on \f(CW$contact\fR. .Sp If you want to start a mutual subscription you have to call \f(CW\*(C`send_subscribe\*(C'\fR \&\fBAFTER\fR you accepted or declined with \f(CW\*(C`send_subscribed\*(C'\fR/\f(CW\*(C`send_unsubscribed\*(C'\fR. Calling it in the opposite order gets some servers confused! .Sp If a \f(CW\*(C`status\*(C'\fR element was transmitted with the subscription it's contents will be in \f(CW$message\fR. Which is usually a text written from the one who requests subscription. .ie n .IP "contact_subscribed => $roster, $contact, $message" 4 .el .IP "contact_subscribed => \f(CW$roster\fR, \f(CW$contact\fR, \f(CW$message\fR" 4 .IX Item "contact_subscribed => $roster, $contact, $message" This event is generated when \f(CW$contact\fR subscribed you to his presence successfully. .Sp If a \f(CW\*(C`status\*(C'\fR element was transmitted with the subscribed presence it's contents will be in \f(CW$message\fR. .ie n .IP "contact_did_unsubscribe => $roster, $contact, $message" 4 .el .IP "contact_did_unsubscribe => \f(CW$roster\fR, \f(CW$contact\fR, \f(CW$message\fR" 4 .IX Item "contact_did_unsubscribe => $roster, $contact, $message" This event is generated when \f(CW$contact\fR unsubscribes from your presence. .Sp If you want to unsubscribe from him call the \f(CW\*(C`send_unsubscribe\*(C'\fR method of AnyEvent::XMPP::IM::Contact on \f(CW$contact\fR. .Sp If a \f(CW\*(C`status\*(C'\fR element was transmitted with the unsubscription it's contents will be in \f(CW$message\fR. Which is usually a text written from the one who unsubscribes. .ie n .IP "contact_unsubscribed => $roster, $contact, $message" 4 .el .IP "contact_unsubscribed => \f(CW$roster\fR, \f(CW$contact\fR, \f(CW$message\fR" 4 .IX Item "contact_unsubscribed => $roster, $contact, $message" This event is generated when \f(CW$contact\fR unsubscribed you from his presence. .Sp If you want to unsubscribe him from your presence call the \f(CW\*(C`send_unsubscribed\*(C'\fR method of AnyEvent::XMPP::IM::Contact on \f(CW$contact\fR. .Sp If a \f(CW\*(C`status\*(C'\fR element was transmitted with the unsubscription it's contents will be in \f(CW$message\fR. .SH AUTHOR .IX Header "AUTHOR" Robin Redeker, \f(CW\*(C`\*(C'\fR, JID: \f(CW\*(C`\*(C'\fR .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.