1AnyEvent::XMPP::Client(U3s)er Contributed Perl DocumentatAinoynEvent::XMPP::Client(3)
2
6 AnyEvent::XMPP::Client - XMPP Client abstraction
7
9 use AnyEvent::XMPP::Client;
10 use AnyEvent;
11 my $j = AnyEvent->condvar;
13 my $cl = AnyEvent::XMPP::Client->new;
15 $cl->start;
16 $j->wait;
18
20 This module tries to implement a straight forward and easy to use API
21 to communicate with XMPP entities. AnyEvent::XMPP::Client handles
22 connections and timeouts and all such stuff for you.
23 For more flexibility please have a look at AnyEvent::XMPP::Connection
25 and AnyEvent::XMPP::IM::Connection, they allow you to control what and
26 how something is being sent more precisely.
27
29 new (%args)
30 Following arguments can be passed in %args:
31 debug => 1
33 This will install callbacks which produce debugging output. This
34 will require XML::Twig to be installed (as it is used for pretty
35 printing the "XML" output).
36 add_account ($jid, $password, $host, $port, $connection_args)
38 This method adds a jabber account for connection with the JID $jid and
39 the password $password.
40 $host and $port can be undef and their default will be the domain of
42 the $jid and the default for the "port" parameter to the constructor of
43 AnyEvent::XMPP::Connection (look there for details about DNS-SRV
44 lookups).
45 $connection_args must either be undef or a hash reference to additional
47 arguments for the constructor of the AnyEvent::XMPP::IM::Connection
48 that will be used to connect the account.
49 Returns 1 on success and undef when the account already exists.
51 start ()
53 This method initiates the connections to the XMPP servers.
54 update_connections ()
56 This method tries to connect all unconnected accounts.
57 disconnect ($msg)
59 Disconnect all accounts.
60 remove_accounts ($reason)
62 Removes all accounts and disconnects. $reason should be some
63 descriptive reason why this account was removed (just for logging
64 purposes).
65 remove_account ($acc, $reason)
67 Removes and disconnects account $acc (which is a
68 AnyEvent::XMPP::IM::Account object). The reason for the removal can be
69 given via $reason.
70 set_accounts (%$accounts)
72 Sets the set of (to be connected) accounts. $accounts must be a hash
73 reference which contains the JIDs of the accounts as keys and the
74 values for $password, $domain, $port and $connection_args as described
75 in "add_account" above.
76 If the account is not yet connected it will be connected on the next
78 call to "update_connections" and if an account is connected that is not
79 in $accounts it will be disconnected.
80 send_message ($msg, $dest_jid, $src, $type)
82 Sends a message to the destination $dest_jid. $msg can either be a
83 string or a AnyEvent::XMPP::IM::Message object. If $msg is such an
84 object $dest_jid is optional, but will, when passed, override the
85 destination of the message.
86 NOTE: $dest_jid is transformed into a bare JID and the routing is done
88 by the conversation tracking mechanism which keeps track of which
89 resource should get the message.
90 $src is optional. It specifies which account to use to send the
92 message. If it is not passed AnyEvent::XMPP::Client will try to find an
93 account itself. First it will look through all rosters to find
94 $dest_jid and if none found it will pick any of the accounts that are
95 connected.
96 $src can either be a JID or a AnyEvent::XMPP::IM::Account object as
98 returned by "add_account" and "get_account".
99 $type is optional but overrides the type of the message object in $msg
101 if $msg is such an object.
102 $type should be 'chat' for normal chatter. If no $type is specified the
104 type of the message defaults to the value documented in
105 AnyEvent::XMPP::IM::Message (should be 'normal').
106 get_account ($jid)
108 Returns the AnyEvent::XMPP::IM::Account account object for the JID $jid
109 if there is any such account added. (returns undef otherwise).
110 get_accounts ()
112 Returns a list of AnyEvent::XMPP::IM::Accounts.
113 get_connected_accounts ()
115 Returns a list of connected AnyEvent::XMPP::IM::Accounts.
116 Same as:
118 grep { $_->is_connected } $client->get_accounts ();
120 find_account_for_dest_jid ($jid)
122 This method tries to find any account that has the contact $jid on his
123 roster. If no account with $jid on his roster was found it takes the
124 first one that is connected. (Return value is a
125 AnyEvent::XMPP::IM::Account object).
126 If no account is connected it returns undef.
128 get_contacts_for_jid ($jid)
130 This method returns all contacts that we are connected to. That means:
131 It joins the contact lists of all account's rosters that we are
132 connected to.
133 get_priority_presence_for_jid ($jid)
135 This method returns the presence for the contact $jid with the highest
136 priority.
137 If the contact $jid is on multiple account's rosters it's undefined
139 which roster the presence belongs to.
140 set_presence ($show, $status, $priority)
142 This sets the presence of all accounts. For a meaning of $show,
143 $status and $priority see the description of the %attrs hash in
144 "send_presence" method of AnyEvent::XMPP::Writer.
145
147 In the following event descriptions the argument $account is always a
148 AnyEvent::XMPP::IM::Account object.
149 All events from AnyEvent::XMPP::IM::Connection are forwarded to the
151 client, only that the first argument for every event is a $account
152 object.
153 Aside fom those, these events can be registered on with "reg_cb":
155 connected => $account
157 This event is sent when the $account was successfully connected.
158 connect_error => $account, $reason
160 This event is emitted when an error occured in the connection
161 process for the account $account.
162 error => $account, $error
164 This event is emitted when any error occured while communicating
165 over the connection to the $account - after a connection was
166 established.
167 $error is an error object which is derived from
169 AnyEvent::XMPP::Error. It will reveal human readable information
170 about the error by calling the "string ()" method (which returns a
171 descriptive error string about the nature of the error).
172 added_account => $account
174 Called whenever an account is added.
175 removed_account => $account
177 Called whenever an account is removed.
178
180 Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
181
183 Copyright 2007, 2008 Robin Redeker, all rights reserved.
184 This program is free software; you can redistribute it and/or modify it
186 under the same terms as Perl itself.
187perl v5.28.0 2012-12-25 AnyEvent::XMPP::Client(3)