ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV-ADNS/ADNS.pm
(Generate patch)

Comparing EV-ADNS/ADNS.pm (file contents):
Revision 1.1 by root, Sat Dec 1 13:53:10 2007 UTC vs.
Revision 1.17 by root, Sat Oct 17 02:38:45 2015 UTC

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

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines