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, 0, sub {
    my ($status, $expires, @a) = @_;
    warn $a[0]; # "127.13.166.3" etc.
 };

 EV::loop;

=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, e.g. C<adns_r_a> becomes
C<EV::ADNS::r_a>, C<adns__qtf_deref> becomes C<EV::ADNS::_qtf_deref> 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).

Currently only the hostname will be stored, so this is alway an arrayref
with a single element of the hostname. Future versions might add
additional address entries.

=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, "mail10.example.com"]

=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.

=back

=cut

package EV::ADNS;

use Carp ();
use EV ();

BEGIN {
   $VERSION = '2.2';

   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.12
Committed:	Fri May 7 21:42:36 2010 UTC (14 years, 1 month ago) by root
Branch:	MAIN
CVS Tags:	rel-2_2
Changes since 1.11:	+1 -1 lines
Log Message:	2.2
#	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.11	EV::ADNS::submit "example.com", EV::ADNS::r_addr, 0, sub {
11	root	1.2	my ($status, $expires, @a) = @_;
12			warn $a[0]; # "127.13.166.3" etc.
13			};
14
15	root	1.3	EV::loop;
16
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			namespace, without the C<adns_> prefix, e.g. C<adns_r_a> becomes
32			C<EV::ADNS::r_a>, C<adns__qtf_deref> becomes C<EV::ADNS::_qtf_deref> and
33			so on.
34
35			=head1 FUNCTIONS
36
37			=over 4
38
39			=item $query = EV::ADNS::submit "domain", $rrtype, $flags, $cb
40
41			Submits a new request to be handled. See the C<adns_submit> C function
42			description for more details. The function optionally returns a query
43			object which can be used to cancel an in-progress request. You do not need
44			to store the query object, even if you ignore it the query will proceed.
45
46			The callback will be invoked with a result status, the time the resource
47			record validity expires and zero or more resource records, one scalar per
48			result record. Example:
49
50			sub adns_cb {
51			my ($status, $expires, @rr) = @_;
52			if ($status == EV::ADNS::s_ok) {
53			use JSON::XS;
54	root	1.7	warn encode_json \@rr;
55	root	1.2	}
56			}
57
58			The format of result records varies considerably, here is some cursory
59			documentation of how each record will look like, depending on the query
60			type:
61
62			=over 4
63
64	root	1.11	=item EV::ADNS::r_a, EV::ADNS::r_addr
65	root	1.2
66			An IPv4 address in dotted quad (string) form.
67
68	root	1.5	=item EV::ADNS::r_ns_raw, EV::ADNS::r_cname, EV::ADNS::r_ptr, EV::ADNS::r_ptr_raw
69	root	1.2
70			The resource record as a simple string.
71
72	root	1.5	=item EV::ADNS::r_txt
73	root	1.2
74			An arrayref of strings.
75
76	root	1.5	=item EV::ADNS::r_ns
77	root	1.2
78			A "host address", a hostname with any number of addresses (hint records).
79
80			Currently only the hostname will be stored, so this is alway an arrayref
81			with a single element of the hostname. Future versions might add
82			additional address entries.
83
84	root	1.5	=item EV::ADNS::r_hinfo
85	root	1.2
86			An arrayref consisting of the two strings.
87
88	root	1.5	=item EV::ADNS::r_rp, EV::ADNS::r_rp_raw
89	root	1.2
90			An arrayref with two strings.
91
92	root	1.5	=item EV::ADNS::r_mx
93	root	1.2
94			An arrayref consisting of the priority and a "host address" (see
95	root	1.5	C<EV::ADNS::r_ns>). Example:
96	root	1.2
97	root	1.5	[10, "mail10.example.com"]
98	root	1.2
99	root	1.5	=item EV::ADNS::r_mx_raw
100	root	1.2
101			An arrayref consisting of the priority and the hostname, e.g. C<[10,
102			"mail.example.com"]>.
103
104	root	1.5	=item EV::ADNS::r_soa, EV::ADNS::r_soa_raw
105	root	1.2
106			An arrayref consisting of the primary nameserver, admin name, serial,
107			refresh, retry expire and minimum times, e.g.:
108
109	root	1.5	["ns.example.net", "hostmaster@example.net", 2000001102, 86400, 21600, 2592000, 172800]
110	root	1.2
111			The "raw" form doesn't mangle the e-mail address.
112
113	root	1.5	=item EV::ADNS::r_srv_raw
114	root	1.2
115			An arrayref consisting of the priority, weight, port and hostname, e.g.:
116
117	root	1.5	[10, 10, 5060, "sip1.example.net"]
118	root	1.2
119	root	1.5	=item EV::ADNS::r_srv
120	root	1.2
121	root	1.5	The same as C<EV::ADNS::r_srv_raw>, but the hostname is replaced by a "host
122			address" (see C<EV::ADNS::r_ns>).
123	root	1.2
124	root	1.5	=item EV::ADNS::r_unknown
125	root	1.2
126			A single octet string with the raw contents.
127
128			=item anything else
129
130			Currently C<undef>.
131
132			=back
133
134			=item $query->cancel
135
136			Cancels a request that is in progress.
137
138			=back
139
140	root	1.1	=cut
141
142			package EV::ADNS;
143
144			use Carp ();
145			use EV ();
146
147			BEGIN {
148	root	1.12	$VERSION = '2.2';
149	root	1.1
150			require XSLoader;
151			XSLoader::load (EV::ADNS, $VERSION);
152			}
153
154			=head1 SEE ALSO
155
156	root	1.2	L<EV>, L<Net::ADNS> another interface to adns, maybe better, but without
157			real support to integrate it into other event loops.
158	root	1.1
159			=head1 AUTHOR
160
161			Marc Lehmann <schmorp@schmorp.de>
162			http://home.schmorp.de/
163
164			=cut
165
166			1
167