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::ADNS; |
8 | use EV::ADNS; |
8 | |
9 | |
|
|
10 | EV::ADNS::submit "example.com", EV::ADNS::r_a, 0, sub { |
|
|
11 | my ($status, $expires, @a) = @_; |
|
|
12 | warn $a[0]; # "127.13.166.3" etc. |
|
|
13 | }; |
|
|
14 | |
|
|
15 | EV::loop; |
|
|
16 | |
9 | =head1 DESCRIPTION |
17 | =head1 DESCRIPTION |
|
|
18 | |
|
|
19 | This is a simple interface to libadns (asynchronous dns) that |
|
|
20 | integrates well and automatically into the EV event loop. The |
|
|
21 | documentation for libadns is vital to understand this module, see |
|
|
22 | L<http://www.chiark.greenend.org.uk/~ian/adns/>. |
|
|
23 | |
|
|
24 | You can use it only with EV (directly or indirectly, e.g. via |
|
|
25 | L<Glib::EV>). Apart from loading and using the C<submit> function you need |
|
|
26 | not do anything (except run an EV event loop). |
|
|
27 | |
|
|
28 | =head1 OVERVIEW |
|
|
29 | |
|
|
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 |
|
|
32 | C<EV::ADNS::r_a>, C<adns__qtf_deref> becomes C<EV::ADNS::_qtf_deref> and |
|
|
33 | so on. |
|
|
34 | |
|
|
35 | =head1 FUNCTIONS |
|
|
36 | |
|
|
37 | =over 4 |
|
|
38 | |
|
|
39 | =item $query = EV::ADNS::submit "domain", $rrtype, $flags, $cb |
|
|
40 | |
|
|
41 | 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 |
|
|
43 | 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. |
|
|
45 | |
|
|
46 | 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 |
|
|
48 | result record. Example: |
|
|
49 | |
|
|
50 | sub adns_cb { |
|
|
51 | my ($status, $expires, @rr) = @_; |
|
|
52 | if ($status == EV::ADNS::s_ok) { |
|
|
53 | use JSON::XS; |
|
|
54 | warn encode_json \@rr; |
|
|
55 | } |
|
|
56 | } |
|
|
57 | |
|
|
58 | The format of result records varies considerably, here is some cursory |
|
|
59 | documentation of how each record will look like, depending on the query |
|
|
60 | type: |
|
|
61 | |
|
|
62 | =over 4 |
|
|
63 | |
|
|
64 | =item EV::ADNS::rr_a |
|
|
65 | |
|
|
66 | An IPv4 address in dotted quad (string) form. |
|
|
67 | |
|
|
68 | =item EV::ADNS::r_ns_raw, EV::ADNS::r_cname, EV::ADNS::r_ptr, EV::ADNS::r_ptr_raw |
|
|
69 | |
|
|
70 | The resource record as a simple string. |
|
|
71 | |
|
|
72 | =item EV::ADNS::r_txt |
|
|
73 | |
|
|
74 | An arrayref of strings. |
|
|
75 | |
|
|
76 | =item EV::ADNS::r_ns |
|
|
77 | |
|
|
78 | A "host address", a hostname with any number of addresses (hint records). |
|
|
79 | |
|
|
80 | Currently only the hostname will be stored, so this is alway an arrayref |
|
|
81 | with a single element of the hostname. Future versions might add |
|
|
82 | additional address entries. |
|
|
83 | |
|
|
84 | =item EV::ADNS::r_hinfo |
|
|
85 | |
|
|
86 | An arrayref consisting of the two strings. |
|
|
87 | |
|
|
88 | =item EV::ADNS::r_rp, EV::ADNS::r_rp_raw |
|
|
89 | |
|
|
90 | An arrayref with two strings. |
|
|
91 | |
|
|
92 | =item EV::ADNS::r_mx |
|
|
93 | |
|
|
94 | An arrayref consisting of the priority and a "host address" (see |
|
|
95 | C<EV::ADNS::r_ns>). Example: |
|
|
96 | |
|
|
97 | [10, "mail10.example.com"] |
|
|
98 | |
|
|
99 | =item EV::ADNS::r_mx_raw |
|
|
100 | |
|
|
101 | An arrayref consisting of the priority and the hostname, e.g. C<[10, |
|
|
102 | "mail.example.com"]>. |
|
|
103 | |
|
|
104 | =item EV::ADNS::r_soa, EV::ADNS::r_soa_raw |
|
|
105 | |
|
|
106 | An arrayref consisting of the primary nameserver, admin name, serial, |
|
|
107 | refresh, retry expire and minimum times, e.g.: |
|
|
108 | |
|
|
109 | ["ns.example.net", "hostmaster@example.net", 2000001102, 86400, 21600, 2592000, 172800] |
|
|
110 | |
|
|
111 | The "raw" form doesn't mangle the e-mail address. |
|
|
112 | |
|
|
113 | =item EV::ADNS::r_srv_raw |
|
|
114 | |
|
|
115 | An arrayref consisting of the priority, weight, port and hostname, e.g.: |
|
|
116 | |
|
|
117 | [10, 10, 5060, "sip1.example.net"] |
|
|
118 | |
|
|
119 | =item EV::ADNS::r_srv |
|
|
120 | |
|
|
121 | The same as C<EV::ADNS::r_srv_raw>, but the hostname is replaced by a "host |
|
|
122 | address" (see C<EV::ADNS::r_ns>). |
|
|
123 | |
|
|
124 | =item EV::ADNS::r_unknown |
|
|
125 | |
|
|
126 | A single octet string with the raw contents. |
|
|
127 | |
|
|
128 | =item anything else |
|
|
129 | |
|
|
130 | Currently C<undef>. |
|
|
131 | |
|
|
132 | =back |
|
|
133 | |
|
|
134 | =item $query->cancel |
|
|
135 | |
|
|
136 | Cancels a request that is in progress. |
|
|
137 | |
|
|
138 | =back |
10 | |
139 | |
11 | =cut |
140 | =cut |
12 | |
141 | |
13 | package EV::ADNS; |
142 | package EV::ADNS; |
14 | |
143 | |
15 | use Carp (); |
144 | use Carp (); |
16 | use EV (); |
145 | use EV (); |
17 | |
146 | |
18 | BEGIN { |
147 | BEGIN { |
19 | $VERSION = '1.0'; |
148 | $VERSION = '0.4'; |
20 | |
149 | |
21 | require XSLoader; |
150 | require XSLoader; |
22 | XSLoader::load (EV::ADNS, $VERSION); |
151 | XSLoader::load (EV::ADNS, $VERSION); |
23 | } |
152 | } |
24 | |
153 | |
25 | =cut |
|
|
26 | |
|
|
27 | =head1 SEE ALSO |
154 | =head1 SEE ALSO |
28 | |
155 | |
29 | L<EV>. |
156 | L<EV>, L<Net::ADNS> another interface to adns, maybe better, but without |
|
|
157 | real support to integrate it into other event loops. |
30 | |
158 | |
31 | =head1 AUTHOR |
159 | =head1 AUTHOR |
32 | |
160 | |
33 | Marc Lehmann <schmorp@schmorp.de> |
161 | Marc Lehmann <schmorp@schmorp.de> |
34 | http://home.schmorp.de/ |
162 | http://home.schmorp.de/ |