AnyEvent::XMPP::ClientUser Contributed Perl DocumentaAnyEvent::XMPP::Client(3)NAMEAnyEvent::XMPP::Client - XMPP Client abstraction
SYNOPSIS
use AnyEvent::XMPP::Client;
use AnyEvent;
my $j = AnyEvent->condvar;
my $cl = AnyEvent::XMPP::Client->new;
$cl->start;
$j->wait;
DESCRIPTION
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.
METHODS
new (%args)
Following arguments can be passed in %args:
debug => 1
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).
add_account ($jid, $password, $host, $port, $connection_args)
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.
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 ($reason)
Removes all accounts and disconnects. $reason should be some
descriptive reason why this account was removed (just for logging
purposes).
remove_account ($acc, $reason)
Removes and disconnects account $acc (which is a
AnyEvent::XMPP::IM::Account object). The reason for the removal can be
given via $reason.
set_accounts (%$accounts)
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.
send_message ($msg, $dest_jid, $src, $type)
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').
get_account ($jid)
Returns the AnyEvent::XMPP::IM::Account account object for the JID $jid
if there is any such account added. (returns undef otherwise).
get_accounts ()
Returns a list of AnyEvent::XMPP::IM::Accounts.
get_connected_accounts ()
Returns a list of connected AnyEvent::XMPP::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
AnyEvent::XMPP::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, $status, $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 AnyEvent::XMPP::Writer.
EVENTS
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":
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
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).
added_account => $account
Called whenever an account is added.
removed_account => $account
Called whenever an account is removed.
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.
perl v5.14.1 2009-08-14 AnyEvent::XMPP::Client(3)
