1POE::Component::Client:U:sDeNrS(C3o)ntributed Perl DocumPeOnEt:a:tCioomnponent::Client::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,
51 concurrent 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
138 context back to the program without modification. The "context"
139 parameter is required, and may contain anything that fits in a
140 scalar.
141 shutdown
143 shutdown() causes the component to terminate gracefully. It will
144 finish serving pending requests then close down.
145 get_resolver
147 POE::Component::Client::DNS uses a Net::DNS::Resolver object
148 internally. get_resolver() returns that object so it may be
149 interrogated or modified. See Net::DNS::Resolver for options.
150 Set the resolver to check on nonstandard port 1153:
152 $poco_client_dns->resolver()->port(1153);
154
156 POE::Component::Client::DNS responds in one of two ways. Its resolve()
157 method will return a response immediately if it can be found in the
158 component's cache. Otherwise the component posts the response back in
159 $_[ARG0]. In either case, the response is a hash reference containing
160 the same fields:
161 host => $request_host,
163 type => $request_type,
164 class => $request_class,
165 context => $request_context,
166 response => $net_dns_packet,
167 error => $net_dns_error,
168 The "host", "type", "class", and "context" response fields are
170 identical to those given in the request message.
171 "response" contains a Net::DNS::Packet object on success or undef if
173 the lookup failed. The Net::DNS::Packet object describes the response
174 to the program's request. It may contain several DNS records. Please
175 consult Net::DNS and Net::DNS::Packet for more information.
176 "error" contains a description of any error that has occurred. It is
178 only valid if "response" is undefined.
179
181 POE - POE::Component::Client::DNS builds heavily on POE.
182 Net::DNS - This module uses Net::DNS internally.
184 Net::DNS::Packet - Responses are returned as Net::DNS::Packet objects.
186
188 The older, list-based interfaces are no longer documented as of version
189 0.98. They are being phased out. The method-based interface, first
190 implementedin version 0.98, will replace the deprecated interfaces
191 after a six-month phase-out period.
192 Version 0.98 was released in October of 2004. The deprecated
194 interfaces will continue to work without warnings until January 2005.
195 As of January 2005, programs that use the deprecated interfaces will
197 continue to work, but they will generate mandatory warnings. Those
198 warnings will persist until April 2005.
199 As of April 2005 the mandatory warnings will be upgraded to mandatory
201 errors. Support for the deprecated interfaces will be removed
202 entirely.
203
205 https://rt.cpan.org/Dist/Display.html?Queue=POE-Component-Client-DNS
206
208 http://github.com/rcaputo/poe-component-client-dns
209
211 http://search.cpan.org/dist/POE-Component-Client-DNS/
212
214 POE::Component::Client::DNS is Copyright 1999-2009 by Rocco Caputo.
215 All rights are reserved. POE::Component::Client::DNS is free software;
216 you may redistribute it and/or modify it under the same terms as Perl
217 itself.
218 Postback arguments were contributed by tag.
220
222 Hey! The above document had some coding errors, which are explained
223 below:
224 Around line 716:
226 You forgot a '=back' before '=head1'
227perl v5.12.0 2009-10-14 POE::Component::Client::DNS(3)