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