NAME

       AnyEvent::IRC::Connection - An IRC connection abstraction

SYNOPSIS

          use AnyEvent;
          use AnyEvent::IRC::Connection;

          my $c = AnyEvent->condvar;

          my $con = new AnyEvent::IRC::Connection;

          $con->connect ("localhost", 6667);

          $con->reg_cb (
             connect => sub {
                my ($con) = @_;
                $con->send_msg (NICK => 'testbot');
                $con->send_msg (USER => 'testbot', '*', '0', 'testbot');
             },
             irc_001 => sub {
                my ($con) = @_;
                print "$_[1]->{prefix} says I'm in the IRC: $_[1]->{params}->[-1]!\n";
                $c->broadcast;
             }
          );

          $c->wait;

DESCRIPTION

       The connection class. Here the actual interesting stuff can be done, such as sending and receiving IRC
       messages. And it also handles TCP connecting and even enabling of TLS.

       Please note that CTCP support is available through the functions "encode_ctcp" and "decode_ctcp" provided
       by AnyEvent::IRC::Util.

   METHODS
       $con = AnyEvent::IRC::Connection->new ()
           This constructor doesn't take any arguments.

           NOTE: You are free to use the hash member "heap" (which contains a hash) to store any associated data
           with this object. For example retry timers or anything else.

           You can also access that member via the "heap" method.

       $con->connect ($host, $port [, $prepcb_or_timeout])
           Tries  to  open a socket to the host $host and the port $port.  If an error occurred it will die (use
           eval to catch the exception).

           If you want to connect via TLS/SSL you have to call the "enable_ssl" method before to enable it.

           $prepcb_or_timeout can either be a callback with the semantics of a prepare callback for the function
           "tcp_connect" in AnyEvent::Socket or a simple number which stands for a timeout.

       $con->enable_ssl ()
           This method will enable SSL for new connections that are initiated by "connect".

       $con->disconnect ($reason)
           Unregisters the connection  in  the  main  AnyEvent::IRC  object,  closes  the  sockets  and  send  a
           'disconnect' event with $reason as argument.

       $con->is_connected
           Returns true when this connection is connected.  Otherwise false.

       $con->heap ()
           Returns  the hash reference stored in the "heap" member, that is local to this connection object that
           lets you store any information you want.

       $con->send_raw ($ircline)
           This method sends $ircline straight to the server without any further processing done.

       $con->send_msg ($command, @params)
           This  function  sends   a   message   to   the   server.   @ircmsg   is   the   argument   list   for
           "AnyEvent::IRC::Util::mk_msg (undef, $command, @params)".

   EVENTS
       Following  events are emitted by this module and shouldn't be emitted from a module user call to "event".
       See also the documents Object::Event about registering event callbacks.

       connect => $error
           This event is generated when the socket  was  successfully  connected  or  an  error  occurred  while
           connecting. The error is given as second argument ($error) to the callback then.

       disconnect => $reason
           This  event  will be generated if the connection is somehow terminated.  It will also be emitted when
           "disconnect" is called.  The second argument to the callback is $reason, a  string  that  contains  a
           clue about why the connection terminated.

           If you want to reestablish a connection, call "connect" again.

       send => $ircmsg
           Emitted  when  a  message  is  about  to  be  sent. $ircmsg is an array reference to the arguments of
           "mk_msg" (see AnyEvent::IRC::Util). You may modify the array reference to change the message or  even
           intercept it completely by calling "stop_event" (see Object::Event API):

              $con->reg_cb (
                 send => sub {
                    my ($con, $ircmsg) = @_;

                    if ($ircmsg->[1] eq 'NOTICE') {
                       $con->stop_event; # prevent any notices from being sent.

                    } elsif ($ircmsg->[1] eq 'PRIVMSG') {
                       $ircmsg->[-1] =~ s/sex/XXX/i; # censor any outgoing private messages.
                    }
                 }
              );

       sent => @ircmsg
           Emitted   when  a  message  (@ircmsg)  was  sent  to  the  server.   @ircmsg  are  the  arguments  to
           "AnyEvent::IRC::Util::mk_msg".

       irc_* => $msg
       irc_<lowercase command> => $msg
       read => $msg
           Emitted when a message ($msg) was read from the server.  $msg  is  the  hash  reference  returned  by
           "AnyEvent::IRC::Util::parse_irc_msg";

           Note: '<lowercase command>' stands for the command of the message in (ASCII) lower case.

       buffer_empty
           This  event  is  emitted when the write buffer of the underlying connection is empty and all data has
           been given to the kernel. See also "samples/notify" about a usage example.

           Please note that this buffer is NOT the queue mentioned in AnyEvent::IRC::Client!

AUTHOR

       Robin Redeker, "<elmex@ta-sa.org>"

SEE ALSO

       AnyEvent::IRC

       AnyEvent::IRC::Client

COPYRIGHT & LICENSE

       Copyright 2006-2009 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.34.0                                       2022-06-06                     AnyEvent::IRC::Connection(3pm)