1AnyEvent::XMPP::ConnectUisoenr(3C)ontributed Perl DocumeAnntyaEtvieonnt::XMPP::Connection(3)
2
3
4

NAME

6       AnyEvent::XMPP::Connection - XML stream that implements the XMPP RFC
7       3920.
8

SYNOPSIS

10          use AnyEvent::XMPP::Connection;
11
12          my $con =
13             AnyEvent::XMPP::Connection->new (
14                username => "abc",
15                domain => "jabber.org",
16                resource => "AnyEvent::XMPP"
17             );
18
19          $con->reg_cb (stream_ready => sub { print "XMPP stream ready!\n" });
20          $con->connect; # will do non-blocking connect
21

DESCRIPTION

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
27       And receive events with the "reg_cb" event framework from the
28       connection.
29
30       If you need instant messaging stuff please take a look at
31       "AnyEvent::XMPP::IM::Connection".
32

METHODS

34       new (%args)
35           Following arguments can be passed in %args:
36
37           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
41               Please look in RFC 3066 how $tag should look like.
42
43           jid => $jid
44               This can be used to set the settings "username", "domain" (and
45               optionally "resource") from a $jid.
46
47           username => $username
48               This is your $username (the userpart in the JID);
49
50               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
55               NOTE: This field has no effect if "jid" is given!
56
57           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
62               NOTE: This field has no effect if "jid" is given!
63
64           resource => $resource
65               If this argument is given $resource will be passed as desired
66               resource on resource binding.
67
68               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
73           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
77               NOTE: To disable DNS SRV lookup you need to specify the port
78               number yourself. See "port" below.
79
80           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
86               This flag is provided until support for XEP 0233 is deployed,
87               which will fix the hostname issue w.r.t. GSSAPI SASL.
88
89           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
96           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
102           password => $password
103               This is the password for the "username" above.
104
105           disable_ssl => $bool
106               If $bool is true no SSL will be used.
107
108           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
114               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
118           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
124           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
130               See also "disable_old_jabber_authentication" below.
131
132           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
138           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
144               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
151               Please note that the old authentication method will fail if
152               "disable_iq_auth" is true.
153
154           stream_version_override => $version
155               NOTE: Only use if you really know what you are doing!
156
157               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
162           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
167       connect ()
168           Try to connect (non blocking) to the domain and port passed in
169           "new".
170
171           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
175           If the connection try was not successful a "disconnect" event will
176           be generated with an error message.
177
178           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
182           NOTE: The "XML" stream initiation is sent when the connection was
183           successfully connected.
184
185       is_connected ()
186           Returns true if the connection is still connected and stanzas can
187           be sent.
188
189       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
196           The default timeout for IQ is 60 seconds.
197
198       send_iq ($type, $create_cb, $result_cb, %attrs)
199           This method sends an IQ XMPP request.
200
201           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
206           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
211           $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
216           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
220           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
224           This method returns the newly generated id for this iq request.
225
226       next_iq_id
227           This method returns the next IQ id that will be used.
228
229       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
233           Please take a look at the documentation for "send_iq" in
234           AnyEvent::XMPP::Writer about the meaning $create_cb and %attrs.
235
236           Use $create_cb to create the XML for the result.
237
238           The type for this iq reply is 'result'.
239
240           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
245       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
249           $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
253           Please take a look at the documentation for "send_iq" in
254           AnyEvent::XMPP::Writer about the meaning of %attrs.
255
256           The type for this iq reply is 'error'.
257
258           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
263       authenticate
264           This method should be called after the "stream_pre_authentication"
265           event was emitted to continue authentication of the stream.
266
267           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
271       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
276           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
280       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
285           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
289       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
293           If it fails again you can call this again. Becareful not to end up
294           in a loop!
295
296           If binding was successful the "stream_ready" event will be
297           generated.
298
299       jid After the stream has been bound to a resource the JID can be
300           retrieved via this method.
301
302       features
303           Returns the last received <features> tag in form of an
304           AnyEvent::XMPP::Node object.
305
306       stream_id
307           This is the ID of this stream that was given us by the server.
308

EVENTS

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
314       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
318       These events can be registered on with "reg_cb":
319
320       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
325       stream_pre_authentication
326           This event is emitted after TLS/SSL was initiated (if enabled) and
327           before any authentication happened.
328
329           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
334           This event is usually used when you want to do in-band
335           registration, see also AnyEvent::XMPP::Ext::Registration.
336
337       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
342           $jid is the bound jabber id.
343
344       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
349              $con->reg_cb (error => sub { warn "xmpp error: " . $_[1]->string . "\n" });
350
351           Basically this event is a collect event for all other error events.
352
353       stream_error => $error
354           This event is sent if a XML stream error occured. $error is a
355           AnyEvent::XMPP::Error::Stream object.
356
357       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
361       tls_error
362           This event is emitted when a TLS error occured on TLS negotiation.
363           After this the connection will be disconnected.
364
365       sasl_error => $error
366           This event is emitted on SASL authentication error.
367
368       iq_auth_error => $error
369           This event is emitted when IQ authentication (XEP-0078) failed.
370
371       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
377           The "condition" of the $error might be one of: 'bad-request',
378           'not-allowed' or 'conflict'.
379
380           Node: this is untested, I couldn't get the server to send a bind
381           error to test this.
382
383       connect => $host, $port
384           This event is generated when a successful TCP connect was performed
385           to the domain passed to "new".
386
387           Note: $host and $port might be different from the domain you passed
388           to "new" if "connect" performed a SRV RR lookup.
389
390           If this connection is lost a "disconnect" will be generated with
391           the same $host and $port.
392
393       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
397           $message is a human readable error message for the failure.  $host
398           and $port were the host and port we were connected to.
399
400           Note: $host and $port might be different from the domain you passed
401           to "new" if "connect" performed a SRV RR lookup.
402
403       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
408           This method might not be as handy for debugging purposes as
409           "debug_recv".
410
411           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
415       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
421           See also the event "debug_send".
422
423       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
427       debug_recv => $data
428           This method is invoked whenever a chunk of data was received.
429
430           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
435           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
439       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
447           Here is an example:
448
449              $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
454       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
458           If you want to overtake the handling of the stanza, see "iq_xml"
459           below.
460
461       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
465           If you want to overtake the handling of the stanza, see "iq_xml"
466           below.
467
468       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
472           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
476              $con->reg_cb (before_iq_xml => sub {
477                 my ($con, $node) = @_;
478
479                 if (...) {
480                    # and stop_event will stop internal handling of the stanza:
481                    $con->stop_event;
482                 }
483              });
484
485           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
489       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
495           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
499       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
503       send_iq_hook => $id, $type, $attrs, \@create_cb
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
507           $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
512           You can push values into "create_cb" (as documented for "send_iq"),
513           for example a callback that fills the IQ.
514
515           Example:
516
517              # this appends a <test/> element to all outgoing IQs
518              # and also a <test2/> element to all outgoing IQs
519              $con->reg_cb (send_iq_hook => sub {
520                 my ($con, $id, $type, $attrs, $create_cb) = @_;
521                 push @$create_cb, sub {
522                    my $w = shift; # $w is a XML::Writer instance
523                    $w->emptyTag ('test');
524                 };
525                 push @$create_cb, {
526                    node => { name => "test2" } # see also simxml() defined in AnyEvent::XMPP::Util
527                 };
528              });
529
530       send_message_hook => $id, $to, $type, $attrs, \@create_cb
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
534           $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
538           To actually append something you need to push into "create_cb" as
539           described in the "send_iq_hook" event above.
540
541       send_presence_hook => $id, $type, $attrs, \@create_cb
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
545           $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
549           To actually append something you need to push into "create_cb" as
550           described in the "send_iq_hook" event above.
551

AUTHOR

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

CONTRIBUTORS

556       melo - minor fixes
557
559       Copyright 2007, 2008 Robin Redeker, all rights reserved.
560
561       This program is free software; you can redistribute it and/or modify it
562       under the same terms as Perl itself.
563
564
565
566perl v5.30.1                      2020-01-29     AnyEvent::XMPP::Connection(3)
Impressum