| 1 |
NAME |
| 2 |
|
| 3 |
POE::Component::Client::DNS - non-blocking, parallel DNS client |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
|
| 7 |
use POE qw(Component::Client::DNS); |
| 8 |
|
| 9 |
my $named = POE::Component::Client::DNS->spawn( |
| 10 |
Alias => "named" |
| 11 |
); |
| 12 |
|
| 13 |
POE::Session->create( |
| 14 |
inline_states => { |
| 15 |
_start => \&start_tests, |
| 16 |
response => \&got_response, |
| 17 |
} |
| 18 |
); |
| 19 |
|
| 20 |
POE::Kernel->run(); |
| 21 |
exit; |
| 22 |
|
| 23 |
sub start_tests { |
| 24 |
my $response = $named->resolve( |
| 25 |
event => "response", |
| 26 |
host => "localhost", |
| 27 |
context => { }, |
| 28 |
); |
| 29 |
if ($response) { |
| 30 |
$_[KERNEL]->yield(response => $response); |
| 31 |
} |
| 32 |
} |
| 33 |
|
| 34 |
sub got_response { |
| 35 |
my $response = $_[ARG0]; |
| 36 |
my @answers = $response->{response}->answer(); |
| 37 |
|
| 38 |
foreach my $answer (@answers) { |
| 39 |
print( |
| 40 |
"$response->{host} = ", |
| 41 |
$answer->type(), " ", |
| 42 |
$answer->rdatastr(), "\n" |
| 43 |
); |
| 44 |
} |
| 45 |
} |
| 46 |
|
| 47 |
DESCRIPTION |
| 48 |
|
| 49 |
POE::Component::Client::DNS provides non-blocking, parallel DNS |
| 50 |
requests via Net::DNS. Using POE, it allows other tasks to run while |
| 51 |
waiting for name servers to respond. |
| 52 |
|
| 53 |
For simple name resolution, including smart handling of IPv6 names, |
| 54 |
please see POE::Component::Resolver instead. |
| 55 |
|
| 56 |
PUBLIC METHODS |
| 57 |
|
| 58 |
spawn |
| 59 |
|
| 60 |
A program must spawn at least one POE::Component::Client::DNS |
| 61 |
instance before it can perform background DNS requests. Each instance |
| 62 |
represents a connection to one or more name servers. If a program |
| 63 |
only needs to request DNS requests from one server, then you only |
| 64 |
need one POE::Component::Client::DNS instance. |
| 65 |
|
| 66 |
As of version 0.98 you can override the default timeout per request. |
| 67 |
From this point forward there is no need to spawn multiple instances |
| 68 |
to affect different timeouts for each request. |
| 69 |
|
| 70 |
PoCo::Client::DNS's spawn method takes a few named parameters: |
| 71 |
|
| 72 |
Alias sets the component's alias. Requests will be posted to this |
| 73 |
alias. The component's alias defaults to "resolver" if one is not |
| 74 |
provided. Programs spawning more than one DNS client component must |
| 75 |
specify aliases for N-1 of them, otherwise alias collisions will |
| 76 |
occur. |
| 77 |
|
| 78 |
Alias => $session_alias, # defaults to "resolver" |
| 79 |
|
| 80 |
Timeout sets the component's default timeout. The timeout may be |
| 81 |
overridden per request. See the "request" event, later on. If no |
| 82 |
Timeout is set, the component will wait 90 seconds per request by |
| 83 |
default. |
| 84 |
|
| 85 |
Timeouts may be set to real numbers. Timeouts are more accurate if |
| 86 |
you have Time::HiRes installed. POE (and thus this component) will |
| 87 |
use Time::HiRes automatically if it's available. |
| 88 |
|
| 89 |
Timeout => $seconds_to_wait, # defaults to 90 |
| 90 |
|
| 91 |
Nameservers holds a reference to a list of name servers to try. The |
| 92 |
list is passed directly to Net::DNS::Resolver's nameservers() method. |
| 93 |
By default, POE::Component::Client::DNS will query the name servers |
| 94 |
that appear in /etc/resolv.conf or its equivalent. |
| 95 |
|
| 96 |
Nameservers => \@name_servers, # defaults to /etc/resolv.conf's |
| 97 |
|
| 98 |
HostsFile (optional) holds the name of a specific hosts file to use |
| 99 |
for resolving hardcoded addresses. By default, it looks for a file |
| 100 |
named /etc/hosts. |
| 101 |
|
| 102 |
On Windows systems, it may look in the following other places: |
| 103 |
|
| 104 |
$ENV{SystemRoot}\System32\Drivers\Etc\hosts |
| 105 |
$ENV{SystemRoot}\System\Drivers\Etc\hosts |
| 106 |
$ENV{SystemRoot}\hosts |
| 107 |
|
| 108 |
resolve |
| 109 |
|
| 110 |
resolve() requests the component to resolve a host name. It will |
| 111 |
return a hash reference (described in RESPONSE MESSAGES, below) if it |
| 112 |
can honor the request immediately (perhaps from a cache). Otherwise |
| 113 |
it returns undef if a resolver must be consulted asynchronously. |
| 114 |
|
| 115 |
Requests are passed as a list of named fields. |
| 116 |
|
| 117 |
$resolver->resolve( |
| 118 |
class => $dns_record_class, # defaults to "IN" |
| 119 |
type => $dns_record_type, # defaults to "A" |
| 120 |
host => $request_host, # required |
| 121 |
context => $request_context, # required |
| 122 |
event => $response_event, # required |
| 123 |
timeout => $request_timeout, # defaults to spawn()'s Timeout |
| 124 |
nameservers => $nameservers, # defaults to $resolver's Nameservers |
| 125 |
); |
| 126 |
|
| 127 |
The "class" and "type" fields specify what kind of information to |
| 128 |
return about a host. Most of the time internet addresses are |
| 129 |
requested for host names, so the class and type default to "IN" |
| 130 |
(internet) and "A" (address), respectively. |
| 131 |
|
| 132 |
The "host" field designates the host to look up. It is required. |
| 133 |
|
| 134 |
The "event" field tells the component which event to send back when a |
| 135 |
response is available. It is required, but it will not be used if |
| 136 |
resolve() can immediately return a cached response. |
| 137 |
|
| 138 |
"timeout" tells the component how long to wait for a response to this |
| 139 |
request. It defaults to the "Timeout" given at spawn() time. |
| 140 |
|
| 141 |
"context" includes some external data that links responses back to |
| 142 |
their requests. The context data is provided by the program that uses |
| 143 |
POE::Component::Client::DNS. The component will pass the context back |
| 144 |
to the program without modification. The "context" parameter is |
| 145 |
required, and may contain anything that fits in a scalar. |
| 146 |
|
| 147 |
shutdown |
| 148 |
|
| 149 |
shutdown() causes the component to terminate gracefully. It will |
| 150 |
finish serving pending requests then close down. |
| 151 |
|
| 152 |
get_resolver |
| 153 |
|
| 154 |
POE::Component::Client::DNS uses a Net::DNS::Resolver object |
| 155 |
internally. get_resolver() returns that object so it may be |
| 156 |
interrogated or modified. See Net::DNS::Resolver for options. |
| 157 |
|
| 158 |
Set the resolver to check on nonstandard port 1153: |
| 159 |
|
| 160 |
$poco_client_dns->get_resolver()->port(1153); |
| 161 |
|
| 162 |
RESPONSE MESSAGES |
| 163 |
|
| 164 |
POE::Component::Client::DNS responds in one of two ways. Its resolve() |
| 165 |
method will return a response immediately if it can be found in the |
| 166 |
component's cache. Otherwise the component posts the response back in |
| 167 |
$_[ARG0]. In either case, the response is a hash reference containing |
| 168 |
the same fields: |
| 169 |
|
| 170 |
host => $request_host, |
| 171 |
type => $request_type, |
| 172 |
class => $request_class, |
| 173 |
context => $request_context, |
| 174 |
response => $net_dns_packet, |
| 175 |
error => $net_dns_error, |
| 176 |
|
| 177 |
The "host", "type", "class", and "context" response fields are |
| 178 |
identical to those given in the request message. |
| 179 |
|
| 180 |
"response" contains a Net::DNS::Packet object on success or undef if |
| 181 |
the lookup failed. The Net::DNS::Packet object describes the response |
| 182 |
to the program's request. It may contain several DNS records. Please |
| 183 |
consult Net::DNS and Net::DNS::Packet for more information. |
| 184 |
|
| 185 |
"error" contains a description of any error that has occurred. It is |
| 186 |
only valid if "response" is undefined. |
| 187 |
|
| 188 |
SEE ALSO |
| 189 |
|
| 190 |
POE - POE::Component::Client::DNS builds heavily on POE. |
| 191 |
|
| 192 |
POE::Component::Resolver - A system name resolver, including IPv6 |
| 193 |
support and whatever else your system supports. |
| 194 |
|
| 195 |
Net::DNS - This module uses Net::DNS internally. |
| 196 |
|
| 197 |
Net::DNS::Packet - Responses are returned as Net::DNS::Packet objects. |
| 198 |
|
| 199 |
DEPRECATIONS |
| 200 |
|
| 201 |
The older, list-based interfaces are no longer documented as of version |
| 202 |
0.98. They are being phased out. The method-based interface, first |
| 203 |
implementedin version 0.98, will replace the deprecated interfaces |
| 204 |
after a six-month phase-out period. |
| 205 |
|
| 206 |
Version 0.98 was released in October of 2004. The deprecated interfaces |
| 207 |
will continue to work without warnings until January 2005. |
| 208 |
|
| 209 |
As of January 2005, programs that use the deprecated interfaces will |
| 210 |
continue to work, but they will generate mandatory warnings. Those |
| 211 |
warnings will persist until April 2005. |
| 212 |
|
| 213 |
As of April 2005 the mandatory warnings will be upgraded to mandatory |
| 214 |
errors. Support for the deprecated interfaces will be removed entirely. |
| 215 |
|
| 216 |
As of late January 2011, POE::Component::Resolver provides basic system |
| 217 |
resolver support, including IPv6 and mDNS if your resolver's configured |
| 218 |
ot use it. The use of POE::Component::Client::DNS for basic resolution |
| 219 |
is deprecated, however it's still the best option for actual DNS server |
| 220 |
requests. |
| 221 |
|
| 222 |
BUG TRACKER |
| 223 |
|
| 224 |
https://rt.cpan.org/Dist/Display.html?Queue=POE-Component-Client-DNS |
| 225 |
|
| 226 |
REPOSITORY |
| 227 |
|
| 228 |
http://github.com/rcaputo/poe-component-client-dns |
| 229 |
|
| 230 |
OTHER RESOURCES |
| 231 |
|
| 232 |
http://search.cpan.org/dist/POE-Component-Client-DNS/ |
| 233 |
|
| 234 |
AUTHOR & COPYRIGHTS |
| 235 |
|
| 236 |
POE::Component::Client::DNS is Copyright 1999-2009 by Rocco Caputo. All |
| 237 |
rights are reserved. POE::Component::Client::DNS is free software; you |
| 238 |
may redistribute it and/or modify it under the same terms as Perl |
| 239 |
itself. |
| 240 |
|
| 241 |
Postback arguments were contributed by tag. |
| 242 |
|