-
-
01 Mar 2014 21:45:53 UTC
- Distribution: AnyEvent-XMPP
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository
- Issues (3)
- Testers (1078 / 0 / 0)
- Kwalitee
Bus factor: 1- 35.23% Coverage
- License: perl_5
- Activity
24 month- Tools
- Download (119.37KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 1 contributors-
Robin Redeker
- Dependencies
- unknown
- Reverse dependencies
- CPAN Testers List
- Dependency graph
- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
- new (%args)
- add_account ($jid, $password, $host, $port, $connection_args)
- start ()
- update_connections ()
- disconnect ($msg)
- remove_accounts ($reason)
- remove_account ($acc, $reason)
- set_accounts (%$accounts)
- send_message ($msg, $dest_jid, $src, $type)
- get_account ($jid)
- get_accounts ()
- get_connected_accounts ()
- find_account_for_dest_jid ($jid)
- get_contacts_for_jid ($jid)
- get_priority_presence_for_jid ($jid)
- set_presence ($show, $status, $priority)
- EVENTS
- AUTHOR
- COPYRIGHT & LICENSE
NAME
AnyEvent::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 theport
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 inadd_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 byadd_account
andget_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 insend_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 thestring ()
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.
Module Install Instructions
To install AnyEvent::XMPP, copy and paste the appropriate command in to your terminal.
cpanm AnyEvent::XMPP
perl -MCPAN -e shell install AnyEvent::XMPP
For more information on module installation, please visit the detailed CPAN module installation guide.