POE::Component::Client::DNS(3pm)

1POE::Component::Client:U:sDeNrS(C3o)ntributed Perl DocumPeOnEt:a:tCioomnponent::Client::DNS(3)
2
3
4

NAME

6       POE::Component::Client::DNS - non-blocking, parallel DNS client
7

VERSION

9       version 1.054
10

SYNOPSIS

12         use POE qw(Component::Client::DNS);
13
14         my $named = POE::Component::Client::DNS->spawn(
15           Alias => "named"
16         );
17
18         POE::Session->create(
19           inline_states  => {
20             _start   => \&start_tests,
21             response => \&got_response,
22           }
23         );
24
25         POE::Kernel->run();
26         exit;
27
28         sub start_tests {
29           my $response = $named->resolve(
30             event   => "response",
31             host    => "localhost",
32             context => { },
33           );
34           if ($response) {
35             $_[KERNEL]->yield(response => $response);
36           }
37         }
38
39         sub got_response {
40           my $response = $_[ARG0];
41           my @answers = $response->{response}->answer();
42
43           foreach my $answer (@answers) {
44             print(
45               "$response->{host} = ",
46               $answer->type(), " ",
47               $answer->rdatastr(), "\n"
48             );
49           }
50         }
51

DESCRIPTION

53       POE::Component::Client::DNS provides non-blocking, parallel DNS
54       requests via Net::DNS.  Using POE, it allows other tasks to run while
55       waiting for name servers to respond.
56
57       For simple name resolution, including smart handling of IPv6 names,
58       please see POE::Component::Resolver instead.
59

PUBLIC METHODS

61       spawn
62         A program must spawn at least one POE::Component::Client::DNS
63         instance before it can perform background DNS requests.  Each
64         instance represents a connection to one or more name servers.  If a
65         program only needs to request DNS requests from one server, then you
66         only need one POE::Component::Client::DNS instance.
67
68         As of version 0.98 you can override the default timeout per request.
69         From this point forward there is no need to spawn multiple instances
70         to affect different timeouts for each request.
71
72         PoCo::Client::DNS's "spawn" method takes a few named parameters:
73
74         Alias sets the component's alias.  Requests will be posted to this
75         alias.  The component's alias defaults to "resolver" if one is not
76         provided.  Programs spawning more than one DNS client component must
77         specify aliases for N-1 of them, otherwise alias collisions will
78         occur.
79
80           Alias => $session_alias,  # defaults to "resolver"
81
82         Timeout sets the component's default timeout.  The timeout may be
83         overridden per request.  See the "request" event, later on.  If no
84         Timeout is set, the component will wait 90 seconds per request by
85         default.
86
87         Timeouts may be set to real numbers.  Timeouts are more accurate if
88         you have Time::HiRes installed.  POE (and thus this component) will
89         use Time::HiRes automatically if it's available.
90
91           Timeout => $seconds_to_wait,  # defaults to 90
92
93         Nameservers holds a reference to a list of name servers to try.  The
94         list is passed directly to Net::DNS::Resolver's nameservers() method.
95         By default, POE::Component::Client::DNS will query the name servers
96         that appear in /etc/resolv.conf or its equivalent.
97
98           Nameservers => \@name_servers,  # defaults to /etc/resolv.conf's
99
100         HostsFile (optional) holds the name of a specific hosts file to use
101         for resolving hardcoded addresses.  By default, it looks for a file
102         named /etc/hosts.
103
104         On Windows systems, it may look in the following other places:
105
106           $ENV{SystemRoot}\System32\Drivers\Etc\hosts
107           $ENV{SystemRoot}\System\Drivers\Etc\hosts
108           $ENV{SystemRoot}\hosts
109
110       resolve
111         resolve() requests the component to resolve a host name.  It will
112         return a hash reference (described in RESPONSE MESSAGES, below) if it
113         can honor the request immediately (perhaps from a cache).  Otherwise
114         it returns undef if a resolver must be consulted asynchronously.
115
116         Requests are passed as a list of named fields.
117
118           $resolver->resolve(
119             class       => $dns_record_class,  # defaults to "IN"
120             type        => $dns_record_type,   # defaults to "A"
121             host        => $request_host,      # required
122             context     => $request_context,   # required
123             event       => $response_event,    # required
124             timeout     => $request_timeout,   # defaults to spawn()'s Timeout
125             nameservers => $nameservers,       # defaults to $resolver's Nameservers
126           );
127
128         The "class" and "type" fields specify what kind of information to
129         return about a host.  Most of the time internet addresses are
130         requested for host names, so the class and type default to "IN"
131         (internet) and "A" (address), respectively.
132
133         The "host" field designates the host to look up.  It is required.
134
135         The "event" field tells the component which event to send back when a
136         response is available.  It is required, but it will not be used if
137         resolve() can immediately return a cached response.
138
139         "timeout" tells the component how long to wait for a response to this
140         request.  It defaults to the "Timeout" given at spawn() time.
141
142         "context" includes some external data that links responses back to
143         their requests.  The context data is provided by the program that
144         uses POE::Component::Client::DNS.  The component will pass the
145         context back to the program without modification.  The "context"
146         parameter is required, and may contain anything that fits in a
147         scalar.
148
149       shutdown
150         shutdown() causes the component to terminate gracefully. It will
151         finish serving pending requests then close down.
152
153       get_resolver
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

RESPONSE MESSAGES

163       POE::Component::Client::DNS responds in one of two ways.  Its resolve()
164       method will return a response immediately if it can be found in the
165       component's cache.  Otherwise the component posts the response back in
166       $_[ARG0].  In either case, the response is a hash reference containing
167       the same fields:
168
169         host     => $request_host,
170         type     => $request_type,
171         class    => $request_class,
172         context  => $request_context,
173         response => $net_dns_packet,
174         error    => $net_dns_error,
175
176       The "host", "type", "class", and "context" response fields are
177       identical to those given in the request message.
178
179       "response" contains a Net::DNS::Packet object on success or undef if
180       the lookup failed.  The Net::DNS::Packet object describes the response
181       to the program's request.  It may contain several DNS records.  Please
182       consult Net::DNS and Net::DNS::Packet for more information.
183
184       "error" contains a description of any error that has occurred.  It is
185       only valid if "response" is undefined.
186

DEPRECATIONS

198       The older, list-based interfaces are no longer documented as of version
199       0.98.  They are being phased out.  The method-based interface, first
200       implementedin version 0.98, will replace the deprecated interfaces
201       after a six-month phase-out period.
202
203       Version 0.98 was released in October of 2004.  The deprecated
204       interfaces will continue to work without warnings until January 2005.
205
206       As of January 2005, programs that use the deprecated interfaces will
207       continue to work, but they will generate mandatory warnings.  Those
208       warnings will persist until April 2005.
209
210       As of April 2005 the mandatory warnings will be upgraded to mandatory
211       errors.  Support for the deprecated interfaces will be removed
212       entirely.
213
214       As of late January 2011, POE::Component::Resolver provides basic system
215       resolver support, including IPv6 and mDNS if your resolver's configured
216       ot use it.  The use of POE::Component::Client::DNS for basic resolution
217       is deprecated, however it's still the best option for actual DNS server
218       requests.
219

BUG TRACKER

221       https://rt.cpan.org/Dist/Display.html?Queue=POE-Component-Client-DNS
222

REPOSITORY

224       http://github.com/rcaputo/poe-component-client-dns
225

OTHER RESOURCES

227       http://search.cpan.org/dist/POE-Component-Client-DNS/
228

AUTHOR & COPYRIGHTS

230       POE::Component::Client::DNS is Copyright 1999-2009 by Rocco Caputo.
231       All rights are reserved.  POE::Component::Client::DNS is free software;
232       you may redistribute it and/or modify it under the same terms as Perl
233       itself.
234
235       Postback arguments were contributed by tag.
236
237
238
239perl v5.38.0                      2023-07-21    POE::Component::Client::DNS(3)