AnyEvent::IRC::Connection

AnyEvent::IRC::ConnectUser3Contributed Perl DocuAnyEvent::IRC::Connection(3pm)



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.14.2                      2011-12-01    AnyEvent::IRC::Connection(3pm)