.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "AnyEvent::XMPP::Client 3" .TH AnyEvent::XMPP::Client 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME AnyEvent::XMPP::Client \- XMPP Client abstraction .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 2 \& use AnyEvent::XMPP::Client; \& use AnyEvent; \& \& my $j = AnyEvent\->condvar; \& \& my $cl = AnyEvent::XMPP::Client\->new; \& $cl\->start; \& \& $j\->wait; .Ve .SH DESCRIPTION .IX Header "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. .PP 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. .SH METHODS .IX Header "METHODS" .SS "new (%args)" .IX Subsection "new (%args)" Following arguments can be passed in \f(CW%args\fR: .IP "debug => 1" 4 .IX Item "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). .ie n .SS "add_account ($jid, $password, $host, $port, $connection_args)" .el .SS "add_account ($jid, \f(CW$password\fP, \f(CW$host\fP, \f(CW$port\fP, \f(CW$connection_args\fP)" .IX Subsection "add_account ($jid, $password, $host, $port, $connection_args)" This method adds a jabber account for connection with the JID \f(CW$jid\fR and the password \f(CW$password\fR. .PP \&\f(CW$host\fR and \f(CW$port\fR can be undef and their default will be the domain of the \&\f(CW$jid\fR and the default for the \f(CW\*(C`port\*(C'\fR parameter to the constructor of AnyEvent::XMPP::Connection (look there for details about DNS-SRV lookups). .PP \&\f(CW$connection_args\fR 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. .PP Returns 1 on success and undef when the account already exists. .SS "start ()" .IX Subsection "start ()" This method initiates the connections to the XMPP servers. .SS "update_connections ()" .IX Subsection "update_connections ()" This method tries to connect all unconnected accounts. .SS "disconnect ($msg)" .IX Subsection "disconnect ($msg)" Disconnect all accounts. .SS "remove_accounts ($reason)" .IX Subsection "remove_accounts ($reason)" Removes all accounts and disconnects. \f(CW$reason\fR should be some descriptive reason why this account was removed (just for logging purposes). .ie n .SS "remove_account ($acc, $reason)" .el .SS "remove_account ($acc, \f(CW$reason\fP)" .IX Subsection "remove_account ($acc, $reason)" Removes and disconnects account \f(CW$acc\fR (which is a AnyEvent::XMPP::IM::Account object). The reason for the removal can be given via \f(CW$reason\fR. .SS "set_accounts (%$accounts)" .IX Subsection "set_accounts (%$accounts)" Sets the set of (to be connected) accounts. \f(CW$accounts\fR must be a hash reference which contains the JIDs of the accounts as keys and the values for \&\f(CW$password\fR, \f(CW$domain\fR, \f(CW$port\fR and \f(CW$connection_args\fR as described in \&\f(CW\*(C`add_account\*(C'\fR above. .PP If the account is not yet connected it will be connected on the next call to \&\f(CW\*(C`update_connections\*(C'\fR and if an account is connected that is not in \&\f(CW$accounts\fR it will be disconnected. .ie n .SS "send_message ($msg, $dest_jid, $src, $type)" .el .SS "send_message ($msg, \f(CW$dest_jid\fP, \f(CW$src\fP, \f(CW$type\fP)" .IX Subsection "send_message ($msg, $dest_jid, $src, $type)" Sends a message to the destination \f(CW$dest_jid\fR. \&\f(CW$msg\fR can either be a string or a AnyEvent::XMPP::IM::Message object. If \f(CW$msg\fR is such an object \f(CW$dest_jid\fR is optional, but will, when passed, override the destination of the message. .PP NOTE: \f(CW$dest_jid\fR 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. .PP \&\f(CW$src\fR 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 \f(CW$dest_jid\fR and if none found it will pick any of the accounts that are connected. .PP \&\f(CW$src\fR can either be a JID or a AnyEvent::XMPP::IM::Account object as returned by \f(CW\*(C`add_account\*(C'\fR and \f(CW\*(C`get_account\*(C'\fR. .PP \&\f(CW$type\fR is optional but overrides the type of the message object in \f(CW$msg\fR if \f(CW$msg\fR is such an object. .PP \&\f(CW$type\fR should be 'chat' for normal chatter. If no \f(CW$type\fR is specified the type of the message defaults to the value documented in AnyEvent::XMPP::IM::Message (should be 'normal'). .SS "get_account ($jid)" .IX Subsection "get_account ($jid)" Returns the AnyEvent::XMPP::IM::Account account object for the JID \f(CW$jid\fR if there is any such account added. (returns undef otherwise). .SS "get_accounts ()" .IX Subsection "get_accounts ()" Returns a list of AnyEvent::XMPP::IM::Accounts. .SS "get_connected_accounts ()" .IX Subsection "get_connected_accounts ()" Returns a list of connected AnyEvent::XMPP::IM::Accounts. .PP Same as: .PP .Vb 1 \& grep { $_\->is_connected } $client\->get_accounts (); .Ve .SS "find_account_for_dest_jid ($jid)" .IX Subsection "find_account_for_dest_jid ($jid)" This method tries to find any account that has the contact \f(CW$jid\fR on his roster. If no account with \f(CW$jid\fR on his roster was found it takes the first one that is connected. (Return value is a AnyEvent::XMPP::IM::Account object). .PP If no account is connected it returns undef. .SS "get_contacts_for_jid ($jid)" .IX Subsection "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. .SS "get_priority_presence_for_jid ($jid)" .IX Subsection "get_priority_presence_for_jid ($jid)" This method returns the presence for the contact \f(CW$jid\fR with the highest priority. .PP If the contact \f(CW$jid\fR is on multiple account's rosters it's undefined which roster the presence belongs to. .ie n .SS "set_presence ($show, $status, $priority)" .el .SS "set_presence ($show, \f(CW$status\fP, \f(CW$priority\fP)" .IX Subsection "set_presence ($show, $status, $priority)" This sets the presence of all accounts. For a meaning of \f(CW$show\fR, \f(CW$status\fR and \f(CW$priority\fR see the description of the \f(CW%attrs\fR hash in \&\f(CW\*(C`send_presence\*(C'\fR method of AnyEvent::XMPP::Writer. .SH EVENTS .IX Header "EVENTS" In the following event descriptions the argument \f(CW$account\fR is always a AnyEvent::XMPP::IM::Account object. .PP All events from AnyEvent::XMPP::IM::Connection are forwarded to the client, only that the first argument for every event is a \f(CW$account\fR object. .PP Aside fom those, these events can be registered on with \f(CW\*(C`reg_cb\*(C'\fR: .ie n .IP "connected => $account" 4 .el .IP "connected => \f(CW$account\fR" 4 .IX Item "connected => $account" This event is sent when the \f(CW$account\fR was successfully connected. .ie n .IP "connect_error => $account, $reason" 4 .el .IP "connect_error => \f(CW$account\fR, \f(CW$reason\fR" 4 .IX Item "connect_error => $account, $reason" This event is emitted when an error occured in the connection process for the account \f(CW$account\fR. .ie n .IP "error => $account, $error" 4 .el .IP "error => \f(CW$account\fR, \f(CW$error\fR" 4 .IX Item "error => $account, $error" This event is emitted when any error occured while communicating over the connection to the \f(CW$account\fR \- after a connection was established. .Sp \&\f(CW$error\fR is an error object which is derived from AnyEvent::XMPP::Error. It will reveal human readable information about the error by calling the \f(CW\*(C`string ()\*(C'\fR method (which returns a descriptive error string about the nature of the error). .ie n .IP "added_account => $account" 4 .el .IP "added_account => \f(CW$account\fR" 4 .IX Item "added_account => $account" Called whenever an account is added. .ie n .IP "removed_account => $account" 4 .el .IP "removed_account => \f(CW$account\fR" 4 .IX Item "removed_account => $account" Called whenever an account is removed. .SH AUTHOR .IX Header "AUTHOR" Robin Redeker, \f(CW\*(C`\*(C'\fR, JID: \f(CW\*(C`\*(C'\fR .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2007, 2008 Robin Redeker, all rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.