.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 turned on, 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 3pm" .TH AnyEvent::XMPP::Client 3pm "2016-09-03" "perl v5.22.2" "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 \s-1API\s0 to communicate with \s-1XMPP\s0 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 \*(L"\s-1XML\*(R"\s0 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 \s-1JID \s0\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 \s-1XMPP\s0 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 \&\s-1NOTE: \s0\f(CW$dest_jid\fR is transformed into a bare \s-1JID\s0 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 \s-1JID\s0 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 \s-1JID \s0\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, \s-1JID: \s0\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.