NAME

       POE::Component::Client::DNS - non-blocking, concurrent DNS requests

SYNOPSIS

         use POE qw(Component::Client::DNS);

         my $named = POE::Component::Client::DNS->spawn(
           Alias => "named"
         );

         POE::Session->create(
           inline_states  => {
             _start   => \&start_tests,
             response => \&got_response,
           }
         );

         POE::Kernel->run();
         exit;

         sub start_tests {
           my $response = $named->resolve(
             event   => "response",
             host    => "localhost",
             context => { },
           );
           if ($response) {
             $_[KERNEL]->yield(response => $response);
           }
         }

         sub got_response {
           my $response = $_[ARG0];
           my @answers = $response->{response}->answer();

           foreach my $answer (@answers) {
             print(
               "$response->{host} = ",
               $answer->type(), " ",
               $answer->rdatastr(), "\n"
             );
           }
         }

DESCRIPTION

       POE::Component::Client::DNS provides a facility for non-blocking, concurrent DNS requests.
       Using POE, it allows other tasks to run while waiting for name servers to respond.

PUBLIC METHODS

       spawn
         A program must spawn at least one POE::Component::Client::DNS instance before it can
         perform background DNS lookups.  Each instance represents a connection to a name server,
         or a pool of them.  If a program only needs to request DNS lookups from one server, then
         you only need one POE::Component::Client::DNS instance.

         As of version 0.98 you can override the default timeout per request.  From this point
         forward there is no need to spawn multiple instances o affect different timeouts for
         each request.

         PoCo::Client::DNS's "spawn" method takes a few named parameters:

         Alias sets the component's alias.  Requests will be posted to this alias.  The
         component's alias defaults to "resolver" if one is not provided.  Programs spawning more
         than one DNS client component must specify aliases for N-1 of them, otherwise alias
         collisions will occur.

           Alias => $session_alias,  # defaults to "resolver"

         Timeout sets the component's default timeout.  The timeout may be overridden per
         request.  See the "request" event, later on.  If no Timeout is set, the component will
         wait 90 seconds per request by default.

         Timeouts may be set to real numbers.  Timeouts are more accurate if you have Time::HiRes
         installed.  POE (and thus this component) will use Time::HiRes automatically if it's
         available.

           Timeout => $seconds_to_wait,  # defaults to 90

         Nameservers holds a reference to a list of name servers to try.  The list is passed
         directly to Net::DNS::Resolver's nameservers() method.  By default,
         POE::Component::Client::DNS will query the name servers that appear in /etc/resolv.conf
         or its equivalent.

           Nameservers => \@name_servers,  # defaults to /etc/resolv.conf's

         HostsFile (optional) holds the name of a specific hosts file to use for resolving
         hardcoded addresses.  By default, it looks for a file named /etc/hosts.

         On Windows systems, it may look in the following other places:

           $ENV{SystemRoot}\System32\Drivers\Etc\hosts
           $ENV{SystemRoot}\System\Drivers\Etc\hosts
           $ENV{SystemRoot}\hosts

       resolve
         resolve() requests the component to resolve a host name.  It will return a hash
         reference (described in RESPONSE MESSAGES, below) if it can honor the request
         immediately (perhaps from a cache).  Otherwise it returns undef if a resolver must be
         consulted asynchronously.

         Requests are passed as a list of named fields.

           $resolver->resolve(
             class   => $dns_record_class,  # defaults to "IN"
             type    => $dns_record_type,   # defaults to "A"
             host    => $request_host,      # required
             context => $request_context,   # required
             event   => $response_event,    # required
             timeout => $request_timeout,   # defaults to spawn()'s Timeout
           );

         The "class" and "type" fields specify what kind of information to return about a host.
         Most of the time internet addresses are requested for host names, so the class and type
         default to "IN" (internet) and "A" (address), respectively.

         The "host" field designates the host to look up.  It is required.

         The "event" field tells the component which event to send back when a response is
         available.  It is required, but it will not be used if resolve() can immediately return
         a cached response.

         "timeout" tells the component how long to wait for a response to this request.  It
         defaults to the "Timeout" given at spawn() time.

         "context" includes some external data that links responses back to their requests.  The
         context data is provided by the program that uses POE::Component::Client::DNS.  The
         component will pass the context back to the program without modification.  The "context"
         parameter is required, and may contain anything that fits in a scalar.

       shutdown
         shutdown() causes the component to terminate gracefully. It will finish serving pending
         requests then close down.

       get_resolver
         POE::Component::Client::DNS uses a Net::DNS::Resolver object internally.  get_resolver()
         returns that object so it may be interrogated or modified.  See Net::DNS::Resolver for
         options.

         Set the resolver to check on nonstandard port 1153:

           $poco_client_dns->resolver()->port(1153);

RESPONSE MESSAGES

       POE::Component::Client::DNS responds in one of two ways.  Its resolve() method will return
       a response immediately if it can be found in the component's cache.  Otherwise the
       component posts the response back in $_[ARG0].  In either case, the response is a hash
       reference containing the same fields:

         host     => $request_host,
         type     => $request_type,
         class    => $request_class,
         context  => $request_context,
         response => $net_dns_packet,
         error    => $net_dns_error,

       The "host", "type", "class", and "context" response fields are identical to those given in
       the request message.

       "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.

SEE ALSO

       POE - POE::Component::Client::DNS builds heavily on POE.

       Net::DNS - This module uses Net::DNS internally.

       Net::DNS::Packet - Responses are returned as Net::DNS::Packet objects.

DEPRECATIONS

       The older, list-based interfaces are no longer documented as of version 0.98.  They are
       being phased out.  The method-based interface, first implementedin version 0.98, will
       replace the deprecated interfaces after a six-month phase-out period.

       Version 0.98 was released in October of 2004.  The deprecated interfaces will continue to
       work without warnings until January 2005.

       As of January 2005, programs that use the deprecated interfaces will continue to work, but
       they will generate mandatory warnings.  Those warnings will persist until April 2005.

       As of April 2005 the mandatory warnings will be upgraded to mandatory errors.  Support for
       the deprecated interfaces will be removed entirely.

BUG TRACKER

       https://rt.cpan.org/Dist/Display.html?Queue=POE-Component-Client-DNS

REPOSITORY

       http://github.com/rcaputo/poe-component-client-dns

OTHER RESOURCES

       http://search.cpan.org/dist/POE-Component-Client-DNS/

AUTHOR & COPYRIGHTS

       POE::Component::Client::DNS is Copyright 1999-2009 by Rocco Caputo.  All rights are
       reserved.  POE::Component::Client::DNS is free software; you may redistribute it and/or
       modify it under the same terms as Perl itself.

       Postback arguments were contributed by tag.