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.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;
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
63=item EV::ADNS::r_addr
64
65An IPv4 and/or IPV6 address in string form.
66
64=item EV::ADNS::rr_a 67=item EV::ADNS::r_a
65 68
66An IPv4 address in dotted quad (string) form. 69An IPv4 address in dotted quad (string) form.
67 70
68=item adns_r_ns_raw, adns_r_cname, adns_r_ptr, adns_r_ptr_raw 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
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 (usually one string per record).
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 pre-resolved addresses
86(hint records).
79 87
80Currently only the hostname will be stored, so this is alway an arrayref 88The record will be an arrayref with domainname, adns status and any number
81with a single element of the hostname. Future versions might add 89of associated addresses: C<< ["domain", adns_status, addr...] >>.
82additional address entries.
83 90
84=item adns_r_hinfo 91=item EV::ADNS::r_hinfo
85 92
86An arrayref consisting of the two strings. 93An arrayref consisting of the two strings.
87 94
88=item adns_r_rp, adns_r_rp_raw 95=item EV::ADNS::r_rp, EV::ADNS::r_rp_raw
89 96
90An arrayref with two strings. 97An arrayref with two strings.
91 98
92=item adns_r_mx 99=item EV::ADNS::r_mx
93 100
94An arrayref consisting of the priority and a "host address" (see 101An arrayref consisting of the priority and a "host address" (see
95C<adns_r_ns>). Example: 102C<EV::ADNS::r_ns>). Example:
96 103
97 [10,"mail10.example.com"] 104 [10, [["alt3.aspmx.l.google.com", 0, "64.233.189.27", "2404:6800:4008:c07::1a"]]]
98 105
99=item adns_r_mx_raw: 106=item EV::ADNS::r_mx_raw
100 107
101An arrayref consisting of the priority and the hostname, e.g. C<[10, 108An arrayref consisting of the priority and the hostname, e.g. C<[10,
102"mail.example.com"]>. 109"mail.example.com"]>.
103 110
104=item adns_r_soa, adns_r_soa_raw 111=item EV::ADNS::r_soa, EV::ADNS::r_soa_raw
105 112
106An arrayref consisting of the primary nameserver, admin name, serial, 113An arrayref consisting of the primary nameserver, admin name, serial,
107refresh, retry expire and minimum times, e.g.: 114refresh, retry expire and minimum times, e.g.:
108 115
109 ["ns.example.net","hostmaster@example.net",2000001102,86400,21600,2592000,172800] 116 ["ns.example.net", "hostmaster@example.net", 2000001102, 86400, 21600, 2592000, 172800]
110 117
111The "raw" form doesn't mangle the e-mail address. 118The "raw" form doesn't mangle the e-mail address.
112 119
113=item adns_r_srv_raw 120=item EV::ADNS::r_srv_raw
114 121
115An arrayref consisting of the priority, weight, port and hostname, e.g.: 122An arrayref consisting of the priority, weight, port and hostname, e.g.:
116 123
117 [10,10,5060,"sip1.example.net"] 124 [10, 10, 5060, "sip1.example.net"]
118 125
119=item adns_r_srv 126=item EV::ADNS::r_srv
120 127
121The same as C<adns_r_srv_raw>, but the hostname is replaced by a "host 128The same as C<EV::ADNS::r_srv_raw>, but the hostname is replaced by a "host
122address" (see C<adns_r_ns>). 129address" (see C<EV::ADNS::r_ns>).
123 130
124=item adns_r_unknown 131=item EV::ADNS::r_unknown
125 132
126A single octet string with the raw contents. 133A single octet string with the raw contents.
127 134
128=item anything else 135=item anything else
129 136
… …
133 140
134=item $query->cancel 141=item $query->cancel
135 142
136Cancels a request that is in progress. 143Cancels a request that is in progress.
137 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
138=back 160=back
139 161
140=cut 162=cut
141 163
142package EV::ADNS; 164package EV::ADNS;
143 165
144use Carp (); 166use Carp ();
145use EV (); 167use EV ();
146 168
147BEGIN { 169BEGIN {
148 $VERSION = '0.2'; 170 $VERSION = '3.0';
149 171
150 require XSLoader; 172 require XSLoader;
151 XSLoader::load (EV::ADNS, $VERSION); 173 XSLoader::load (EV::ADNS, $VERSION);
152} 174}
153 175

Diff Legend

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