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.4 by root, Sat Dec 1 22:36:10 2007 UTC vs.
Revision 1.16 by root, Sat Oct 17 00:01:53 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;
8 use EV::ADNS; 8 use EV::ADNS;
9 9
10 EV::ADNS::submit "example.com", EV::ADNS::r_a, 0, sub { 10 EV::ADNS::submit "example.com", EV::ADNS::r_addr, EV::ADNS::qf_cname_loose, sub {
11 my ($status, $expires, @a) = @_; 11 my ($status, $expires, @a) = @_;
12 warn $a[0]; # "127.13.166.3" etc. 12 warn $a[0]; # "127.13.166.3" etc.
13 }; 13 };
14 14
15 EV::loop; 15 EV::run;
16 16
17=head1 DESCRIPTION 17=head1 DESCRIPTION
18 18
19This is a simple interface to libadns (asynchronous dns) that 19This is a simple interface to libadns (asynchronous dns) that
20integrates well and automatically into the EV event loop. The 20integrates well and automatically into the EV event loop. The
… …
26not do anything (except run an EV event loop). 26not do anything (except run an EV event loop).
27 27
28=head1 OVERVIEW 28=head1 OVERVIEW
29 29
30All the constants/enums from F<adns.h> are available in the EV::ADNS 30All the constants/enums from F<adns.h> are available in the EV::ADNS
31namespace, without the C<adns_> prefix, e.g. C<adns_r_a> becomes 31namespace, without the C<adns_> prefix, i.e. C<adns_r_a> becomes
32C<EV::ADNS::r_a>, C<adns__qtf_deref> becomes C<EV::ADNS::_qtf_deref> and 32C<EV::ADNS::r_a> and so on.
33so on.
34 33
35=head1 FUNCTIONS 34=head1 FUNCTIONS
36 35
37=over 4 36=over 4
38 37
39=item $query = EV::ADNS::submit "domain", $rrtype, $flags, $cb 38=item $query = EV::ADNS::submit "domain", $rrtype, $flags, $cb
40 39
41Submits a new request to be handled. See the C<adns_submit> C function 40Submits a new request to be handled. See the C<adns_submit> C function
42description for more details. The function optionally returns a query 41description for more details. The function optionally returns a query
43object which can be used to cancel an in-progress request. You do not need 42object which can be used to cancel an in-progress request. You do not need
44to store the query object, even if you ignore it the query will proceed. 43to store the query object, even if you ignore it, the query will proceed.
45 44
46The callback will be invoked with a result status, the time the resource 45The callback will be invoked with a result status, the time the resource
47record validity expires and zero or more resource records, one scalar per 46record validity expires and zero or more resource records, one scalar per
48result record. Example: 47result record. Example:
49 48
50 sub adns_cb { 49 sub adns_cb {
51 my ($status, $expires, @rr) = @_; 50 my ($status, $expires, @rr) = @_;
52 if ($status == EV::ADNS::s_ok) { 51 if ($status == EV::ADNS::s_ok) {
53 use JSON::XS; 52 use JSON::XS;
54 warn to_json \@rr; 53 warn encode_json \@rr;
55 } 54 }
56 } 55 }
57 56
58The format of result records varies considerably, here is some cursory 57The format of result records varies considerably, here is some cursory
59documentation of how each record will look like, depending on the query 58documentation of how each record will look like, depending on the query
60type: 59type:
61 60
62=over 4 61=over 4
63 62
64=item EV::ADNS::rr_a 63=item EV::ADNS::r_addr
65 64
66An IPv4 address in dotted quad (string) form. 65IPv4 and/or IPV6 addresses in string form.
67 66
68=item adns_r_ns_raw, adns_r_cname, adns_r_ptr, adns_r_ptr_raw 67=item EV::ADNS::r_a
68
69IPv4 addresses in dotted quad (string) form.
70
71=item EV::ADNS::r_aaaa
72
73IPv6 addresses in string form.
74
75=item EV::ADNS::r_ns_raw, EV::ADNS::r_cname, EV::ADNS::r_ptr, EV::ADNS::r_ptr_raw
69 76
70The resource record as a simple string. 77The resource record as a simple string.
71 78
72=item adns_r_txt 79=item EV::ADNS::r_txt
73 80
74An arrayref of strings. 81An arrayref of strings.
75 82
76=item adns_r_ns 83=item EV::ADNS::r_ns
77 84
78A "host address", a hostname with any number of addresses (hint records). 85A "host address", a hostname with any number of addresses (hint records).
79 86
80Currently only the hostname will be stored, so this is alway an arrayref 87The record will be an arrayref with domainname, adns status and any number
81with a single element of the hostname. Future versions might add 88of associated addresses: C<< ["domain", adns_status, addr...] >>.
82additional address entries.
83 89
84=item adns_r_hinfo 90=item EV::ADNS::r_hinfo
85 91
86An arrayref consisting of the two strings. 92An arrayref consisting of the two strings.
87 93
88=item adns_r_rp, adns_r_rp_raw 94=item EV::ADNS::r_rp, EV::ADNS::r_rp_raw
89 95
90An arrayref with two strings. 96An arrayref with two strings.
91 97
92=item adns_r_mx 98=item EV::ADNS::r_mx
93 99
94An arrayref consisting of the priority and a "host address" (see 100An arrayref consisting of the priority and a "host address" (see
95C<adns_r_ns>). Example: 101C<EV::ADNS::r_ns>). Example:
96 102
97 [10,"mail10.example.com"] 103 [10, [["alt3.aspmx.l.google.com", 0, "64.233.189.27", "2404:6800:4008:c07::1a"]]]
98 104
99=item adns_r_mx_raw: 105=item EV::ADNS::r_mx_raw
100 106
101An arrayref consisting of the priority and the hostname, e.g. C<[10, 107An arrayref consisting of the priority and the hostname, e.g. C<[10,
102"mail.example.com"]>. 108"mail.example.com"]>.
103 109
104=item adns_r_soa, adns_r_soa_raw 110=item EV::ADNS::r_soa, EV::ADNS::r_soa_raw
105 111
106An arrayref consisting of the primary nameserver, admin name, serial, 112An arrayref consisting of the primary nameserver, admin name, serial,
107refresh, retry expire and minimum times, e.g.: 113refresh, retry expire and minimum times, e.g.:
108 114
109 ["ns.example.net","hostmaster@example.net",2000001102,86400,21600,2592000,172800] 115 ["ns.example.net", "hostmaster@example.net", 2000001102, 86400, 21600, 2592000, 172800]
110 116
111The "raw" form doesn't mangle the e-mail address. 117The "raw" form doesn't mangle the e-mail address.
112 118
113=item adns_r_srv_raw 119=item EV::ADNS::r_srv_raw
114 120
115An arrayref consisting of the priority, weight, port and hostname, e.g.: 121An arrayref consisting of the priority, weight, port and hostname, e.g.:
116 122
117 [10,10,5060,"sip1.example.net"] 123 [10, 10, 5060, "sip1.example.net"]
118 124
119=item adns_r_srv 125=item EV::ADNS::r_srv
120 126
121The same as C<adns_r_srv_raw>, but the hostname is replaced by a "host 127The same as C<EV::ADNS::r_srv_raw>, but the hostname is replaced by a "host
122address" (see C<adns_r_ns>). 128address" (see C<EV::ADNS::r_ns>).
123 129
124=item adns_r_unknown 130=item EV::ADNS::r_unknown
125 131
126A single octet string with the raw contents. 132A single octet string with the raw contents.
127 133
128=item anything else 134=item anything else
129 135
… …
133 139
134=item $query->cancel 140=item $query->cancel
135 141
136Cancels a request that is in progress. 142Cancels a request that is in progress.
137 143
144=item EV::ADNS::reinit $flags_or_undef, $resolvdata_or_undef
145
146Cancels all outstanding queries, frees all adns state and reinitialises
147it. It is highly recommended to only call this when there are no
148outstanding requests.
149
150The first argument is the set of init flags to use, or C<undef>, in which
151case EV::ADNS uses it's default flag set.
152
153The second argument can be missing or C<undef>; in which case the normal
154initialisation is done (such as reading the F<resolv.conf>), or it might
155be a stirng, in which case no config files or environment variables will
156be read and the given string will be interpreted as the F<resolv.conf>
157contents.
158
138=back 159=back
139 160
140=cut 161=cut
141 162
142package EV::ADNS; 163package EV::ADNS;
143 164
144use Carp (); 165use Carp ();
145use EV (); 166use EV ();
146 167
147BEGIN { 168BEGIN {
148 $VERSION = '0.2'; 169 $VERSION = '3.0';
149 170
150 require XSLoader; 171 require XSLoader;
151 XSLoader::load (EV::ADNS, $VERSION); 172 XSLoader::load (EV::ADNS, $VERSION);
152} 173}
153 174

Diff Legend

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