.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POE::Component::Client::DNS 3pm"
.TH POE::Component::Client::DNS 3pm "2023-10-29" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
POE::Component::Client::DNS \- non\-blocking, parallel DNS client
.SH "VERSION"
.IX Header "VERSION"
version 1.054
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use POE qw(Component::Client::DNS);
\&
\&  my $named = POE::Component::Client::DNS\->spawn(
\&    Alias => "named"
\&  );
\&
\&  POE::Session\->create(
\&    inline_states  => {
\&      _start   => \e&start_tests,
\&      response => \e&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(), "\en"
\&      );
\&    }
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
POE::Component::Client::DNS provides non-blocking, parallel \s-1DNS\s0
requests via Net::DNS.  Using \s-1POE,\s0 it allows other tasks to run while
waiting for name servers to respond.
.PP
For simple name resolution, including smart handling of IPv6 names,
please see POE::Component::Resolver instead.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
.IP "spawn" 2
.IX Item "spawn"
A program must spawn at least one POE::Component::Client::DNS instance
before it can perform background \s-1DNS\s0 requests.  Each instance
represents a connection to one or more name servers.  If a program
only needs to request \s-1DNS\s0 requests from one server, then you only need
one POE::Component::Client::DNS instance.
.Sp
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
to affect different timeouts for each request.
.Sp
PoCo::Client::DNS's \f(CW\*(C`spawn\*(C'\fR method takes a few named parameters:
.Sp
Alias sets the component's alias.  Requests will be posted to this
alias.  The component's alias defaults to \*(L"resolver\*(R" if one is not
provided.  Programs spawning more than one \s-1DNS\s0 client component must
specify aliases for N\-1 of them, otherwise alias collisions will
occur.
.Sp
.Vb 1
\&  Alias => $session_alias,  # defaults to "resolver"
.Ve
.Sp
Timeout sets the component's default timeout.  The timeout may be
overridden per request.  See the \*(L"request\*(R" event, later on.  If no
Timeout is set, the component will wait 90 seconds per request by
default.
.Sp
Timeouts may be set to real numbers.  Timeouts are more accurate if
you have Time::HiRes installed.  \s-1POE\s0 (and thus this component) will
use Time::HiRes automatically if it's available.
.Sp
.Vb 1
\&  Timeout => $seconds_to_wait,  # defaults to 90
.Ve
.Sp
Nameservers holds a reference to a list of name servers to try.  The
list is passed directly to Net::DNS::Resolver's \fBnameservers()\fR method.
By default, POE::Component::Client::DNS will query the name servers
that appear in /etc/resolv.conf or its equivalent.
.Sp
.Vb 1
\&  Nameservers => \e@name_servers,  # defaults to /etc/resolv.conf\*(Aqs
.Ve
.Sp
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.
.Sp
On Windows systems, it may look in the following other places:
.Sp
.Vb 3
\&  $ENV{SystemRoot}\eSystem32\eDrivers\eEtc\ehosts
\&  $ENV{SystemRoot}\eSystem\eDrivers\eEtc\ehosts
\&  $ENV{SystemRoot}\ehosts
.Ve
.IP "resolve" 2
.IX Item "resolve"
\&\fBresolve()\fR requests the component to resolve a host name.  It will
return a hash reference (described in \s-1RESPONSE MESSAGES,\s0 below) if it
can honor the request immediately (perhaps from a cache).  Otherwise
it returns undef if a resolver must be consulted asynchronously.
.Sp
Requests are passed as a list of named fields.
.Sp
.Vb 9
\&  $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()\*(Aqs Timeout
\&    nameservers => $nameservers,       # defaults to $resolver\*(Aqs Nameservers
\&  );
.Ve
.Sp
The \*(L"class\*(R" and \*(L"type\*(R" 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 \*(L"\s-1IN\*(R"\s0
(internet) and \*(L"A\*(R" (address), respectively.
.Sp
The \*(L"host\*(R" field designates the host to look up.  It is required.
.Sp
The \*(L"event\*(R" field tells the component which event to send back when a
response is available.  It is required, but it will not be used if
\&\fBresolve()\fR can immediately return a cached response.
.Sp
\&\*(L"timeout\*(R" tells the component how long to wait for a response to this
request.  It defaults to the \*(L"Timeout\*(R" given at \fBspawn()\fR time.
.Sp
\&\*(L"context\*(R" 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 \*(L"context\*(R" parameter is
required, and may contain anything that fits in a scalar.
.IP "shutdown" 2
.IX Item "shutdown"
\&\fBshutdown()\fR causes the component to terminate gracefully. It will finish
serving pending requests then close down.
.IP "get_resolver" 2
.IX Item "get_resolver"
POE::Component::Client::DNS uses a Net::DNS::Resolver object
internally.  \fBget_resolver()\fR returns that object so it may be
interrogated or modified.  See Net::DNS::Resolver for options.
.Sp
Set the resolver to check on nonstandard port 1153:
.Sp
.Vb 1
\&  $poco_client_dns\->get_resolver()\->port(1153);
.Ve
.SH "RESPONSE MESSAGES"
.IX Header "RESPONSE MESSAGES"
POE::Component::Client::DNS responds in one of two ways.  Its
\&\fBresolve()\fR method will return a response immediately if it can be found
in the component's cache.  Otherwise the component posts the response
back in \f(CW$_\fR[\s-1ARG0\s0].  In either case, the response is a hash reference
containing the same fields:
.PP
.Vb 6
\&  host     => $request_host,
\&  type     => $request_type,
\&  class    => $request_class,
\&  context  => $request_context,
\&  response => $net_dns_packet,
\&  error    => $net_dns_error,
.Ve
.PP
The \*(L"host\*(R", \*(L"type\*(R", \*(L"class\*(R", and \*(L"context\*(R" response fields are
identical to those given in the request message.
.PP
\&\*(L"response\*(R" 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 \s-1DNS\s0 records.  Please
consult Net::DNS and Net::DNS::Packet for more information.
.PP
\&\*(L"error\*(R" contains a description of any error that has occurred.  It is
only valid if \*(L"response\*(R" is undefined.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1POE\s0 \- POE::Component::Client::DNS builds heavily on \s-1POE.\s0
.PP
POE::Component::Resolver \- A system name resolver, including IPv6
support and whatever else your system supports.
.PP
Net::DNS \- This module uses Net::DNS internally.
.PP
Net::DNS::Packet \- Responses are returned as Net::DNS::Packet
objects.
.SH "DEPRECATIONS"
.IX Header "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.
.PP
Version 0.98 was released in October of 2004.  The deprecated
interfaces will continue to work without warnings until January 2005.
.PP
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.
.PP
As of April 2005 the mandatory warnings will be upgraded to mandatory
errors.  Support for the deprecated interfaces will be removed
entirely.
.PP
As of late January 2011, POE::Component::Resolver provides basic
system resolver support, including IPv6 and mDNS if your resolver's
configured ot use it.  The use of POE::Component::Client::DNS for
basic resolution is deprecated, however it's still the best option for
actual \s-1DNS\s0 server requests.
.SH "BUG TRACKER"
.IX Header "BUG TRACKER"
https://rt.cpan.org/Dist/Display.html?Queue=POE\-Component\-Client\-DNS
.SH "REPOSITORY"
.IX Header "REPOSITORY"
http://github.com/rcaputo/poe\-component\-client\-dns
.SH "OTHER RESOURCES"
.IX Header "OTHER RESOURCES"
http://search.cpan.org/dist/POE\-Component\-Client\-DNS/
.SH "AUTHOR & COPYRIGHTS"
.IX Header "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.
.PP
Postback arguments were contributed by tag.