view release on metacpan or  search on metacpan

lib/AnyEvent/IRC/Connection.pm  view on Meta::CPAN

=head1 NAME

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

=head1 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;

=head1 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
C<encode_ctcp> and C<decode_ctcp> provided by L<AnyEvent::IRC::Util>.

=head2 METHODS

=over 4

=item $con = AnyEvent::IRC::Connection->new ()

This constructor doesn't take any arguments.

B<NOTE:> You are free to use the hash member C<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 C<heap> method.

=cut

sub new {
  my $this = shift;
  my $class = ref($this) || $this;

  my $self = $class->SUPER::new (@_, heap => { });

  bless $self, $class;

  $self->reg_cb (
     ext_after_send => sub {
        my ($self, $mkmsg_args) = @_;
        $self->send_raw (mk_msg (@$mkmsg_args));
     }
  );

  return $self;
}

=item $con->connect ($host, $port [, $prepcb_or_timeout])

Tries to open a socket to the host C<$host> and the port C<$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 C<enable_ssl>
method before to enable it.

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

=cut

sub connect {
   my ($self, $host, $port, $prep) = @_;

   if ($self->{socket}) {
      $self->disconnect ("reconnect requested.");
   }

   $self->{con_guard} =
      tcp_connect $host, $port, sub {
         my ($fh) = @_;

         delete $self->{socket};

         unless ($fh) {
            $self->event (connect => $!);
            return;
         }

         $self->{host} = $host;
         $self->{port} = $port;

         $self->{socket} =
            AnyEvent::Handle->new (
               fh => $fh,
               ($self->{enable_ssl} ? (tls => 'connect') : ()),
               on_eof => sub {
                  $self->disconnect ("EOF from server $host:$port");
               },
               on_error => sub {
                  $self->disconnect ("error in connection to server $host:$port: $!");
               },
               on_read => sub {
                  my ($hdl) = @_;