Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
AnyEvent::XMPP::ClientUser Contributed Perl DocumentaAnyEvent::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;


       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.

   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

       $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

   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

       $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

       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.

       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

       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

	   $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.

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

       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.32.0			  2012-12-25	     AnyEvent::XMPP::Client(3)


Want to link to this manual page? Use this URL:

home | help