NAME
    POE::Component::Client::DNS::Recursive - A recursive DNS client for POE

SYNOPSIS
      use strict;
      use warnings;
      use Getopt::Long;
  
      use POE qw(Component::Client::DNS::Recursive);
  
      my $trace;
      GetOptions ('trace' => \$trace);
  
      my $host = shift || die "Nothing to query\n";
      my $type = shift;
  
      POE::Session->create(
        package_states => [
              'main', [qw(_start _response _trace)],
        ],
      );
  
      $poe_kernel->run();
      exit 0;
  
      sub _start {
        POE::Component::Client::DNS::Recursive->resolve(
              event => '_response',
              host => $host,
            ( $type ? ( type => $type ) : () ),
            ( $trace ? ( trace => '_trace' ) : () ),
        );
        return;
      }
  
      sub _trace {
        my $packet = $_[ARG0];
        return unless $packet;
        print $packet->string;
        return;
      }
  
      sub _response {
        my $packet = $_[ARG0]->{response};
        return unless $packet;
        print $packet->string;
        return;
      }

DESCRIPTION
    POE::Component::Client::DNS::Recursive is a POE component that
    implements a recursive DNS client.

    POE sessions and components can spawn a
    POE::Component::Client::DNS::Recursive instance to perform a DNS query.
    The component will perform its task and return the results to the
    requesting session.

    One may also enable tracing of the delegation path from the root name
    servers for the name being looked up.

CONSTRUCTOR
    "resolve"
        Takes a number of options, only those marked as "mandatory" are
        required:

          'event', the event to emit when completed, mandatory;
          'host', what to look up, mandatory;
          'type', defaults to 'A' or 'PTR' if 'host' appears to be an IP address;
          'class', defaults to 'IN';
          'port', the port to use for DNS requests. Default is 53;
          'session', provide an alternative session to send the resultant event to;
          'trace', the event to send trace information to;
          'nameservers', an arrayref of IP addresses that the poco will use instead of built-in 'hints';
          'context', user defined data. Can be anything that can be stored in a scalar;

        "event" and "trace" are discussed in the "OUTPUT EVENTS" section
        below.

        "session" is only required if one wishes to send the resultant
        events to a different session than the calling one, or if the
        component is spawned with the POE::Kernel as its parent.

OUTPUT EVENTS
    The output events from the component as specified in the "resolve"
    constructor.

    "event"
        Emitted when the query has finished.

        "ARG0" will contain a hashref with the following fields:

          host     => the host requested,
          type     => the type requested,
          class    => the class requested,
          context  => the context that was passed to us,
          response => a Net::DNS::Packet object,
          error    => an error message ( if applicable )

        "response" contains a Net::DNS::Packet object on success or undef if
        the lookup failed. The Net::DNS::Packet object describes the
        response to the program's request. It may contain several DNS
        records. Please consult Net::DNS and Net::DNS::Packet for more
        information.

        "error" contains a description of any error that has occurred. It is
        only valid if "response" is undefined.

    "trace"
        Emitted whenever an element of the delegation path from the root
        servers is found.

        "ARG0" will be a Net::DNS::Packet object.

AUTHOR
    Chris "BinGOs" Williams <chris@bingosnet.co.uk>

LICENSE
    Copyright © Chris Williamss.

    This module may be used, modified, and distributed under the same terms
    as Perl itself. Please see the license that came with your Perl
    distribution for details.

SEE ALSO
    POE::Component::Client::DNS