1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
|
# NAME
POE::Component::Client::DNS - non-blocking, parallel DNS client
# VERSION
version 1.054
# 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 non-blocking, parallel DNS
requests via Net::DNS. Using POE, it allows other tasks to run while
waiting for name servers to respond.
For simple name resolution, including smart handling of IPv6 names,
please see [POE::Component::Resolver](https://metacpan.org/pod/POE::Component::Resolver) instead.
# PUBLIC METHODS
- spawn
A program must spawn at least one POE::Component::Client::DNS instance
before it can perform background DNS requests. Each instance
represents a connection to one or more name servers. If a program
only needs to request DNS requests 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
to 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
nameservers => $nameservers, # defaults to $resolver's Nameservers
);
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](https://metacpan.org/pod/Net::DNS::Resolver) for options.
Set the resolver to check on nonstandard port 1153:
$poco_client_dns->get_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](https://metacpan.org/pod/Net::DNS) and [Net::DNS::Packet](https://metacpan.org/pod/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](https://metacpan.org/pod/POE) - POE::Component::Client::DNS builds heavily on POE.
[POE::Component::Resolver](https://metacpan.org/pod/POE::Component::Resolver) - A system name resolver, including IPv6
support and whatever else your system supports.
[Net::DNS](https://metacpan.org/pod/Net::DNS) - This module uses Net::DNS internally.
[Net::DNS::Packet](https://metacpan.org/pod/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.
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 DNS server requests.
# 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.
|
