1 | =head1 NAME |
1 | =head1 NAME |
2 | |
2 | |
3 | EV::ADNS - |
3 | EV::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 | |
19 | This is a simple interface to libadns (asynchronous dns) that |
19 | This is a simple interface to libadns (asynchronous dns) that |
20 | integrates well and automatically into the EV event loop. The |
20 | integrates well and automatically into the EV event loop. The |
… | |
… | |
26 | not do anything (except run an EV event loop). |
26 | not do anything (except run an EV event loop). |
27 | |
27 | |
28 | =head1 OVERVIEW |
28 | =head1 OVERVIEW |
29 | |
29 | |
30 | All the constants/enums from F<adns.h> are available in the EV::ADNS |
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 |
31 | namespace, without the C<adns_> prefix, i.e. C<adns_r_a> becomes |
32 | C<EV::ADNS::r_a>, C<adns__qtf_deref> becomes C<EV::ADNS::_qtf_deref> and |
32 | C<EV::ADNS::r_a> and so on. |
33 | so 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 | |
41 | Submits a new request to be handled. See the C<adns_submit> C function |
40 | 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 |
41 | 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 |
42 | 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. |
43 | to store the query object, even if you ignore it, the query will proceed. |
45 | |
44 | |
46 | The callback will be invoked with a result status, the time the resource |
45 | 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 |
46 | record validity expires and zero or more resource records, one scalar per |
48 | result record. Example: |
47 | result 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 | |
58 | The format of result records varies considerably, here is some cursory |
57 | The format of result records varies considerably, here is some cursory |
59 | documentation of how each record will look like, depending on the query |
58 | documentation of how each record will look like, depending on the query |
60 | type: |
59 | type: |
61 | |
60 | |
62 | =over 4 |
61 | =over 4 |
63 | |
62 | |
64 | =item EV::ADNS::rr_a |
63 | =item EV::ADNS::r_addr |
65 | |
64 | |
66 | An IPv4 address in dotted quad (string) form. |
65 | IPv4 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 | |
|
|
69 | IPv4 addresses in dotted quad (string) form. |
|
|
70 | |
|
|
71 | =item EV::ADNS::r_aaaa |
|
|
72 | |
|
|
73 | IPv6 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 | |
70 | The resource record as a simple string. |
77 | The resource record as a simple string. |
71 | |
78 | |
72 | =item adns_r_txt |
79 | =item EV::ADNS::r_txt |
73 | |
80 | |
74 | An arrayref of strings. |
81 | An arrayref of strings. |
75 | |
82 | |
76 | =item adns_r_ns |
83 | =item EV::ADNS::r_ns |
77 | |
84 | |
78 | A "host address", a hostname with any number of addresses (hint records). |
85 | A "host address", a hostname with any number of addresses (hint records). |
79 | |
86 | |
80 | Currently only the hostname will be stored, so this is alway an arrayref |
87 | The record will be an arrayref with domainname, adns status and any number |
81 | with a single element of the hostname. Future versions might add |
88 | of associated addresses: C<< ["domain", adns_status, addr...] >>. |
82 | additional address entries. |
|
|
83 | |
89 | |
84 | =item adns_r_hinfo |
90 | =item EV::ADNS::r_hinfo |
85 | |
91 | |
86 | An arrayref consisting of the two strings. |
92 | An 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 | |
90 | An arrayref with two strings. |
96 | An arrayref with two strings. |
91 | |
97 | |
92 | =item adns_r_mx |
98 | =item EV::ADNS::r_mx |
93 | |
99 | |
94 | An arrayref consisting of the priority and a "host address" (see |
100 | An arrayref consisting of the priority and a "host address" (see |
95 | C<adns_r_ns>). Example: |
101 | C<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 | |
101 | An arrayref consisting of the priority and the hostname, e.g. C<[10, |
107 | An 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 | |
106 | An arrayref consisting of the primary nameserver, admin name, serial, |
112 | An arrayref consisting of the primary nameserver, admin name, serial, |
107 | refresh, retry expire and minimum times, e.g.: |
113 | refresh, 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 | |
111 | The "raw" form doesn't mangle the e-mail address. |
117 | The "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 | |
115 | An arrayref consisting of the priority, weight, port and hostname, e.g.: |
121 | An 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 | |
121 | The same as C<adns_r_srv_raw>, but the hostname is replaced by a "host |
127 | The same as C<EV::ADNS::r_srv_raw>, but the hostname is replaced by a "host |
122 | address" (see C<adns_r_ns>). |
128 | address" (see C<EV::ADNS::r_ns>). |
123 | |
129 | |
124 | =item adns_r_unknown |
130 | =item EV::ADNS::r_unknown |
125 | |
131 | |
126 | A single octet string with the raw contents. |
132 | A 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 | |
136 | Cancels a request that is in progress. |
142 | Cancels a request that is in progress. |
137 | |
143 | |
|
|
144 | =item EV::ADNS::reinit undef, $resolvdata_or_undef |
|
|
145 | |
|
|
146 | Cancels all outstanding queries, frees all adns state and reinitialises |
|
|
147 | it. It is highly recommended to only call this when there are no |
|
|
148 | outstanding requests. |
|
|
149 | |
|
|
150 | The first argument must currently be specified as C<undef>. |
|
|
151 | |
|
|
152 | The second argument can be missing or C<undef>; in which case the normal |
|
|
153 | initialisation is done (such as reading the F<resolv.conf>), or it might |
|
|
154 | be a stirng, in which case no config files or environment variables will |
|
|
155 | be read and the given string will be interpreted as the F<resolv.conf> |
|
|
156 | contents. |
|
|
157 | |
138 | =back |
158 | =back |
139 | |
159 | |
140 | =cut |
160 | =cut |
141 | |
161 | |
142 | package EV::ADNS; |
162 | package EV::ADNS; |
143 | |
163 | |
144 | use Carp (); |
164 | use Carp (); |
145 | use EV (); |
165 | use EV (); |
146 | |
166 | |
147 | BEGIN { |
167 | BEGIN { |
148 | $VERSION = '0.1'; |
168 | $VERSION = '3.0'; |
149 | |
169 | |
150 | require XSLoader; |
170 | require XSLoader; |
151 | XSLoader::load (EV::ADNS, $VERSION); |
171 | XSLoader::load (EV::ADNS, $VERSION); |
152 | } |
172 | } |
153 | |
173 | |