--- EV-ADNS/ADNS.pm 2007/12/01 22:36:10 1.4 +++ EV-ADNS/ADNS.pm 2015/10/17 02:38:45 1.17 @@ -1,18 +1,18 @@ =head1 NAME -EV::ADNS - +EV::ADNS - lightweight asynchronous dns queries using EV and libadns =head1 SYNOPSIS use EV; use EV::ADNS; - EV::ADNS::submit "example.com", EV::ADNS::r_a, 0, sub { + EV::ADNS::submit "example.com", EV::ADNS::r_addr, EV::ADNS::qf_cname_loose, sub { my ($status, $expires, @a) = @_; warn $a[0]; # "127.13.166.3" etc. }; - EV::loop; + EV::run; =head1 DESCRIPTION @@ -28,9 +28,8 @@ =head1 OVERVIEW All the constants/enums from F are available in the EV::ADNS -namespace, without the C prefix, e.g. C becomes -C, C becomes C and -so on. +namespace, without the C prefix, i.e. C becomes +C and so on. =head1 FUNCTIONS @@ -41,7 +40,7 @@ Submits a new request to be handled. See the C C function description for more details. The function optionally returns a query object which can be used to cancel an in-progress request. You do not need -to store the query object, even if you ignore it the query will proceed. +to store the query object, even if you ignore it, the query will proceed. The callback will be invoked with a result status, the time the resource record validity expires and zero or more resource records, one scalar per @@ -51,7 +50,7 @@ my ($status, $expires, @rr) = @_; if ($status == EV::ADNS::s_ok) { use JSON::XS; - warn to_json \@rr; + warn encode_json \@rr; } } @@ -61,67 +60,75 @@ =over 4 -=item EV::ADNS::rr_a +=item EV::ADNS::r_addr + +An IPv4 and/or IPV6 address in string form. + +=item EV::ADNS::r_a An IPv4 address in dotted quad (string) form. -=item adns_r_ns_raw, adns_r_cname, adns_r_ptr, adns_r_ptr_raw +=item EV::ADNS::r_aaaa + +An IPv6 address in string form. + +=item EV::ADNS::r_ns_raw, EV::ADNS::r_cname, EV::ADNS::r_ptr, EV::ADNS::r_ptr_raw The resource record as a simple string. -=item adns_r_txt +=item EV::ADNS::r_txt -An arrayref of strings. +An arrayref of strings (usually one string per record). -=item adns_r_ns +=item EV::ADNS::r_ns -A "host address", a hostname with any number of addresses (hint records). +A "host address", a hostname with any number of pre-resolved addresses +(hint records). -Currently only the hostname will be stored, so this is alway an arrayref -with a single element of the hostname. Future versions might add -additional address entries. +The record will be an arrayref with domainname, adns status and any number +of associated addresses: C<< ["domain", adns_status, addr...] >>. -=item adns_r_hinfo +=item EV::ADNS::r_hinfo An arrayref consisting of the two strings. -=item adns_r_rp, adns_r_rp_raw +=item EV::ADNS::r_rp, EV::ADNS::r_rp_raw An arrayref with two strings. -=item adns_r_mx +=item EV::ADNS::r_mx An arrayref consisting of the priority and a "host address" (see -C). Example: +C). Example: - [10,"mail10.example.com"] + [10, [["alt3.aspmx.l.google.com", 0, "64.233.189.27", "2404:6800:4008:c07::1a"]]] -=item adns_r_mx_raw: +=item EV::ADNS::r_mx_raw An arrayref consisting of the priority and the hostname, e.g. C<[10, "mail.example.com"]>. -=item adns_r_soa, adns_r_soa_raw +=item EV::ADNS::r_soa, EV::ADNS::r_soa_raw An arrayref consisting of the primary nameserver, admin name, serial, refresh, retry expire and minimum times, e.g.: - ["ns.example.net","hostmaster@example.net",2000001102,86400,21600,2592000,172800] + ["ns.example.net", "hostmaster@example.net", 2000001102, 86400, 21600, 2592000, 172800] The "raw" form doesn't mangle the e-mail address. -=item adns_r_srv_raw +=item EV::ADNS::r_srv_raw An arrayref consisting of the priority, weight, port and hostname, e.g.: - [10,10,5060,"sip1.example.net"] + [10, 10, 5060, "sip1.example.net"] -=item adns_r_srv +=item EV::ADNS::r_srv -The same as C, but the hostname is replaced by a "host -address" (see C). +The same as C, but the hostname is replaced by a "host +address" (see C). -=item adns_r_unknown +=item EV::ADNS::r_unknown A single octet string with the raw contents. @@ -135,6 +142,21 @@ Cancels a request that is in progress. +=item EV::ADNS::reinit $flags_or_undef, $resolvdata_or_undef + +Cancels all outstanding queries, frees all adns state and reinitialises +it. It is highly recommended to only call this when there are no +outstanding requests. + +The first argument is the set of init flags to use, or C, in which +case EV::ADNS uses it's default flag set. + +The second argument can be missing or C; in which case the normal +initialisation is done (such as reading the F), or it might +be a stirng, in which case no config files or environment variables will +be read and the given string will be interpreted as the F +contents. + =back =cut @@ -145,7 +167,7 @@ use EV (); BEGIN { - $VERSION = '0.2'; + $VERSION = '3.0'; require XSLoader; XSLoader::load (EV::ADNS, $VERSION);