1AnyEvent::XMPP::ConnectUisoenr(3C)ontributed Perl DocumeAnntyaEtvieonnt::XMPP::Connection(3)
2
6 AnyEvent::XMPP::Connection - XML stream that implements the XMPP RFC
7 3920.
8
10 use AnyEvent::XMPP::Connection;
11 my $con =
13 AnyEvent::XMPP::Connection->new (
14 username => "abc",
15 domain => "jabber.org",
16 resource => "AnyEvent::XMPP"
17 );
18 $con->reg_cb (stream_ready => sub { print "XMPP stream ready!\n" });
20 $con->connect; # will do non-blocking connect
21
23 This module represents a XMPP stream as described in RFC 3920. You can
24 issue the basic XMPP XML stanzas with methods like "send_iq",
25 "send_message" and "send_presence".
26 And receive events with the "reg_cb" event framework from the
28 connection.
29 If you need instant messaging stuff please take a look at
31 "AnyEvent::XMPP::IM::Connection".
32
34 new (%args)
35 Following arguments can be passed in %args:
36 language => $tag
38 This should be the language of the human readable contents that
39 will be transmitted over the stream. The default will be 'en'.
40 Please look in RFC 3066 how $tag should look like.
42 jid => $jid
44 This can be used to set the settings "username", "domain" (and
45 optionally "resource") from a $jid.
46 username => $username
48 This is your $username (the userpart in the JID);
49 Note: You have to take care that the stringprep profile for
51 nodes can be applied at: $username. Otherwise the server might
52 signal an error. See AnyEvent::XMPP::Util for utility functions
53 to check this.
54 NOTE: This field has no effect if "jid" is given!
56 domain => $domain
58 If you didn't provide a "jid" (see above) you have to set the
59 "username" which you want to connect as (see above) and the
60 $domain to connect to.
61 NOTE: This field has no effect if "jid" is given!
63 resource => $resource
65 If this argument is given $resource will be passed as desired
66 resource on resource binding.
67 Note: You have to take care that the stringprep profile for
69 resources can be applied at: $resource. Otherwise the server
70 might signal an error. See AnyEvent::XMPP::Util for utility
71 functions to check this.
72 host => $host
74 This parameter specifies the hostname where we are going to
75 connect to. The default for this is the "domain" of the "jid".
76 NOTE: To disable DNS SRV lookup you need to specify the port
78 number yourself. See "port" below.
79 use_host_as_sasl_hostname => $bool
81 This is a special parameter for people who might want to use
82 GSSAPI SASL mechanism. It will cause the value of the "host"
83 parameter (see above) to be passed to the SASL mechanisms,
84 instead of the "domain" of the JID.
85 This flag is provided until support for XEP 0233 is deployed,
87 which will fix the hostname issue w.r.t. GSSAPI SASL.
88 port => $port
90 This is optional, the default value for $port is
91 'xmpp-client=5222', which will used as $service argument to
92 "tcp_connect" of AnyEvent::Socket. NOTE: If you specify the
93 port number here (instead of 'xmpp-client=5222'), no DNS SRV
94 lookup will be done when connecting.
95 connect_timeout => $timeout
97 This sets the connection timeout. If the socket connect takes
98 too long a "disconnect" event will be generated with an
99 appropriate error message. If this argument is not given no
100 timeout is installed for the connects.
101 password => $password
103 This is the password for the "username" above.
104 disable_ssl => $bool
106 If $bool is true no SSL will be used.
107 old_style_ssl => $bool
109 If $bool is true the TLS handshake will be initiated when the
110 TCP connection was established. This is useful if you have to
111 connect to an old Jabber server, with old-style SSL connections
112 on port 5223.
113 But that practice has been discouraged in XMPP, and a TLS
115 handshake is done after the XML stream has been established.
116 Only use this option if you know what you are doing.
117 disable_sasl => $bool
119 If $bool is true SASL will NOT be used to authenticate with the
120 server, even if it advertises SASL through stream features.
121 Alternative authentication methods will be used, such as IQ
122 Auth (XEP-0078) if the server offers it.
123 disable_iq_auth => $bool
125 This disables the use of IQ Auth (XEP-0078) for authentication,
126 you might want to exclude it because it's deprecated and
127 insecure. (However, I want to reach a maximum in compatibility
128 with AnyEvent::XMPP so I'm not disabling this by default.
129 See also "disable_old_jabber_authentication" below.
131 anal_iq_auth => $bool
133 This enables the anal iq auth mechanism that will first look in
134 the stream features before trying to start iq authentication.
135 Yes, servers don't always advertise what they can. I only
136 implemented this option for my test suite.
137 disable_old_jabber_authentication => $bool
139 If $bool is a true value, then the VERY old style
140 authentication method with VERY old jabber server won't be used
141 when a <stream> start tag from the server without version
142 attribute is received.
143 The VERY old style authentication method is per default enabled
145 to ensure maximum compatibility with old jabber
146 implementations. The old method works as follows: When a
147 <stream> start tag is received from the server with no
148 'version' attribute IQ Auth (XEP-0078) will be initiated to
149 authenticate with the server.
150 Please note that the old authentication method will fail if
152 "disable_iq_auth" is true.
153 stream_version_override => $version
155 NOTE: Only use if you really know what you are doing!
156 This will override the stream version which is sent in the XMPP
158 stream initiation element. This is currently only used by the
159 tests which set $version to '0.9' for testing IQ authentication
160 with ejabberd.
161 whitespace_ping_interval => $interval
163 This will set the whitespace ping interval (in seconds). The
164 default interval are 60 seconds. You can disable the
165 whitespace ping by setting $interval to 0.
166 connect ()
168 Try to connect (non blocking) to the domain and port passed in
169 "new".
170 The connection is performed non blocking, so this method will just
172 trigger the connection process. The event "connect" will be emitted
173 when the connection was successfully established.
174 If the connection try was not successful a "disconnect" event will
176 be generated with an error message.
177 NOTE: Please note that you can't reconnect a
179 AnyEvent::XMPP::Connection object. You need to recreate it if you
180 want to reconnect.
181 NOTE: The "XML" stream initiation is sent when the connection was
183 successfully connected.
184 is_connected ()
186 Returns true if the connection is still connected and stanzas can
187 be sent.
188 set_default_iq_timeout ($seconds)
190 This sets the default timeout for IQ requests. If the timeout runs
191 out the request will be aborted and the callback called with a
192 AnyEvent::XMPP::Error::IQ object where the "condition" method
193 returns a special value (see also "condition" method of
194 AnyEvent::XMPP::Error::IQ).
195 The default timeout for IQ is 60 seconds.
197 send_iq ($type, $create_cb, $result_cb, %attrs)
199 This method sends an IQ XMPP request.
200 If you want to respond to a IQ request you received via the
202 "iq_set_request_xml", and "iq_get_request_xml" events you have to
203 use the "reply_iq_result" or "reply_iq_error" methods documented
204 below.
205 Please take a look at the documentation for "send_iq" in
207 AnyEvent::XMPP::Writer about the meaning of $type, $create_cb and
208 %attrs (with the exception of the 'timeout' key of %attrs, see
209 below).
210 $result_cb will be called when a result was received or the timeout
212 reached. The first argument to $result_cb will be a
213 AnyEvent::XMPP::Node instance containing the IQ result stanza
214 contents.
215 If the IQ resulted in a stanza error the second argument to
217 $result_cb will be "undef" (if the error type was not 'continue')
218 and the third argument will be a AnyEvent::XMPP::Error::IQ object.
219 The timeout can be set by "set_default_iq_timeout" or passed
221 separately in the %attrs array as the value for the key "timeout"
222 (timeout in seconds btw.).
223 This method returns the newly generated id for this iq request.
225 next_iq_id
227 This method returns the next IQ id that will be used.
228 reply_iq_result ($req_iq_node, $create_cb, %attrs)
230 This method will generate a result reply to the iq request
231 "AnyEvent::XMPP::Node" in $req_iq_node.
232 Please take a look at the documentation for "send_iq" in
234 AnyEvent::XMPP::Writer about the meaning $create_cb and %attrs.
235 Use $create_cb to create the XML for the result.
237 The type for this iq reply is 'result'.
239 The "to" attribute of the reply stanza will be set to the "from"
241 attribute of the $req_iq_node. If $req_iq_node had no "from" node
242 it won't be set. If you want to overwrite the "to" field just pass
243 it via %attrs.
244 reply_iq_error ($req_iq_node, $error_type, $error, %attrs)
246 This method will generate an error reply to the iq request
247 "AnyEvent::XMPP::Node" in $req_iq_node.
248 $error_type is one of 'cancel', 'continue', 'modify', 'auth' and
250 'wait'. $error is one of the defined error conditions described in
251 "write_error_tag" method of AnyEvent::XMPP::Writer.
252 Please take a look at the documentation for "send_iq" in
254 AnyEvent::XMPP::Writer about the meaning of %attrs.
255 The type for this iq reply is 'error'.
257 The "to" attribute of the reply stanza will be set to the "from"
259 attribute of the $req_iq_node. If $req_iq_node had no "from" node
260 it won't be set. If you want to overwrite the "to" field just pass
261 it via %attrs.
262 authenticate
264 This method should be called after the "stream_pre_authentication"
265 event was emitted to continue authentication of the stream.
266 Usually this method only has to be called when you want to register
268 before you authenticate. See also the documentation of the
269 "stream_pre_authentication" event below.
270 send_presence ($type, $create_cb, %attrs)
272 This method sends a presence stanza, for the meanings of $type,
273 $create_cb and %attrs please take a look at the documentation for
274 "send_presence" method of AnyEvent::XMPP::Writer.
275 This methods does attach an id attribute to the presence stanza and
277 will return the id that was used (so you can react on possible
278 replies).
279 send_message ($to, $type, $create_cb, %attrs)
281 This method sends a message stanza, for the meanings of $to, $type,
282 $create_cb and %attrs please take a look at the documentation for
283 "send_message" method of AnyEvent::XMPP::Writer.
284 This methods does attach an id attribute to the message stanza and
286 will return the id that was used (so you can react on possible
287 replies).
288 do_rebind ($resource)
290 In case you got a "bind_error" event and want to retry binding you
291 can call this function to set a new $resource and retry binding.
292 If it fails again you can call this again. Becareful not to end up
294 in a loop!
295 If binding was successful the "stream_ready" event will be
297 generated.
298 jid After the stream has been bound to a resource the JID can be
300 retrieved via this method.
301 features
303 Returns the last received <features> tag in form of an
304 AnyEvent::XMPP::Node object.
305 stream_id
307 This is the ID of this stream that was given us by the server.
308
310 The AnyEvent::XMPP::Connection class is derived from the Object::Event
311 class, and thus inherits the event callback registering system from it.
312 Consult the documentation of Object::Event about more details.
313 NODE: Every callback gets as it's first argument the
315 AnyEvent::XMPP::Connection object. The further callback arguments are
316 described in the following listing of events.
317 These events can be registered on with "reg_cb":
319 stream_features => $node
321 This event is sent when a stream feature (<features>) tag is
322 received. $node is the AnyEvent::XMPP::Node object that represents
323 the <features> tag.
324 stream_pre_authentication
326 This event is emitted after TLS/SSL was initiated (if enabled) and
327 before any authentication happened.
328 The return value of the first event callback that is called decides
330 what happens next. If it is true value the authentication
331 continues. If it is undef or a false value authentication is
332 stopped and you need to call "authentication" later. value
333 This event is usually used when you want to do in-band
335 registration, see also AnyEvent::XMPP::Ext::Registration.
336 stream_ready => $jid
338 This event is sent if the XML stream has been established (and
339 resources have been bound) and is ready for transmitting regular
340 stanzas.
341 $jid is the bound jabber id.
343 error => $error
345 This event is generated whenever some error occured. $error is an
346 instance of AnyEvent::XMPP::Error. Trivial error reporting may
347 look like this:
348 $con->reg_cb (error => sub { warn "xmpp error: " . $_[1]->string . "\n" });
350 Basically this event is a collect event for all other error events.
352 stream_error => $error
354 This event is sent if a XML stream error occured. $error is a
355 AnyEvent::XMPP::Error::Stream object.
356 xml_parser_error => $error
358 This event is generated whenever the parser trips over XML that it
359 can't read. $error is a AnyEvent::XMPP::Error::Parser object.
360 tls_error
362 This event is emitted when a TLS error occured on TLS negotiation.
363 After this the connection will be disconnected.
364 sasl_error => $error
366 This event is emitted on SASL authentication error.
367 iq_auth_error => $error
369 This event is emitted when IQ authentication (XEP-0078) failed.
370 bind_error => $error, $resource
372 This event is generated when the stream was unable to bind to any
373 or the in "new" specified resource. $error is a
374 AnyEvent::XMPP::Error::IQ object. $resource is the errornous
375 resource string or undef if none was received.
376 The "condition" of the $error might be one of: 'bad-request',
378 'not-allowed' or 'conflict'.
379 Node: this is untested, I couldn't get the server to send a bind
381 error to test this.
382 connect => $host, $port
384 This event is generated when a successful TCP connect was performed
385 to the domain passed to "new".
386 Note: $host and $port might be different from the domain you passed
388 to "new" if "connect" performed a SRV RR lookup.
389 If this connection is lost a "disconnect" will be generated with
391 the same $host and $port.
392 disconnect => $host, $port, $message
394 This event is generated when the TCP connection was lost or another
395 error occurred while writing or reading from it.
396 $message is a human readable error message for the failure. $host
398 and $port were the host and port we were connected to.
399 Note: $host and $port might be different from the domain you passed
401 to "new" if "connect" performed a SRV RR lookup.
402 recv_stanza_xml => $node, $rstop
404 This event is generated before any processing of a "XML" stanza
405 happens. $node is the node of the stanza that is being processed,
406 it's of type AnyEvent::XMPP::Node.
407 This method might not be as handy for debugging purposes as
409 "debug_recv".
410 If you want to handle the stanza yourself and don't want this
412 module to take care of it set a true value to the scalar referenced
413 by $rstop.
414 send_stanza_data => $data
416 This event is generated shortly before data is sent to the socket.
417 $data contains a complete "XML" stanza or the end of stream closing
418 tag. This method is useful for debugging purposes and I recommend
419 using XML::Twig or something like that to display it nicely.
420 See also the event "debug_send".
422 debug_send => $data
424 This method is invoked whenever data is written out. This event is
425 mostly the same as "send_stanza_data".
426 debug_recv => $data
428 This method is invoked whenever a chunk of data was received.
429 It works to filter $data through XML::Twig for debugging display
431 purposes sometimes, but as $data is some arbitrary chunk of bytes
432 you might get a XML parse error (did I already mention that XMPP's
433 application of "XML" sucks?).
434 So you might want to use "recv_stanza_xml" to detect complete
436 stanzas. Unfortunately "recv_stanza_xml" doesn't have the bytes
437 anymore and just a data structure (AnyEvent::XMPP::Node).
438 send_buffer_empty
440 This event is VERY useful if you want to wait (or at least be
441 notified) when the output buffer is empty. If you got a bunch of
442 messages to sent or even one and you want to do something when the
443 output buffer is empty, you can wait for this event. It is emitted
444 every time the output buffer is completely written out to the
445 kernel.
446 Here is an example:
448 $con->reg_cb (send_buffer_empty => sub {
450 $con->disconnect ("wrote message, going to disconnect now...");
451 });
452 $con->send_message ("Test message!" => 'elmex@jabber.org', undef, 'chat');
453 presence_xml => $node
455 This event is sent when a presence stanza is received. $node is the
456 AnyEvent::XMPP::Node object that represents the <presence> tag.
457 If you want to overtake the handling of the stanza, see "iq_xml"
459 below.
460 message_xml => $node
462 This event is sent when a message stanza is received. $node is the
463 AnyEvent::XMPP::Node object that represents the <message> tag.
464 If you want to overtake the handling of the stanza, see "iq_xml"
466 below.
467 iq_xml => $node
469 This event is emitted when a iq stanza arrives. $node is the
470 AnyEvent::XMPP::Node object that represents the <iq> tag.
471 If you want to overtake the handling of a stanza, you should
473 register a callback for the "before_iq_xml" event and call the
474 "stop_event" method. See also Object::Event. This is an example:
475 $con->reg_cb (before_iq_xml => sub {
477 my ($con, $node) = @_;
478 if (...) {
480 # and stop_event will stop internal handling of the stanza:
481 $con->stop_event;
482 }
483 });
484 Please note that if you overtake handling of a stanza none of the
486 internal handling of that stanza will be done. That means you won't
487 get events like "iq_set_request_xml" anymore.
488 iq_set_request_xml => $node, $rhandled
490 iq_get_request_xml => $node, $rhandled
491 These events are sent when an iq request stanza of type 'get' or
492 'set' is received. $type will either be 'get' or 'set' and $node
493 will be the AnyEvent::XMPP::Node object of the iq tag.
494 To signal the stanza was handled set the scalar referenced by
496 $rhandled to a true value. If the stanza was not handled an error
497 iq will be generated.
498 iq_result_cb_exception => $exception
500 If the $result_cb of a "send_iq" operation somehow threw a
501 exception or failed this event will be generated.
502 send_iq_hook => $id, $type, $attrs
504 This event lets you add any desired number of additional create
505 callbacks to a IQ stanza that is about to be sent.
506 $id, $type are described in the documentation of "send_iq" of
508 AnyEvent::XMPP::Writer. $attrs is the hashref to the %attrs hash
509 that can be passed to "send_iq" and also has the exact same
510 semantics as described in the documentation of "send_iq".
511 The return values of the event callbacks are interpreted as
513 $create_cb value as documented for "send_iq". (That means you can
514 for example return a callback that fills the IQ).
515 Example:
517 # this appends a <test/> element to all outgoing IQs
519 # and also a <test2/> element to all outgoing IQs
520 $con->reg_cb (send_iq_hook => sub {
521 my ($con, $id, $type, $attrs) = @_;
522 (sub {
523 my $w = shift; # $w is a XML::Writer instance
524 $w->emptyTag ('test');
525 }, {
526 node => { name => "test2" } # see also simxml() defined in AnyEvent::XMPP::Util
527 })
528 });
529 send_message_hook => $id, $to, $type, $attrs
531 This event lets you add any desired number of additional create
532 callbacks to a message stanza that is about to be sent.
533 $id, $to, $type and the hashref $attrs are described in the
535 documentation for "send_message" of AnyEvent::XMPP::Writer ($attrs
536 is %attrs there).
537 To actually append something you need to return something, what you
539 need to return is described in the "send_iq_hook" event above.
540 send_presence_hook => $id, $type, $attrs
542 This event lets you add any desired number of additional create
543 callbacks to a presence stanza that is about to be sent.
544 $id, $type and the hashref $attrs are described in the
546 documentation for "send_presence" of AnyEvent::XMPP::Writer ($attrs
547 is %attrs there).
548 To actually append something you need to return something, what you
550 need to return is described in the "send_iq_hook" event above.
551
553 Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
554
556 melo - minor fixes
557
559 Copyright 2007, 2008 Robin Redeker, all rights reserved.
560 This program is free software; you can redistribute it and/or modify it
562 under the same terms as Perl itself.
563perl v5.12.0 2009-08-14 AnyEvent::XMPP::Connection(3)