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:
%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.
$jid
$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).
$host
$port
port
$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.
$connection_args
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).
$reason
Removes and disconnects account $acc (which is a AnyEvent::XMPP::IM::Account object). The reason for the removal can be given via $reason.
$acc
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.
$accounts
$domain
add_account
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.
update_connections
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.
$dest_jid
$msg
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
$src can either be a JID or a AnyEvent::XMPP::IM::Account object as returned by add_account and get_account.
get_account
$type is optional but overrides the type of the message object in $msg if $msg is such an object.
$type
$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.
$show
$status
$priority
%attrs
send_presence
In the following event descriptions the argument $account is always a AnyEvent::XMPP::IM::Account object.
$account
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:
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).
$error
string ()
Called whenever an account is added.
Called whenever an account is removed.
Robin Redeker, <elmex at ta-sa.org>, JID: <elmex at jabber.org>
<elmex at ta-sa.org>
<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.
To install AnyEvent::XMPP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm AnyEvent::XMPP
CPAN shell
perl -MCPAN -e shell install AnyEvent::XMPP
For more information on module installation, please visit the detailed CPAN module installation guide.