NAME

       Kanla::Plugin::Banner - Useful functions for banner-based plugins

SYNOPSIS

           use Kanla::Plugin;
           use Kanla::Plugin::Banner;

           sub run {
               banner_connect(
                   host            => 'irc.twice-irc.de',
                   default_service => 'ircd',
                   cb              => sub {
                       my ($handle, $timeout) = @_;
                       $handle->push_write("NICK kanla\r\n");
                       $handle->push_write("USER kanla kanla kanla :kanla\r\n");
                       my @read_line;
                       @read_line = (
                           line => sub {
                               my ($handle, $line) = @_;
                               if ($line !~ /^:[^ ]+ 001 /) {
                                   $handle->push_read(@read_line);
                                   return;
                               }

                               # We successfully signed on.
                               undef $timeout;
                               $handle->push_write("QUIT\r\n");
                               banner_disconnect($handle);
                           });

                       $handle->push_read(@read_line);
                   });
           }

METHODS

   banner_connect
       Connects to the given address (parsed by "AnyEvent::Socket"'s parse_hostport) using the
       configured address families.

       The caller provides a callback, which will be called after the connection was established.
       In case there was an error (DNS name could not be resolved, connection was refused/timed
       out, etc.), the callback will NOT be called, but an alert will be signaled.

       The callback will be called with an "AnyEvent::Handle" and an "AnyEvent" timer (timeouts).

       The timeout is initialized to the configured value (plugin configuration) or 20s if left
       unconfigured.

       This example connects to one of Google's SMTP servers and waits for the SMTP greeting.  It
       does not resolve MX records, but that's not the point of the example:

           banner_connect(
               host => 'aspmx.l.google.com',
               default_service => 'smtp',
               cb => sub {
                   my ($handle, $timeout) = @_;
                   $handle->push_read(line => sub {
                       my ($handle, $line) = @_;
                       undef $timeout;
                       if ($line !~ /^220 /) {
                           signal_error('critical', 'Invalid greeting');
                       }
                   });
               });

   banner_disconnect($handle)
       Properly disconnects the specified "AnyEvent::Handle".