Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  NET::XMPP2::CLIENT (3)

.ds Aq ’


Net::XMPP2::Client - XMPP Client abstraction



   use Net::XMPP2::Client;
   use AnyEvent;

   my $j = AnyEvent->condvar;

   my $cl = Net::XMPP2::Client->new;



This module tries to implement a straight forward and easy to use API to communicate with XMPP entities. Net::XMPP2::Client handles connections and timeouts and all such stuff for you.

For more flexibility please have a look at Net::XMPP2::Connection and Net::XMPP2::IM::Connection, they allow you to control what and how something is being sent more precisely.


    new (%args)

Following arguments can be passed in %args:

add_account ($jid, CW$password, CW$host, CW$port, CW$connection_args)

This method adds a jabber account for connection with the JID $jid and the password $password.

$host and $port are optional and can be undef. $host overrides the host in the $jid.

$connection_args must either be undef or a hashreference to additional arguments for the constructor of the Net::XMPP2::IM::Connection that will be used to connect the account.

Returns 1 on success and undef when the account already exists.

    start ()

This method initiates the connections to the XMPP servers.

    update_connections ()

This method tries to connect all unconnected accounts.

    disconnect ($msg)

Disconnect all accounts.

    remove_accounts ($msg)

Removes all accounts and disconnects.

remove_account ($acc, CW$reason)

Removes and disconnects account $acc (which is a Net::XMPP2::IM::Account object). The reason for the removal can be given via $reason.

send_message ($msg, CW$dest_jid, CW$src, CW$type)

Sends a message to the destination $dest_jid. $msg can either be a string or a Net::XMPP2::IM::Message object. If $msg is such an object $dest_jid is optional, but will, when passed, override the destination of the message.

NOTE: $dest_jid is transformed into a bare JID and the routing is done by the conversation tracking mechanism which keeps track of which resource should get the message.

$src is optional. It specifies which account to use to send the message. If it is not passed Net::XMPP2::Client will try to find an account itself. First it will look through all rosters to find $dest_jid and if none found it will pick any of the accounts that are connected.

$src can either be a JID or a Net::XMPP2::IM::Account object as returned by add_account and get_account.

$type is optional but overrides the type of the message object in $msg if $msg is such an object.

$type should be ’chat’ for normal chatter. If no $type is specified the type of the message defaults to the value documented in Net::XMPP2::IM::Message (should be ’normal’).

    get_account ($jid)

Returns the Net::XMPP2::IM::Account account object for the JID $jid if there is any such account added. (returns undef otherwise).

    get_accounts ()

Returns a list of Net::XMPP2::IM::Accounts.

    get_connected_accounts ()

Returns a list of connected Net::XMPP2::IM::Accounts.

Same as:

  grep { $_->is_connected } $client->get_accounts ();

    find_account_for_dest_jid ($jid)

This method tries to find any account that has the contact $jid on his roster. If no account with $jid on his roster was found it takes the first one that is connected. (Return value is a Net::XMPP2::IM::Account object).

If no account is connected it returns undef.

    get_contacts_for_jid ($jid)

This method returns all contacts that we are connected to. That means: It joins the contact lists of all account’s rosters that we are connected to.

    get_priority_presence_for_jid ($jid)

This method returns the presence for the contact $jid with the highest priority.

If the contact $jid is on multiple account’s rosters it’s undefined which roster the presence belongs to.

set_presence ($show, CW$status, CW$priority)

This sets the presence of all accounts. For a meaning of $show, $status and $priority see the description of the %attrs hash in send_presence method of Net::XMPP2::Writer.


In the following event descriptions the argument $account is always a Net::XMPP2::IM::Account object.

All events from Net::XMPP2::IM::Connection are forwarded to the client, only that the first argument for every event is a $account object.

Aside fom those, these events can be registered on with reg_cb:
connected => $account This event is sent when the $account was successfully connected.
connect_error => $account, $reason This event is emitted when an error occured in the connection process for the account $account.
error => $account, $error This event is emitted when any error occured while communicating over the connection to the $account - after a connection was established.

$error is an error object which is derived from Net::XMPP2::Error. It will reveal human readable information about the error by calling the string () method (which returns a descriptive error string about the nature of the error).


Robin Redeker, <elmex at>, JID: <elmex at>


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.

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 NET::XMPP2::CLIENT (3) 2008-04-15

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.