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, "<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.