AnyEvent::XMPP::Client(3) User Contributed Perl Documentation AnyEvent::XMPP::Client(3)

AnyEvent::XMPP::Client - XMPP Client abstraction

use AnyEvent::XMPP::Client;
use AnyEvent;
my $j = AnyEvent->condvar;
my $cl = AnyEvent::XMPP::Client->new;
$cl->start;
$j->wait;

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

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

Following arguments can be passed in %args:

This will install callbacks which produce debugging output. This will require XML::Twig to be installed (as it is used for pretty printing the "XML" output).

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

$host and $port can be undef and their default will be the domain of the $jid and the default for the "port" parameter to the constructor of AnyEvent::XMPP::Connection (look there for details about DNS-SRV lookups).

$connection_args must either be undef or a hash reference to additional arguments for the constructor of the AnyEvent::XMPP::IM::Connection that will be used to connect the account.

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

This method initiates the connections to the XMPP servers.

This method tries to connect all unconnected accounts.

Disconnect all accounts.

Removes all accounts and disconnects. $reason should be some descriptive reason why this account was removed (just for logging purposes).

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

Sets the set of (to be connected) accounts. $accounts must be a hash reference which contains the JIDs of the accounts as keys and the values for $password, $domain, $port and $connection_args as described in "add_account" above.

If the account is not yet connected it will be connected on the next call to "update_connections" and if an account is connected that is not in $accounts it will be disconnected.

Sends a message to the destination $dest_jid. $msg can either be a string or a AnyEvent::XMPP::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 AnyEvent::XMPP::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 AnyEvent::XMPP::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 AnyEvent::XMPP::IM::Message (should be 'normal').

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

Returns a list of AnyEvent::XMPP::IM::Accounts.

Returns a list of connected AnyEvent::XMPP::IM::Accounts.

Same as:

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

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 AnyEvent::XMPP::IM::Account object).

If no account is connected it returns undef.

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.

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.

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 AnyEvent::XMPP::Writer.

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

All events from AnyEvent::XMPP::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":

This event is sent when the $account was successfully connected.
This event is emitted when an error occured in the connection process for the account $account.
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 AnyEvent::XMPP::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).

Called whenever an account is added.
Called whenever an account is removed.

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.

2024-07-13 perl v5.38.2