AnyEvent::XMPP::IM::Connection - "XML" stream that
implements the XMPP RFC 3921.
use AnyEvent::XMPP::Connection;
my $con = AnyEvent::XMPP::Connection->new;
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.
- 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.
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.
Robin Redeker, "<elmex at
ta-sa.org>", JID: "<elmex at
jabber.org>"
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.