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  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.36.0                                       2022-12-06                        AnyEvent::XMPP::Client(3pm)