[ViewVC] Annotation of: cvs/EV-ADNS/README

NAME
    EV::ADNS - lightweight asynchronous dns queries using EV and libadns

SYNOPSIS
     use EV;
     use EV::ADNS;

     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::run;

DESCRIPTION
    This is a simple interface to libadns (asynchronous dns) that integrates
    well and automatically into the EV event loop. The documentation for
    libadns is vital to understand this module, see
    <http://www.chiark.greenend.org.uk/~ian/adns/>.

    You can use it only with EV (directly or indirectly, e.g. via Glib::EV).
    Apart from loading and using the "submit" function you need not do
    anything (except run an EV event loop).

OVERVIEW
    All the constants/enums from adns.h are available in the EV::ADNS
    namespace, without the "adns_" prefix, i.e. "adns_r_a" becomes
    "EV::ADNS::r_a" and so on.

FUNCTIONS
    $query = EV::ADNS::submit "domain", $rrtype, $flags, $cb
        Submits a new request to be handled. See the "adns_submit" 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.

        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 result record. Example:

           sub adns_cb {
              my ($status, $expires, @rr) = @_;
              if ($status == EV::ADNS::s_ok) {
                 use JSON::XS;
                 warn encode_json \@rr;
              }
           }

        The format of result records varies considerably, here is some
        cursory documentation of how each record will look like, depending
        on the query type:

        EV::ADNS::r_a, EV::ADNS::r_addr
            An IPv4 address in dotted quad (string) form.

        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.

        EV::ADNS::r_txt
            An arrayref of strings.

        EV::ADNS::r_ns
            A "host address", a hostname with any number of addresses (hint
            records).

            The record will be an arrayref with domainname, adns status and
            any number of associated addresses: "["domain", adns_status,
            addr...]".

        EV::ADNS::r_hinfo
            An arrayref consisting of the two strings.

        EV::ADNS::r_rp, EV::ADNS::r_rp_raw
            An arrayref with two strings.

        EV::ADNS::r_mx
            An arrayref consisting of the priority and a "host address" (see
            "EV::ADNS::r_ns"). Example:

               [10, [["alt3.aspmx.l.google.com", 0, "64.233.189.27", "2404:6800:4008:c07::1a"]]]

        EV::ADNS::r_mx_raw
            An arrayref consisting of the priority and the hostname, e.g.
            "[10, "mail.example.com"]".

        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]

            The "raw" form doesn't mangle the e-mail address.

        EV::ADNS::r_srv_raw
            An arrayref consisting of the priority, weight, port and
            hostname, e.g.:

               [10, 10, 5060, "sip1.example.net"]

        EV::ADNS::r_srv
            The same as "EV::ADNS::r_srv_raw", but the hostname is replaced
            by a "host address" (see "EV::ADNS::r_ns").

        EV::ADNS::r_unknown
            A single octet string with the raw contents.

        anything else
            Currently "undef".

    $query->cancel
        Cancels a request that is in progress.

    EV::ADNS::reinit 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 must currently be specified as "undef".

        The second argument can be missing or "undef"; in which case the
        normal initialisation is done (such as reading the resolv.conf), 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 resolv.conf contents.

SEE ALSO
    EV, Net::ADNS another interface to adns, maybe better, but without real
    support to integrate it into other event loops.

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

Revision:	1.6
Committed:	Fri Oct 16 22:58:35 2015 UTC (10 years, 11 months ago) by root
Branch:	MAIN
CVS Tags:	rel-3_0, HEAD
Changes since 1.5:	+22 -10 lines
Log Message:	3.0
#	User	Rev	Content
1	root	1.1	NAME
2	root	1.3	EV::ADNS - lightweight asynchronous dns queries using EV and libadns
3	root	1.1
4			SYNOPSIS
5	root	1.2	use EV;
6			use EV::ADNS;
7	root	1.1
8	root	1.6	EV::ADNS::submit "example.com", EV::ADNS::r_addr, EV::ADNS::qf_cname_loose, sub {
9	root	1.2	my ($status, $expires, @a) = @_;
10			warn $a[0]; # "127.13.166.3" etc.
11			};
12
13	root	1.6	EV::run;
14	root	1.1
15			DESCRIPTION
16	root	1.2	This is a simple interface to libadns (asynchronous dns) that integrates
17			well and automatically into the EV event loop. The documentation for
18			libadns is vital to understand this module, see
19			<http://www.chiark.greenend.org.uk/~ian/adns/>.
20
21			You can use it only with EV (directly or indirectly, e.g. via Glib::EV).
22			Apart from loading and using the "submit" function you need not do
23			anything (except run an EV event loop).
24
25			OVERVIEW
26			All the constants/enums from adns.h are available in the EV::ADNS
27	root	1.6	namespace, without the "adns_" prefix, i.e. "adns_r_a" becomes
28			"EV::ADNS::r_a" and so on.
29	root	1.2
30			FUNCTIONS
31			$query = EV::ADNS::submit "domain", $rrtype, $flags, $cb
32			Submits a new request to be handled. See the "adns_submit" C
33			function description for more details. The function optionally
34			returns a query object which can be used to cancel an in-progress
35			request. You do not need to store the query object, even if you
36	root	1.6	ignore it, the query will proceed.
37	root	1.2
38			The callback will be invoked with a result status, the time the
39			resource record validity expires and zero or more resource records,
40			one scalar per result record. Example:
41
42			sub adns_cb {
43			my ($status, $expires, @rr) = @_;
44			if ($status == EV::ADNS::s_ok) {
45			use JSON::XS;
46	root	1.4	warn encode_json \@rr;
47	root	1.2	}
48			}
49
50			The format of result records varies considerably, here is some
51			cursory documentation of how each record will look like, depending
52			on the query type:
53
54	root	1.5	EV::ADNS::r_a, EV::ADNS::r_addr
55	root	1.2	An IPv4 address in dotted quad (string) form.
56
57	root	1.3	EV::ADNS::r_ns_raw, EV::ADNS::r_cname, EV::ADNS::r_ptr,
58			EV::ADNS::r_ptr_raw
59	root	1.2	The resource record as a simple string.
60
61	root	1.3	EV::ADNS::r_txt
62	root	1.2	An arrayref of strings.
63
64	root	1.3	EV::ADNS::r_ns
65	root	1.2	A "host address", a hostname with any number of addresses (hint
66			records).
67
68	root	1.6	The record will be an arrayref with domainname, adns status and
69			any number of associated addresses: "["domain", adns_status,
70			addr...]".
71	root	1.2
72	root	1.3	EV::ADNS::r_hinfo
73	root	1.2	An arrayref consisting of the two strings.
74
75	root	1.3	EV::ADNS::r_rp, EV::ADNS::r_rp_raw
76	root	1.2	An arrayref with two strings.
77
78	root	1.3	EV::ADNS::r_mx
79	root	1.2	An arrayref consisting of the priority and a "host address" (see
80	root	1.3	"EV::ADNS::r_ns"). Example:
81	root	1.2
82	root	1.6	[10, [["alt3.aspmx.l.google.com", 0, "64.233.189.27", "2404:6800:4008:c07::1a"]]]
83	root	1.2
84	root	1.3	EV::ADNS::r_mx_raw
85	root	1.2	An arrayref consisting of the priority and the hostname, e.g.
86			"[10, "mail.example.com"]".
87
88	root	1.3	EV::ADNS::r_soa, EV::ADNS::r_soa_raw
89	root	1.2	An arrayref consisting of the primary nameserver, admin name,
90			serial, refresh, retry expire and minimum times, e.g.:
91
92	root	1.3	["ns.example.net", "hostmaster@example.net", 2000001102, 86400, 21600, 2592000, 172800]
93	root	1.2
94			The "raw" form doesn't mangle the e-mail address.
95
96	root	1.3	EV::ADNS::r_srv_raw
97	root	1.2	An arrayref consisting of the priority, weight, port and
98			hostname, e.g.:
99
100	root	1.3	[10, 10, 5060, "sip1.example.net"]
101	root	1.2
102	root	1.3	EV::ADNS::r_srv
103			The same as "EV::ADNS::r_srv_raw", but the hostname is replaced
104			by a "host address" (see "EV::ADNS::r_ns").
105	root	1.2
106	root	1.3	EV::ADNS::r_unknown
107	root	1.2	A single octet string with the raw contents.
108
109			anything else
110			Currently "undef".
111	root	1.1
112	root	1.2	$query->cancel
113			Cancels a request that is in progress.
114	root	1.1
115	root	1.6	EV::ADNS::reinit undef, $resolvdata_or_undef
116			Cancels all outstanding queries, frees all adns state and
117			reinitialises it. It is highly recommended to only call this when
118			there are no outstanding requests.
119
120			The first argument must currently be specified as "undef".
121
122			The second argument can be missing or "undef"; in which case the
123			normal initialisation is done (such as reading the resolv.conf), or
124			it might be a stirng, in which case no config files or environment
125			variables will be read and the given string will be interpreted as
126			the resolv.conf contents.
127
128	root	1.1	SEE ALSO
129	root	1.2	EV, Net::ADNS another interface to adns, maybe better, but without real
130			support to integrate it into other event loops.
131	root	1.1
132			AUTHOR
133			Marc Lehmann <schmorp@schmorp.de>
134			http://home.schmorp.de/
135