cvsroot/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_a, EV::ADNS::r_addr

An IPv4 address in dotted quad (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.

=item EV::ADNS::r_ns

A "host address", a hostname with any number of 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 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 must currently be specified as C<undef>.

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.14
Committed:	Fri Oct 16 22:58:35 2015 UTC (8 years, 8 months ago) by root
Branch:	MAIN
CVS Tags:	rel-3_0
Changes since 1.13:	+23 -11 lines
Log Message:	3.0
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3	root	1.5	EV::ADNS - lightweight asynchronous dns queries using EV and libadns
4	root	1.1
5			=head1 SYNOPSIS
6
7	root	1.3	use EV;
8	root	1.1	use EV::ADNS;
9
10	root	1.14	EV::ADNS::submit "example.com", EV::ADNS::r_addr, EV::ADNS::qf_cname_loose, sub {
11	root	1.2	my ($status, $expires, @a) = @_;
12			warn $a[0]; # "127.13.166.3" etc.
13			};
14
15	root	1.14	EV::run;
16	root	1.3
17	root	1.1	=head1 DESCRIPTION
18
19	root	1.2	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	root	1.14	namespace, without the C<adns_> prefix, i.e. C<adns_r_a> becomes
32			C<EV::ADNS::r_a> and so on.
33	root	1.2
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	root	1.14	to store the query object, even if you ignore it, the query will proceed.
44	root	1.2
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	root	1.7	warn encode_json \@rr;
54	root	1.2	}
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	root	1.11	=item EV::ADNS::r_a, EV::ADNS::r_addr
64	root	1.2
65			An IPv4 address in dotted quad (string) form.
66
67	root	1.5	=item EV::ADNS::r_ns_raw, EV::ADNS::r_cname, EV::ADNS::r_ptr, EV::ADNS::r_ptr_raw
68	root	1.2
69			The resource record as a simple string.
70
71	root	1.5	=item EV::ADNS::r_txt
72	root	1.2
73			An arrayref of strings.
74
75	root	1.5	=item EV::ADNS::r_ns
76	root	1.2
77			A "host address", a hostname with any number of addresses (hint records).
78
79	root	1.14	The record will be an arrayref with domainname, adns status and any number
80			of associated addresses: C<< ["domain", adns_status, addr...] >>.
81	root	1.2
82	root	1.5	=item EV::ADNS::r_hinfo
83	root	1.2
84			An arrayref consisting of the two strings.
85
86	root	1.5	=item EV::ADNS::r_rp, EV::ADNS::r_rp_raw
87	root	1.2
88			An arrayref with two strings.
89
90	root	1.5	=item EV::ADNS::r_mx
91	root	1.2
92			An arrayref consisting of the priority and a "host address" (see
93	root	1.5	C<EV::ADNS::r_ns>). Example:
94	root	1.2
95	root	1.14	[10, [["alt3.aspmx.l.google.com", 0, "64.233.189.27", "2404:6800:4008:c07::1a"]]]
96	root	1.2
97	root	1.5	=item EV::ADNS::r_mx_raw
98	root	1.2
99			An arrayref consisting of the priority and the hostname, e.g. C<[10,
100			"mail.example.com"]>.
101
102	root	1.5	=item EV::ADNS::r_soa, EV::ADNS::r_soa_raw
103	root	1.2
104			An arrayref consisting of the primary nameserver, admin name, serial,
105			refresh, retry expire and minimum times, e.g.:
106
107	root	1.5	["ns.example.net", "hostmaster@example.net", 2000001102, 86400, 21600, 2592000, 172800]
108	root	1.2
109			The "raw" form doesn't mangle the e-mail address.
110
111	root	1.5	=item EV::ADNS::r_srv_raw
112	root	1.2
113			An arrayref consisting of the priority, weight, port and hostname, e.g.:
114
115	root	1.5	[10, 10, 5060, "sip1.example.net"]
116	root	1.2
117	root	1.5	=item EV::ADNS::r_srv
118	root	1.2
119	root	1.5	The same as C<EV::ADNS::r_srv_raw>, but the hostname is replaced by a "host
120			address" (see C<EV::ADNS::r_ns>).
121	root	1.2
122	root	1.5	=item EV::ADNS::r_unknown
123	root	1.2
124			A single octet string with the raw contents.
125
126			=item anything else
127
128			Currently C<undef>.
129
130			=back
131
132			=item $query->cancel
133
134			Cancels a request that is in progress.
135
136	root	1.14	=item EV::ADNS::reinit undef, $resolvdata_or_undef
137
138			Cancels all outstanding queries, frees all adns state and reinitialises
139			it. It is highly recommended to only call this when there are no
140			outstanding requests.
141
142			The first argument must currently be specified as C<undef>.
143
144			The second argument can be missing or C<undef>; in which case the normal
145			initialisation is done (such as reading the F<resolv.conf>), or it might
146			be a stirng, in which case no config files or environment variables will
147			be read and the given string will be interpreted as the F<resolv.conf>
148			contents.
149
150	root	1.2	=back
151
152	root	1.1	=cut
153
154			package EV::ADNS;
155
156			use Carp ();
157			use EV ();
158
159			BEGIN {
160	root	1.14	$VERSION = '3.0';
161	root	1.1
162			require XSLoader;
163			XSLoader::load (EV::ADNS, $VERSION);
164			}
165
166			=head1 SEE ALSO
167
168	root	1.2	L<EV>, L<Net::ADNS> another interface to adns, maybe better, but without
169			real support to integrate it into other event loops.
170	root	1.1
171			=head1 AUTHOR
172
173			Marc Lehmann <schmorp@schmorp.de>
174			http://home.schmorp.de/
175
176			=cut
177
178			1
179