1DNS(3) User Contributed Perl Documentation DNS(3)
2
6 POE::Component::Client::DNS - non-blocking, concurrent DNS requests
7
9 use POE qw(Component::Client::DNS);
10 my $named = POE::Component::Client::DNS->spawn(
12 Alias => "named"
13 );
14 POE::Session->create(
16 inline_states => {
17 _start => \&start_tests,
18 response => \&got_response,
19 }
20 );
21 POE::Kernel->run();
23 exit;
24 sub start_tests {
26 my $response = $named->resolve(
27 event => "response",
28 host => "localhost",
29 context => { },
30 );
31 if ($response) {
32 $_[KERNEL]->yield(response => $response);
33 }
34 }
35 sub got_response {
37 my $response = $_[ARG0];
38 my @answers = $response->{response}->answer();
39 foreach my $answer (@answers) {
41 print(
42 "$response->{host} = ",
43 $answer->type(), " ",
44 $answer->rdatastr(), "\n"
45 );
46 }
47 }
48
50 POE::Component::Client::DNS provides a facility for non-blocking, con‐
51 current DNS requests. Using POE, it allows other tasks to run while
52 waiting for name servers to respond.
53
55 spawn
56 A program must spawn at least one POE::Component::Client::DNS
57 instance before it can perform background DNS lookups. Each instance
58 represents a connection to a name server, or a pool of them. If a
59 program only needs to request DNS lookups from one server, then you
60 only need one POE::Component::Client::DNS instance.
61 As of version 0.98 you can override the default timeout per request.
63 From this point forward there is no need to spawn multiple instances
64 o affect different timeouts for each request.
65 PoCo::Client::DNS's "spawn" method takes a few named parameters:
67 Alias sets the component's alias. Requests will be posted to this
69 alias. The component's alias defaults to "resolver" if one is not
70 provided. Programs spawning more than one DNS client component must
71 specify aliases for N-1 of them, otherwise alias collisions will
72 occur.
73 Alias => $session_alias, # defaults to "resolver"
75 Timeout sets the component's default timeout. The timeout may be
77 overridden per request. See the "request" event, later on. If no
78 Timeout is set, the component will wait 90 seconds per request by
79 default.
80 Timeouts may be set to real numbers. Timeouts are more accurate if
82 you have Time::HiRes installed. POE (and thus this component) will
83 use Time::HiRes automatically if it's available.
84 Timeout => $seconds_to_wait, # defaults to 90
86 Nameservers holds a reference to a list of name servers to try. The
88 list is passed directly to Net::DNS::Resolver's nameservers() method.
89 By default, POE::Component::Client::DNS will query the name servers
90 that appear in /etc/resolv.conf or its equivalent.
91 Nameservers => \@name_servers, # defaults to /etc/resolv.conf's
93 HostsFile (optional) holds the name of a specific hosts file to use
95 for resolving hardcoded addresses. By default, it looks for a file
96 named /etc/hosts.
97 On Windows systems, it may look in the following other places:
99 $ENV{SystemRoot}\System32\Drivers\Etc\hosts
101 $ENV{SystemRoot}\System\Drivers\Etc\hosts
102 $ENV{SystemRoot}\hosts
103 resolve
105 resolve() requests the component to resolve a host name. It will
106 return a hash reference (described in RESPONSE MESSAGES, below) if it
107 can honor the request immediately (perhaps from a cache). Otherwise
108 it returns undef if a resolver must be consulted asynchronously.
109 Requests are passed as a list of named fields.
111 $resolver->resolve(
113 class => $dns_record_class, # defaults to "IN"
114 type => $dns_record_type, # defaults to "A"
115 host => $request_host, # required
116 context => $request_context, # required
117 event => $response_event, # required
118 timeout => $request_timeout, # defaults to spawn()'s Timeout
119 );
120 The "class" and "type" fields specify what kind of information to
122 return about a host. Most of the time internet addresses are
123 requested for host names, so the class and type default to "IN"
124 (internet) and "A" (address), respectively.
125 The "host" field designates the host to look up. It is required.
127 The "event" field tells the component which event to send back when a
129 response is available. It is required, but it will not be used if
130 resolve() can immediately return a cached response.
131 "timeout" tells the component how long to wait for a response to this
133 request. It defaults to the "Timeout" given at spawn() time.
134 "context" includes some external data that links responses back to
136 their requests. The context data is provided by the program that
137 uses POE::Component::Client::DNS. The component will pass the con‐
138 text back to the program without modification. The "context" parame‐
139 ter is required, and may contain anything that fits in a scalar.
140 shutdown
142 shutdown() causes the component to terminate gracefully. It will fin‐
143 ish serving pending requests then close down.
144 get_resolver
146 POE::Component::Client::DNS uses a Net::DNS::Resolver object inter‐
147 nally. get_resolver() returns that object so it may be interrogated
148 or modified. See Net::DNS::Resolver for options.
149 Set the resolver to check on nonstandard port 1153:
151 $poco_client_dns->resolver()->port(1153);
153
155 POE::Component::Client::DNS responds in one of two ways. Its resolve()
156 method will return a response immediately if it can be found in the
157 component's cache. Otherwise the component posts the response back in
158 $_[ARG0]. In either case, the response is a hash reference containing
159 the same fields:
160 host => $request_host,
162 type => $request_type,
163 class => $request_class,
164 context => $request_context,
165 response => $net_dns_packet,
166 error => $net_dns_error,
167 The "host", "type", "class", and "context" response fields are identi‐
169 cal to those given in the request message.
170 "response" contains a Net::DNS::Packet object on success or undef if
172 the lookup failed. The Net::DNS::Packet object describes the response
173 to the program's request. It may contain several DNS records. Please
174 consult Net::DNS and Net::DNS::Packet for more information.
175 "error" contains a description of any error that has occurred. It is
177 only valid if "response" is undefined.
178
180 POE - POE::Component::Client::DNS builds heavily on POE.
181 Net::DNS - This module uses Net::DNS internally.
183 Net::DNS::Packet - Responses are returned as Net::DNS::Packet objects.
185
187 This component does not yet expose the full power of Net::DNS.
188 Timeouts have not been tested extensively. Please contact the author
190 if you know of a reliable way to test DNS timeouts.
191
193 The older, list-based interfaces are no longer documented as of version
194 0.98. They are being phased out. The method-based interface, first
195 implementedin version 0.98, will replace the deprecated interfaces
196 after a six-month phase-out period.
197 Version 0.98 was released in October of 2004. The deprecated inter‐
199 faces will continue to work without warnings until January 2005.
200 As of January 2005, programs that use the deprecated interfaces will
202 continue to work, but they will generate mandatory warnings. Those
203 warnings will persist until April 2005.
204 As of April 2005 the mandatory warnings will be upgraded to mandatory
206 errors. Support for the deprecated interfaces will be removed
207 entirely.
208
210 POE::Component::Client::DNS is Copyright 1999-2004 by Rocco Caputo.
211 All rights are reserved. POE::Component::Client::DNS is free software;
212 you may redistribute it and/or modify it under the same terms as Perl
213 itself.
214 Postback arguments were contributed by tag.
216 Rocco may be contacted by e-mail via rcaputo@cpan.org.
218perl v5.8.8 2007-01-06 DNS(3)