1AnyEvent::XMPP::Client(U3s)er Contributed Perl DocumentatAinoynEvent::XMPP::Client(3)
2
3
4

NAME

6       AnyEvent::XMPP::Client - XMPP Client abstraction
7

SYNOPSIS

9          use AnyEvent::XMPP::Client;
10          use AnyEvent;
11
12          my $j = AnyEvent->condvar;
13
14          my $cl = AnyEvent::XMPP::Client->new;
15          $cl->start;
16
17          $j->wait;
18

DESCRIPTION

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
24       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

METHODS

29   new (%args)
30       Following arguments can be passed in %args:
31
32       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
37   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
41       $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
46       $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
50       Returns 1 on success and undef when the account already exists.
51
52   start ()
53       This method initiates the connections to the XMPP servers.
54
55   update_connections ()
56       This method tries to connect all unconnected accounts.
57
58   disconnect ($msg)
59       Disconnect all accounts.
60
61   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
66   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
71   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
77       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
81   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
87       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
91       $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
97       $src can either be a JID or a AnyEvent::XMPP::IM::Account object as
98       returned by "add_account" and "get_account".
99
100       $type is optional but overrides the type of the message object in $msg
101       if $msg is such an object.
102
103       $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
107   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
111   get_accounts ()
112       Returns a list of AnyEvent::XMPP::IM::Accounts.
113
114   get_connected_accounts ()
115       Returns a list of connected AnyEvent::XMPP::IM::Accounts.
116
117       Same as:
118
119         grep { $_->is_connected } $client->get_accounts ();
120
121   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
127       If no account is connected it returns undef.
128
129   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
134   get_priority_presence_for_jid ($jid)
135       This method returns the presence for the contact $jid with the highest
136       priority.
137
138       If the contact $jid is on multiple account's rosters it's undefined
139       which roster the presence belongs to.
140
141   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

EVENTS

147       In the following event descriptions the argument $account is always a
148       AnyEvent::XMPP::IM::Account object.
149
150       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
154       Aside fom those, these events can be registered on with "reg_cb":
155
156       connected => $account
157           This event is sent when the $account was successfully connected.
158
159       connect_error => $account, $reason
160           This event is emitted when an error occured in the connection
161           process for the account $account.
162
163       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
168           $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
173       added_account => $account
174           Called whenever an account is added.
175
176       removed_account => $account
177           Called whenever an account is removed.
178

AUTHOR

180       Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
181

183       Copyright 2007, 2008 Robin Redeker, all rights reserved.
184
185       This program is free software; you can redistribute it and/or modify it
186       under the same terms as Perl itself.
187
188
189
190perl v5.28.1                      2012-12-25         AnyEvent::XMPP::Client(3)
Impressum