--- name: "AnyEvent::XMPP::Client" section: "3pm" platform: "linux" package: "perl-anyevent-xmpp" version: "0.55-7" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/AnyEvent::XMPP::Client" --- # AnyEvent::XMPP::Client(3pm) XMPP Client abstraction ## 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, `""`, JID: `""` ## 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.