[ViewVC] Diff of: cvs/EV-ADNS/ADNS.pm

Comparing EV-ADNS/ADNS.pm (file contents):
Revision 1.1 by root, Sat Dec 1 13:53:10 2007 UTC vs.
Revision 1.7 by root, Wed Dec 5 10:46:00 2007 UTC

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.3';
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/

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing EV-ADNS/ADNS.pm (file contents): Revision 1.1 by root, Sat Dec 1 13:53:10 2007 UTC vs. Revision 1.7 by root, Wed Dec 5 10:46:00 2007 UTC

Diff Legend

Comparing EV-ADNS/ADNS.pm (file contents):
Revision 1.1 by root, Sat Dec 1 13:53:10 2007 UTC vs.
Revision 1.7 by root, Wed Dec 5 10:46:00 2007 UTC