AnyEvent::XMPP::IM::CoUsertContributed Perl DAnyEvent::XMPP::IM::Connection(3)NAMEAnyEvent::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, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
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.
perl v5.14.1 2009-08-14 AnyEvent::XMPP::IM::Connection(3)
