EV-ADNS/ADNS.pm

=head1 NAME

EV::ADNS - 

=head1 SYNOPSIS

 use EV::ADNS;

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

=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 to_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::rr_a

An IPv4 address in dotted quad (string) form.

=item adns_r_ns_raw, adns_r_cname, adns_r_ptr, adns_r_ptr_raw

The resource record as a simple string.

=item adns_r_txt

An arrayref of strings.

=item 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 adns_r_hinfo

An arrayref consisting of the two strings.

=item adns_r_rp, adns_r_rp_raw

An arrayref with two strings.

=item adns_r_mx

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

   [10,"mail10.example.com"]

=item adns_r_mx_raw:

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

=item adns_r_soa, 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 adns_r_srv_raw

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

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

=item adns_r_srv

The same as C<adns_r_srv_raw>, but the hostname is replaced by a "host
address" (see C<adns_r_ns>).

=item 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 = '0.1';

   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.2
Committed:	Sat Dec 1 21:29:08 2007 UTC (18 years, 9 months ago) by root
Branch:	MAIN
Changes since 1.1:	+129 -4 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			EV::ADNS -
4
5			=head1 SYNOPSIS
6
7			use EV::ADNS;
8
9	root	1.2	EV::ADNS::submit "example.com", EV::ADNS::r_a, 0, sub {
10			my ($status, $expires, @a) = @_;
11			warn $a[0]; # "127.13.166.3" etc.
12			};
13
14	root	1.1	=head1 DESCRIPTION
15
16	root	1.2	This is a simple interface to libadns (asynchronous dns) that
17			integrates well and automatically into the EV event loop. The
18			documentation for libadns is vital to understand this module, see
19			L<http://www.chiark.greenend.org.uk/~ian/adns/>.
20
21			You can use it only with EV (directly or indirectly, e.g. via
22			L<Glib::EV>). Apart from loading and using the C<submit> function you need
23			not do anything (except run an EV event loop).
24
25			=head1 OVERVIEW
26
27			All the constants/enums from F<adns.h> are available in the EV::ADNS
28			namespace, without the C<adns_> prefix, e.g. C<adns_r_a> becomes
29			C<EV::ADNS::r_a>, C<adns__qtf_deref> becomes C<EV::ADNS::_qtf_deref> and
30			so on.
31
32			=head1 FUNCTIONS
33
34			=over 4
35
36			=item $query = EV::ADNS::submit "domain", $rrtype, $flags, $cb
37
38			Submits a new request to be handled. See the C<adns_submit> C function
39			description for more details. The function optionally returns a query
40			object which can be used to cancel an in-progress request. You do not need
41			to store the query object, even if you ignore it the query will proceed.
42
43			The callback will be invoked with a result status, the time the resource
44			record validity expires and zero or more resource records, one scalar per
45			result record. Example:
46
47			sub adns_cb {
48			my ($status, $expires, @rr) = @_;
49			if ($status == EV::ADNS::s_ok) {
50			use JSON::XS;
51			warn to_json \@rr;
52			}
53			}
54
55			The format of result records varies considerably, here is some cursory
56			documentation of how each record will look like, depending on the query
57			type:
58
59			=over 4
60
61			=item EV::ADNS::rr_a
62
63			An IPv4 address in dotted quad (string) form.
64
65			=item adns_r_ns_raw, adns_r_cname, adns_r_ptr, adns_r_ptr_raw
66
67			The resource record as a simple string.
68
69			=item adns_r_txt
70
71			An arrayref of strings.
72
73			=item adns_r_ns
74
75			A "host address", a hostname with any number of addresses (hint records).
76
77			Currently only the hostname will be stored, so this is alway an arrayref
78			with a single element of the hostname. Future versions might add
79			additional address entries.
80
81			=item adns_r_hinfo
82
83			An arrayref consisting of the two strings.
84
85			=item adns_r_rp, adns_r_rp_raw
86
87			An arrayref with two strings.
88
89			=item adns_r_mx
90
91			An arrayref consisting of the priority and a "host address" (see
92			C<adns_r_ns>). Example:
93
94			[10,"mail10.example.com"]
95
96			=item adns_r_mx_raw:
97
98			An arrayref consisting of the priority and the hostname, e.g. C<[10,
99			"mail.example.com"]>.
100
101			=item adns_r_soa, adns_r_soa_raw
102
103			An arrayref consisting of the primary nameserver, admin name, serial,
104			refresh, retry expire and minimum times, e.g.:
105
106			["ns.example.net","hostmaster@example.net",2000001102,86400,21600,2592000,172800]
107
108			The "raw" form doesn't mangle the e-mail address.
109
110			=item adns_r_srv_raw
111
112			An arrayref consisting of the priority, weight, port and hostname, e.g.:
113
114			[10,10,5060,"sip1.example.net"]
115
116			=item adns_r_srv
117
118			The same as C<adns_r_srv_raw>, but the hostname is replaced by a "host
119			address" (see C<adns_r_ns>).
120
121			=item adns_r_unknown
122
123			A single octet string with the raw contents.
124
125			=item anything else
126
127			Currently C<undef>.
128
129			=back
130
131			=item $query->cancel
132
133			Cancels a request that is in progress.
134
135			=back
136
137	root	1.1	=cut
138
139			package EV::ADNS;
140
141			use Carp ();
142			use EV ();
143
144			BEGIN {
145	root	1.2	$VERSION = '0.1';
146	root	1.1
147			require XSLoader;
148			XSLoader::load (EV::ADNS, $VERSION);
149			}
150
151			=head1 SEE ALSO
152
153	root	1.2	L<EV>, L<Net::ADNS> another interface to adns, maybe better, but without
154			real support to integrate it into other event loops.
155	root	1.1
156			=head1 AUTHOR
157
158			Marc Lehmann <schmorp@schmorp.de>
159			http://home.schmorp.de/
160
161			=cut
162
163			1
164