Debian Codegraph @

README

raw
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