NAME

Net::XMPP2::IM::Connection - "XML" stream that implements the XMPP RFC 3921.

SYNOPSIS

use Net::XMPP2::Connection;

my $con = Net::XMPP2::Connection->new;

DESCRIPTION

This module represents a XMPP instant messaging connection and implements RFC 3921.

This module is a subclass of Net::XMPP2::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 Net::XMPP2::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 Net::XMPP2::Error::IQ object when an error occured while retrieving the roster.

get_roster

Returns the roster object of type Net::XMPP2::IM::Roster.

EVENTS

These additional events can be registered on with reg_cb:

In the following events $roster is the Net::XMPP2::IM::Roster object you get by calling get_roster.

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 Net::XMPP2::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 Net::XMPP2::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 retrival of the roster this event will be generated. $error will be an Net::XMPP2::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 Net::XMPP2::IM::Contact object which presence status has changed. $old_presence is a Net::XMPP2::IM::Presence object which represents the presence prior to the change. $new_presence is a Net::XMPP2::IM::Presence object which represents the presence after to the change.

presence_error => $error

This event is emitted when a presence stanza error was received. $error will be an Net::XMPP2::Error::Presence error object.

message => $msg

This event is emitted when a message was received. $msg is a Net::XMPP2::IM::Message object.

message_error => $error

This event is emitted when a message stanza error was received. $error will be an Net::XMPP2::Error::Message error object.

contact_request_subscribe => $roster, $contact

This event is generated when the $contact wants to subscribe to your presence.

If any of the event callbacks for this event return a true value then the subscription request is accepted and a subscribed presence is sent. If all callbacks return a false value the subscription request is cancelled. If none of the callbacks return anything (all return an empty list) nothing of the former two things are done.

If you want to accept or decline the request later, call send_subscribed method of Net::XMPP2::IM::Contact or send_unsubscribed method of Net::XMPP2::IM::Contact on $contact.

contact_subscribed => $roster, $contact

This event is generated when $contact subscribed to your presence successfully.

contact_did_unsubscribe => $roster, $contact, $rdoit

This event is generated when $contact unsubscribes from your presence.

Returning a true value from any event callback will also unsubscribe you from the presence of the contact.

If you want to unsubscribe later from him call the send_unsubscribed method of Net::XMPP2::IM::Contact on $contact.

contact_unsubscribed => $roster, $contact

This event is generated when $contact unsubscribed you from his presence.

AUTHOR

Robin Redeker, <elmex at ta-sa.org>, JID: <elmex at jabber.org>

COPYRIGHT & LICENSE

Copyright 2007 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.