EV-ADNS/ADNS.pm

=head1 NAME

EV::ADNS - lightweight asynchronous dns queries using EV and libadns

=head1 SYNOPSIS

 use EV;
 use EV::ADNS;

 EV::ADNS::submit "example.com", EV::ADNS::r_addr, EV::ADNS::qf_cname_loose, sub {
    my ($status, $expires, @a) = @_;
    warn $a[0]; # "127.13.166.3" etc.
 };

 EV::run;

=head1 DESCRIPTION

This is a simple interface to libadns (asynchronous dns) that
integrates well and automatically into the EV event loop. The
documentation for libadns is vital to understand this module, see
L<http://www.chiark.greenend.org.uk/~ian/adns/>.

You can use it only with EV (directly or indirectly, e.g. via
L<Glib::EV>). Apart from loading and using the C<submit> function you need
not do anything (except run an EV event loop).

=head1 OVERVIEW

All the constants/enums from F<adns.h> are available in the EV::ADNS
namespace, without the C<adns_> prefix, i.e. C<adns_r_a> becomes
C<EV::ADNS::r_a> and so on.

=head1 FUNCTIONS

=over 4

=item $query = EV::ADNS::submit "domain", $rrtype, $flags, $cb

Submits a new request to be handled. See the C<adns_submit> C function
description for more details. The function optionally returns a query
object which can be used to cancel an in-progress request. You do not need
to store the query object, even if you ignore it, the query will proceed.

The callback will be invoked with a result status, the time the resource
record validity expires and zero or more resource records, one scalar per
result record. Example:

   sub adns_cb {
      my ($status, $expires, @rr) = @_;
      if ($status == EV::ADNS::s_ok) {
         use JSON::XS;
         warn encode_json \@rr;
      }
   }

The format of result records varies considerably, here is some cursory
documentation of how each record will look like, depending on the query
type:

=over 4

=item EV::ADNS::r_addr

An IPv4 and/or IPV6 address in string form.

=item EV::ADNS::r_a

An IPv4 address in dotted quad (string) form.

=item EV::ADNS::r_aaaa

An IPv6 address in string form.

=item EV::ADNS::r_ns_raw, EV::ADNS::r_cname, EV::ADNS::r_ptr, EV::ADNS::r_ptr_raw

The resource record as a simple string.

=item EV::ADNS::r_txt

An arrayref of strings (usually one string per record).

=item EV::ADNS::r_ns

A "host address", a hostname with any number of pre-resolved addresses
(hint records).

The record will be an arrayref with domainname, adns status and any number
of associated addresses: C<< ["domain", adns_status, addr...] >>.

=item EV::ADNS::r_hinfo

An arrayref consisting of the two strings.

=item EV::ADNS::r_rp, EV::ADNS::r_rp_raw

An arrayref with two strings.

=item EV::ADNS::r_mx

An arrayref consisting of the priority and a "host address" (see
C<EV::ADNS::r_ns>). Example:

   [10, [["alt3.aspmx.l.google.com", 0, "64.233.189.27", "2404:6800:4008:c07::1a"]]]

=item EV::ADNS::r_mx_raw

An arrayref consisting of the priority and the hostname, e.g. C<[10,
"mail.example.com"]>.

=item EV::ADNS::r_soa, EV::ADNS::r_soa_raw

An arrayref consisting of the primary nameserver, admin name, serial,
refresh, retry expire and minimum times, e.g.:

  ["ns.example.net", "hostmaster@example.net", 2000001102, 86400, 21600, 2592000, 172800]

The "raw" form doesn't mangle the e-mail address.

=item EV::ADNS::r_srv_raw

An arrayref consisting of the priority, weight, port and hostname, e.g.:

   [10, 10, 5060, "sip1.example.net"]

=item EV::ADNS::r_srv

The same as C<EV::ADNS::r_srv_raw>, but the hostname is replaced by a "host
address" (see C<EV::ADNS::r_ns>).

=item EV::ADNS::r_unknown

A single octet string with the raw contents.

=item anything else

Currently C<undef>.

=back

=item $query->cancel

Cancels a request that is in progress.

=item EV::ADNS::reinit $flags_or_undef, $resolvdata_or_undef

Cancels all outstanding queries, frees all adns state and reinitialises
it. It is highly recommended to only call this when there are no
outstanding requests.

The first argument is the set of init flags to use, or C<undef>, in which
case EV::ADNS uses it's default flag set.

The second argument can be missing or C<undef>; in which case the normal
initialisation is done (such as reading the F<resolv.conf>), or it might
be a stirng, in which case no config files or environment variables will
be read and the given string will be interpreted as the F<resolv.conf>
contents.

=back

=cut

package EV::ADNS;

use Carp ();
use EV ();

BEGIN {
   $VERSION = '3.0';

   require XSLoader;
   XSLoader::load (EV::ADNS, $VERSION);
}

=head1 SEE ALSO

L<EV>, L<Net::ADNS> another interface to adns, maybe better, but without
real support to integrate it into other event loops.

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

1

Revision:	1.17
Committed:	Sat Oct 17 02:38:45 2015 UTC (10 years, 10 months ago) by root
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.16:	+6 -5 lines
Log Message:	* empty log message *
#	Content
1	=head1 NAME
2
3	EV::ADNS - lightweight asynchronous dns queries using EV and libadns
4
5	=head1 SYNOPSIS
6
7	use EV;
8	use EV::ADNS;
9
10	EV::ADNS::submit "example.com", EV::ADNS::r_addr, EV::ADNS::qf_cname_loose, sub {
11	my ($status, $expires, @a) = @_;
12	warn $a[0]; # "127.13.166.3" etc.
13	};
14
15	EV::run;
16
17	=head1 DESCRIPTION
18
19	This is a simple interface to libadns (asynchronous dns) that
20	integrates well and automatically into the EV event loop. The
21	documentation for libadns is vital to understand this module, see
22	L<http://www.chiark.greenend.org.uk/~ian/adns/>.
23
24	You can use it only with EV (directly or indirectly, e.g. via
25	L<Glib::EV>). Apart from loading and using the C<submit> function you need
26	not do anything (except run an EV event loop).
27
28	=head1 OVERVIEW
29
30	All the constants/enums from F<adns.h> are available in the EV::ADNS
31	namespace, without the C<adns_> prefix, i.e. C<adns_r_a> becomes
32	C<EV::ADNS::r_a> and so on.
33
34	=head1 FUNCTIONS
35
36	=over 4
37
38	=item $query = EV::ADNS::submit "domain", $rrtype, $flags, $cb
39
40	Submits a new request to be handled. See the C<adns_submit> C function
41	description for more details. The function optionally returns a query
42	object which can be used to cancel an in-progress request. You do not need
43	to store the query object, even if you ignore it, the query will proceed.
44
45	The callback will be invoked with a result status, the time the resource
46	record validity expires and zero or more resource records, one scalar per
47	result record. Example:
48
49	sub adns_cb {
50	my ($status, $expires, @rr) = @_;
51	if ($status == EV::ADNS::s_ok) {
52	use JSON::XS;
53	warn encode_json \@rr;
54	}
55	}
56
57	The format of result records varies considerably, here is some cursory
58	documentation of how each record will look like, depending on the query
59	type:
60
61	=over 4
62
63	=item EV::ADNS::r_addr
64
65	An IPv4 and/or IPV6 address in string form.
66
67	=item EV::ADNS::r_a
68
69	An IPv4 address in dotted quad (string) form.
70
71	=item EV::ADNS::r_aaaa
72
73	An IPv6 address in string form.
74
75	=item EV::ADNS::r_ns_raw, EV::ADNS::r_cname, EV::ADNS::r_ptr, EV::ADNS::r_ptr_raw
76
77	The resource record as a simple string.
78
79	=item EV::ADNS::r_txt
80
81	An arrayref of strings (usually one string per record).
82
83	=item EV::ADNS::r_ns
84
85	A "host address", a hostname with any number of pre-resolved addresses
86	(hint records).
87
88	The record will be an arrayref with domainname, adns status and any number
89	of associated addresses: C<< ["domain", adns_status, addr...] >>.
90
91	=item EV::ADNS::r_hinfo
92
93	An arrayref consisting of the two strings.
94
95	=item EV::ADNS::r_rp, EV::ADNS::r_rp_raw
96
97	An arrayref with two strings.
98
99	=item EV::ADNS::r_mx
100
101	An arrayref consisting of the priority and a "host address" (see
102	C<EV::ADNS::r_ns>). Example:
103
104	[10, [["alt3.aspmx.l.google.com", 0, "64.233.189.27", "2404:6800:4008:c07::1a"]]]
105
106	=item EV::ADNS::r_mx_raw
107
108	An arrayref consisting of the priority and the hostname, e.g. C<[10,
109	"mail.example.com"]>.
110
111	=item EV::ADNS::r_soa, EV::ADNS::r_soa_raw
112
113	An arrayref consisting of the primary nameserver, admin name, serial,
114	refresh, retry expire and minimum times, e.g.:
115
116	["ns.example.net", "hostmaster@example.net", 2000001102, 86400, 21600, 2592000, 172800]
117
118	The "raw" form doesn't mangle the e-mail address.
119
120	=item EV::ADNS::r_srv_raw
121
122	An arrayref consisting of the priority, weight, port and hostname, e.g.:
123
124	[10, 10, 5060, "sip1.example.net"]
125
126	=item EV::ADNS::r_srv
127
128	The same as C<EV::ADNS::r_srv_raw>, but the hostname is replaced by a "host
129	address" (see C<EV::ADNS::r_ns>).
130
131	=item EV::ADNS::r_unknown
132
133	A single octet string with the raw contents.
134
135	=item anything else
136
137	Currently C<undef>.
138
139	=back
140
141	=item $query->cancel
142
143	Cancels a request that is in progress.
144
145	=item EV::ADNS::reinit $flags_or_undef, $resolvdata_or_undef
146
147	Cancels all outstanding queries, frees all adns state and reinitialises
148	it. It is highly recommended to only call this when there are no
149	outstanding requests.
150
151	The first argument is the set of init flags to use, or C<undef>, in which
152	case EV::ADNS uses it's default flag set.
153
154	The second argument can be missing or C<undef>; in which case the normal
155	initialisation is done (such as reading the F<resolv.conf>), or it might
156	be a stirng, in which case no config files or environment variables will
157	be read and the given string will be interpreted as the F<resolv.conf>
158	contents.
159
160	=back
161
162	=cut
163
164	package EV::ADNS;
165
166	use Carp ();
167	use EV ();
168
169	BEGIN {
170	$VERSION = '3.0';
171
172	require XSLoader;
173	XSLoader::load (EV::ADNS, $VERSION);
174	}
175
176	=head1 SEE ALSO
177
178	L<EV>, L<Net::ADNS> another interface to adns, maybe better, but without
179	real support to integrate it into other event loops.
180
181	=head1 AUTHOR
182
183	Marc Lehmann <schmorp@schmorp.de>
184	http://home.schmorp.de/
185
186	=cut
187
188	1
189