--- name: "AnyEvent::XMPP::IM::Connection" section: "3pm" platform: "linux" package: "perl-anyevent-xmpp" version: "0.55-7" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/AnyEvent::XMPP::IM::Connection" --- # AnyEvent::XMPP::IM::Connection(3pm) "XML" stream that implements the XMPP RFC 3921. ## NAME AnyEvent::XMPP::IM::Connection - "XML" stream that implements the XMPP RFC 3921. ## SYNOPSIS ``` use AnyEvent::XMPP::Connection; my $con = AnyEvent::XMPP::Connection->new; ``` ## DESCRIPTION This module represents a XMPP instant messaging connection and implements RFC 3921. This module is a subclass of `"AnyEvent::XMPP::Connection"` and inherits all methods. For example `"reg_cb"` and the stanza sending routines. For additional events that can be registered to look below in the EVENTS section. ## METHODS - **new (%args)** This is the constructor. It takes the same arguments as the constructor of AnyEvent::XMPP::Connection along with a few others: - 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 `"retrieve_roster"` method. The internal roster will be set even if this option is active, and even presences will be stored in there, except that the `"get_contacts"` method on the roster object won't return anything as there are no roster items. - initial\_presence =\> $priority This sets whether the initial presence should be sent. `$priority` should be the priority of the initial presence. The default value for the initial presence `$priority` is 10. If you pass a undefined value as `$priority` no initial presence will be sent! - **retrieve\_roster ($cb)** This method initiates a roster request. If you set `"dont_retrieve_roster"` when creating this connection no roster was retrieved. You can do that with this method. The coderef in `$cb` will be called after the roster was retrieved. The first argument of the callback in `$cb` will be the roster and the second will be a AnyEvent::XMPP::Error::IQ object when an error occurred while retrieving the roster. - **get\_roster** Returns the roster object of type AnyEvent::XMPP::IM::Roster. ## EVENTS These additional events can be registered on with `"reg_cb"`: In the following events `$roster` is the AnyEvent::XMPP::IM::Roster object you get by calling `"get_roster"`. 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. - session\_ready This event is generated when the session has been fully established and can be used to send around messages and other stuff. - session\_error =\> $error If an error happened during establishment of the session this event will be generated. `$error` will be an AnyEvent::XMPP::Error::IQ error object. - roster\_update =\> $roster, $contacts This event is emitted when a roster update has been received. `$contacts` 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 `"subscription"` method on it. The first time this event is sent is when the roster was received for the first time. - roster\_error =\> $error If an error happened during retrieval of the roster this event will be generated. `$error` will be an AnyEvent::XMPP::Error::IQ error object. - presence\_update =\> $roster, $contact, $old\_presence, $new\_presence This event is emitted when the presence of a contact has changed. `$contact` is the AnyEvent::XMPP::IM::Contact object which presence status has changed. `$old_presence` is a AnyEvent::XMPP::IM::Presence object which represents the presence prior to the change. `$new_presence` 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'. - presence\_error =\> $error This event is emitted when a presence stanza error was received. `$error` will be an AnyEvent::XMPP::Error::Presence error object. - message =\> $msg This event is emitted when a message was received. `$msg` is a AnyEvent::XMPP::IM::Message object. - message\_error =\> $error This event is emitted when a message stanza error was received. `$error` will be an AnyEvent::XMPP::Error::Message error object. - contact\_request\_subscribe =\> $roster, $contact, $message This event is generated when the `$contact` wants to subscribe to your presence. If you want to accept or decline the request, call `"send_subscribed"` method of AnyEvent::XMPP::IM::Contact or `"send_unsubscribed"` method of AnyEvent::XMPP::IM::Contact on `$contact`. If you want to start a mutual subscription you have to call `"send_subscribe"` **AFTER** you accepted or declined with `"send_subscribed"`/`"send_unsubscribed"`. Calling it in the opposite order gets some servers confused! If a `"status"` element was transmitted with the subscription it's contents will be in `$message`. Which is usually a text written from the one who requests subscription. - contact\_subscribed =\> $roster, $contact, $message This event is generated when `$contact` subscribed you to his presence successfully. If a `"status"` element was transmitted with the subscribed presence it's contents will be in `$message`. - contact\_did\_unsubscribe =\> $roster, $contact, $message This event is generated when `$contact` unsubscribes from your presence. If you want to unsubscribe from him call the `"send_unsubscribe"` method of AnyEvent::XMPP::IM::Contact on `$contact`. If a `"status"` element was transmitted with the unsubscription it's contents will be in `$message`. Which is usually a text written from the one who unsubscribes. - contact\_unsubscribed =\> $roster, $contact, $message This event is generated when `$contact` unsubscribed you from his presence. If you want to unsubscribe him from your presence call the `"send_unsubscribed"` method of AnyEvent::XMPP::IM::Contact on `$contact`. If a `"status"` element was transmitted with the unsubscription it's contents will be in `$message`. ## AUTHOR Robin Redeker, `""`, JID: `""` ## COPYRIGHT & LICENSE Copyright 2007, 2008 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.