Provided by: libanyevent-xmpp-perl_0.55-6_all bug

NAME

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

SYNOPSIS

          use AnyEvent::XMPP::Connection;

          my $con =
             AnyEvent::XMPP::Connection->new (
                username => "abc",
                domain => "jabber.org",
                resource => "AnyEvent::XMPP"
             );

          $con->reg_cb (stream_ready => sub { print "XMPP stream ready!\n" });
          $con->connect; # will do non-blocking connect

DESCRIPTION

       This module represents a XMPP stream as described in RFC 3920. You can issue the basic XMPP XML stanzas
       with methods like "send_iq", "send_message" and "send_presence".

       And receive events with the "reg_cb" event framework from the connection.

       If you need instant messaging stuff please take a look at "AnyEvent::XMPP::IM::Connection".

METHODS

       new (%args)
           Following arguments can be passed in %args:

           language => $tag
               This  should  be  the  language  of the human readable contents that will be transmitted over the
               stream. The default will be 'en'.

               Please look in RFC 3066 how $tag should look like.

           jid => $jid
               This can be used to set the settings "username", "domain"  (and  optionally  "resource")  from  a
               $jid.

           username => $username
               This is your $username (the userpart in the JID);

               Note:  You  have to take care that the stringprep profile for nodes can be applied at: $username.
               Otherwise the server might signal an error. See AnyEvent::XMPP::Util  for  utility  functions  to
               check this.

               NOTE: This field has no effect if "jid" is given!

           domain => $domain
               If  you  didn't  provide  a  "jid"  (see  above) you have to set the "username" which you want to
               connect as (see above) and the $domain to connect to.

               NOTE: This field has no effect if "jid" is given!

           resource => $resource
               If this argument is given $resource will be passed as desired resource on resource binding.

               Note: You have to take care that  the  stringprep  profile  for  resources  can  be  applied  at:
               $resource.  Otherwise  the  server  might  signal  an error. See AnyEvent::XMPP::Util for utility
               functions to check this.

           host => $host
               This parameter specifies the hostname where we are going to connect to. The default for  this  is
               the "domain" of the "jid".

               NOTE: To disable DNS SRV lookup you need to specify the port number yourself. See "port" below.

           use_host_as_sasl_hostname => $bool
               This is a special parameter for people who might want to use GSSAPI SASL mechanism. It will cause
               the value of the "host" parameter (see above) to be passed to the SASL mechanisms, instead of the
               "domain" of the JID.

               This  flag  is provided until support for XEP 0233 is deployed, which will fix the hostname issue
               w.r.t. GSSAPI SASL.

           port => $port
               This is optional, the default value for $port is 'xmpp-client=5222', which will used as  $service
               argument  to  "tcp_connect"  of  AnyEvent::Socket.   NOTE:  If  you  specify the port number here
               (instead of 'xmpp-client=5222'), no DNS SRV lookup will be done when connecting.

           connect_timeout => $timeout
               This sets the connection timeout. If the socket connect takes too long a "disconnect" event  will
               be  generated  with  an  appropriate  error message.  If this argument is not given no timeout is
               installed for the connects.

           password => $password
               This is the password for the "username" above.

           disable_ssl => $bool
               If $bool is true no SSL will be used.

           old_style_ssl => $bool
               If $bool is true the TLS handshake will be initiated when the  TCP  connection  was  established.
               This  is useful if you have to connect to an old Jabber server, with old-style SSL connections on
               port 5223.

               But that practice has been discouraged in XMPP, and a TLS handshake is done after the XML  stream
               has been established. Only use this option if you know what you are doing.

           disable_sasl => $bool
               If  $bool  is  true  SASL will NOT be used to authenticate with the server, even if it advertises
               SASL through stream features.  Alternative authentication methods will be used, such as  IQ  Auth
               (XEP-0078) if the server offers it.

           disable_iq_auth => $bool
               This  disables  the  use  of  IQ Auth (XEP-0078) for authentication, you might want to exclude it
               because it's deprecated and insecure. (However, I want to reach a maximum in  compatibility  with
               AnyEvent::XMPP so I'm not disabling this by default.

               See also "disable_old_jabber_authentication" below.

           anal_iq_auth => $bool
               This enables the anal iq auth mechanism that will first look in the stream features before trying
               to start iq authentication. Yes, servers don't always advertise what they can. I only implemented
               this option for my test suite.

           disable_old_jabber_authentication => $bool
               If  $bool  is  a  true  value, then the VERY old style authentication method with VERY old jabber
               server won't be used when a <stream> start tag from  the  server  without  version  attribute  is
               received.

               The  VERY  old style authentication method is per default enabled to ensure maximum compatibility
               with old jabber implementations. The old method works as follows: When a <stream>  start  tag  is
               received  from  the  server  with  no 'version' attribute IQ Auth (XEP-0078) will be initiated to
               authenticate with the server.

               Please note that the old authentication method will fail if "disable_iq_auth" is true.

           stream_version_override => $version
               NOTE: Only use if you really know what you are doing!

               This will override the stream version which is sent in the XMPP stream initiation  element.  This
               is  currently  only  used  by the tests which set $version to '0.9' for testing IQ authentication
               with ejabberd.

           whitespace_ping_interval => $interval
               This will set the whitespace ping interval (in seconds). The default  interval  are  60  seconds.
               You can disable the whitespace ping by setting $interval to 0.

       connect ()
           Try to connect (non blocking) to the domain and port passed in "new".

           The  connection  is  performed non blocking, so this method will just trigger the connection process.
           The event "connect" will be emitted when the connection was successfully established.

           If the connection try was not successful a  "disconnect"  event  will  be  generated  with  an  error
           message.

           NOTE:  Please note that you can't reconnect a AnyEvent::XMPP::Connection object. You need to recreate
           it if you want to reconnect.

           NOTE: The "XML" stream initiation is sent when the connection was successfully connected.

       is_connected ()
           Returns true if the connection is still connected and stanzas can be sent.

       set_default_iq_timeout ($seconds)
           This sets the default timeout for IQ requests. If the timeout runs out the request  will  be  aborted
           and  the callback called with a AnyEvent::XMPP::Error::IQ object where the "condition" method returns
           a special value (see also "condition" method of AnyEvent::XMPP::Error::IQ).

           The default timeout for IQ is 60 seconds.

       send_iq ($type, $create_cb, $result_cb, %attrs)
           This method sends an IQ XMPP request.

           If  you  want  to  respond  to  a  IQ  request  you  received  via  the   "iq_set_request_xml",   and
           "iq_get_request_xml"  events  you  have  to  use  the  "reply_iq_result"  or "reply_iq_error" methods
           documented below.

           Please take a look at the documentation for "send_iq" in AnyEvent::XMPP::Writer about the meaning  of
           $type, $create_cb and %attrs (with the exception of the 'timeout' key of %attrs, see below).

           $result_cb  will  be called when a result was received or the timeout reached.  The first argument to
           $result_cb will be a AnyEvent::XMPP::Node instance containing the IQ result stanza contents.

           If the IQ resulted in a stanza error the second argument to $result_cb will be "undef" (if the  error
           type was not 'continue') and the third argument will be a AnyEvent::XMPP::Error::IQ object.

           The  timeout  can  be set by "set_default_iq_timeout" or passed separately in the %attrs array as the
           value for the key "timeout" (timeout in seconds btw.).

           This method returns the newly generated id for this iq request.

       next_iq_id
           This method returns the next IQ id that will be used.

       reply_iq_result ($req_iq_node, $create_cb, %attrs)
           This method will generate a result reply to the iq request "AnyEvent::XMPP::Node" in $req_iq_node.

           Please take a look at the documentation for "send_iq" in  AnyEvent::XMPP::Writer  about  the  meaning
           $create_cb and %attrs.

           Use $create_cb to create the XML for the result.

           The type for this iq reply is 'result'.

           The  "to"  attribute  of the reply stanza will be set to the "from" attribute of the $req_iq_node. If
           $req_iq_node had no "from" node it won't be set. If you want to overwrite the "to" field just pass it
           via %attrs.

       reply_iq_error ($req_iq_node, $error_type, $error, %attrs)
           This method will generate an error reply to the iq request "AnyEvent::XMPP::Node" in $req_iq_node.

           $error_type is one of 'cancel', 'continue', 'modify', 'auth'  and  'wait'.   $error  is  one  of  the
           defined error conditions described in "write_error_tag" method of AnyEvent::XMPP::Writer.

           Please  take a look at the documentation for "send_iq" in AnyEvent::XMPP::Writer about the meaning of
           %attrs.

           The type for this iq reply is 'error'.

           The "to" attribute of the reply stanza will be set to the "from" attribute of  the  $req_iq_node.  If
           $req_iq_node had no "from" node it won't be set. If you want to overwrite the "to" field just pass it
           via %attrs.

       authenticate
           This  method  should  be  called  after the "stream_pre_authentication" event was emitted to continue
           authentication of the stream.

           Usually this method only has to be called when you want to register before you authenticate. See also
           the documentation of the "stream_pre_authentication" event below.

       send_presence ($type, $create_cb, %attrs)
           This method sends a presence stanza, for the meanings of $type, $create_cb and %attrs please  take  a
           look at the documentation for "send_presence" method of AnyEvent::XMPP::Writer.

           This  methods does attach an id attribute to the presence stanza and will return the id that was used
           (so you can react on possible replies).

       send_message ($to, $type, $create_cb, %attrs)
           This method sends a message stanza, for the meanings of $to, $type, $create_cb and %attrs please take
           a look at the documentation for "send_message" method of AnyEvent::XMPP::Writer.

           This methods does attach an id attribute to the message stanza and will return the id that  was  used
           (so you can react on possible replies).

       do_rebind ($resource)
           In  case  you  got a "bind_error" event and want to retry binding you can call this function to set a
           new $resource and retry binding.

           If it fails again you can call this again. Becareful not to end up in a loop!

           If binding was successful the "stream_ready" event will be generated.

       jid After the stream has been bound to a resource the JID can be retrieved via this method.

       features
           Returns the last received <features> tag in form of an AnyEvent::XMPP::Node object.

       stream_id
           This is the ID of this stream that was given us by the server.

EVENTS

       The AnyEvent::XMPP::Connection class is derived from the Object::Event class, and thus inherits the event
       callback registering system from it. Consult the documentation of Object::Event about more details.

       NODE: Every callback gets as it's first  argument  the  AnyEvent::XMPP::Connection  object.  The  further
       callback arguments are described in the following listing of events.

       These events can be registered on with "reg_cb":

       stream_features => $node
           This   event   is   sent   when  a  stream  feature  (<features>)  tag  is  received.  $node  is  the
           AnyEvent::XMPP::Node object that represents the <features> tag.

       stream_pre_authentication
           This event is emitted after  TLS/SSL  was  initiated  (if  enabled)  and  before  any  authentication
           happened.

           The return value of the first event callback that is called decides what happens next.  If it is true
           value the authentication continues. If it is undef or a false value authentication is stopped and you
           need to call "authentication" later.  value

           This   event   is   usually   used   when   you   want   to   do   in-band   registration,  see  also
           AnyEvent::XMPP::Ext::Registration.

       stream_ready => $jid
           This event is sent if the XML stream has been established (and resources  have  been  bound)  and  is
           ready for transmitting regular stanzas.

           $jid is the bound jabber id.

       error => $error
           This event is generated whenever some error occured.  $error is an instance of AnyEvent::XMPP::Error.
           Trivial error reporting may look like this:

              $con->reg_cb (error => sub { warn "xmpp error: " . $_[1]->string . "\n" });

           Basically this event is a collect event for all other error events.

       stream_error => $error
           This event is sent if a XML stream error occured. $error is a AnyEvent::XMPP::Error::Stream object.

       xml_parser_error => $error
           This  event  is  generated  whenever  the  parser  trips  over  XML  that  it can't read. $error is a
           AnyEvent::XMPP::Error::Parser object.

       tls_error
           This event is emitted when a TLS error occured on TLS negotiation.  After this the connection will be
           disconnected.

       sasl_error => $error
           This event is emitted on SASL authentication error.

       iq_auth_error => $error
           This event is emitted when IQ authentication (XEP-0078) failed.

       bind_error => $error, $resource
           This event is generated when the stream was unable to bind to any or the in "new" specified resource.
           $error is a AnyEvent::XMPP::Error::IQ object. $resource is the errornous resource string or undef  if
           none was received.

           The "condition" of the $error might be one of: 'bad-request', 'not-allowed' or 'conflict'.

           Node: this is untested, I couldn't get the server to send a bind error to test this.

       connect => $host, $port
           This event is generated when a successful TCP connect was performed to the domain passed to "new".

           Note: $host and $port might be different from the domain you passed to "new" if "connect" performed a
           SRV RR lookup.

           If this connection is lost a "disconnect" will be generated with the same $host and $port.

       disconnect => $host, $port, $message
           This  event  is generated when the TCP connection was lost or another error occurred while writing or
           reading from it.

           $message is a human readable error message for the failure.  $host and $port were the host  and  port
           we were connected to.

           Note: $host and $port might be different from the domain you passed to "new" if "connect" performed a
           SRV RR lookup.

       recv_stanza_xml => $node, $rstop
           This  event  is  generated before any processing of a "XML" stanza happens.  $node is the node of the
           stanza that is being processed, it's of type AnyEvent::XMPP::Node.

           This method might not be as handy for debugging purposes as "debug_recv".

           If you want to handle the stanza yourself and don't want this module to take care of it  set  a  true
           value to the scalar referenced by $rstop.

       send_stanza_data => $data
           This  event  is generated shortly before data is sent to the socket.  $data contains a complete "XML"
           stanza or the end of stream closing tag. This method is useful for debugging purposes and I recommend
           using XML::Twig or something like that to display it nicely.

           See also the event "debug_send".

       debug_send => $data
           This  method  is  invoked  whenever  data  is  written  out.  This  event  is  mostly  the  same   as
           "send_stanza_data".

       debug_recv => $data
           This method is invoked whenever a chunk of data was received.

           It  works to filter $data through XML::Twig for debugging display purposes sometimes, but as $data is
           some arbitrary chunk of bytes you might get a XML parse error (did  I  already  mention  that  XMPP's
           application of "XML" sucks?).

           So   you   might   want   to   use   "recv_stanza_xml"  to  detect  complete  stanzas.  Unfortunately
           "recv_stanza_xml" doesn't have the bytes anymore and just a data structure (AnyEvent::XMPP::Node).

       send_buffer_empty
           This event is VERY useful if you want to wait (or at least be notified) when  the  output  buffer  is
           empty.  If  you  got  a  bunch  of messages to sent or even one and you want to do something when the
           output buffer is empty, you can wait for this event. It is emitted every time the  output  buffer  is
           completely written out to the kernel.

           Here is an example:

              $con->reg_cb (send_buffer_empty => sub {
                 $con->disconnect ("wrote message, going to disconnect now...");
              });
              $con->send_message ("Test message!" => 'elmex@jabber.org', undef, 'chat');

       presence_xml => $node
           This  event is sent when a presence stanza is received. $node is the AnyEvent::XMPP::Node object that
           represents the <presence> tag.

           If you want to overtake the handling of the stanza, see "iq_xml" below.

       message_xml => $node
           This event is sent when a message stanza is received. $node is the AnyEvent::XMPP::Node  object  that
           represents the <message> tag.

           If you want to overtake the handling of the stanza, see "iq_xml" below.

       iq_xml => $node
           This  event  is  emitted  when  a  iq  stanza  arrives. $node is the AnyEvent::XMPP::Node object that
           represents the <iq> tag.

           If you want to  overtake  the  handling  of  a  stanza,  you  should  register  a  callback  for  the
           "before_iq_xml" event and call the "stop_event" method. See also Object::Event. This is an example:

              $con->reg_cb (before_iq_xml => sub {
                 my ($con, $node) = @_;

                 if (...) {
                    # and stop_event will stop internal handling of the stanza:
                    $con->stop_event;
                 }
              });

           Please  note  that  if you overtake handling of a stanza none of the internal handling of that stanza
           will be done. That means you won't get events like "iq_set_request_xml" anymore.

       iq_set_request_xml => $node, $rhandled
       iq_get_request_xml => $node, $rhandled
           These events are sent when an iq request stanza of type 'get'  or  'set'  is  received.   $type  will
           either be 'get' or 'set' and $node will be the AnyEvent::XMPP::Node object of the iq tag.

           To  signal  the  stanza  was  handled set the scalar referenced by $rhandled to a true value.  If the
           stanza was not handled an error iq will be generated.

       iq_result_cb_exception => $exception
           If the $result_cb of a "send_iq" operation somehow threw a exception or failed  this  event  will  be
           generated.

       send_iq_hook => $id, $type, $attrs, \@create_cb
           This  event  lets  you  add  any desired number of additional create callbacks to a IQ stanza that is
           about to be sent.

           $id, $type are described in the documentation of "send_iq" of AnyEvent::XMPP::Writer. $attrs  is  the
           hashref  to  the %attrs hash that can be passed to "send_iq" and also has the exact same semantics as
           described in the documentation of "send_iq".

           You can push values into "create_cb" (as documented for "send_iq"), for example a callback that fills
           the IQ.

           Example:

              # this appends a <test/> element to all outgoing IQs
              # and also a <test2/> element to all outgoing IQs
              $con->reg_cb (send_iq_hook => sub {
                 my ($con, $id, $type, $attrs, $create_cb) = @_;
                 push @$create_cb, sub {
                    my $w = shift; # $w is a XML::Writer instance
                    $w->emptyTag ('test');
                 };
                 push @$create_cb, {
                    node => { name => "test2" } # see also simxml() defined in AnyEvent::XMPP::Util
                 };
              });

       send_message_hook => $id, $to, $type, $attrs, \@create_cb
           This event lets you add any desired number of additional create callbacks to a message stanza that is
           about to be sent.

           $id, $to, $type and the hashref $attrs are described  in  the  documentation  for  "send_message"  of
           AnyEvent::XMPP::Writer ($attrs is %attrs there).

           To  actually  append  something  you need to push into "create_cb" as described in the "send_iq_hook"
           event above.

       send_presence_hook => $id, $type, $attrs, \@create_cb
           This event lets you add any desired number of additional create callbacks to a presence  stanza  that
           is about to be sent.

           $id,  $type  and  the  hashref  $attrs  are  described  in  the  documentation for "send_presence" of
           AnyEvent::XMPP::Writer ($attrs is %attrs there).

           To actually append something you need to push into "create_cb" as  described  in  the  "send_iq_hook"
           event above.

AUTHOR

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

CONTRIBUTORS

       melo - minor fixes

COPYRIGHT & LICENSE

       Copyright 2007, 2008 Robin Redeker, all rights reserved.

       This  program  is  free  software;  you can redistribute it and/or modify it under the same terms as Perl
       itself.

perl v5.36.0                                       2022-12-06                    AnyEvent::XMPP::Connection(3pm)