view release on metacpan or  search on metacpan

lib/AnyEvent/DNS.pm  view on Meta::CPAN

=item $resolver->resolve ($qname, $qtype, %options, $cb->(@rr))

Queries the DNS for the given domain name C<$qname> of type C<$qtype>.

A C<$qtype> is either a numerical query type (e.g. C<1> for A records) or
a lowercase name (you have to look at the source to see which aliases are
supported, but all types from RFC 1035, C<aaaa>, C<srv>, C<spf> and a few
more are known to this module). A C<$qtype> of "*" is supported and means
"any" record type.

The callback will be invoked with a list of matching result records or
none on any error or if the name could not be found.

CNAME chains (although illegal) are followed up to a length of 10.

The callback will be invoked with arraryefs of the form C<[$name,
$type, $class, $ttl, @data>], where C<$name> is the domain name,
C<$type> a type string or number, C<$class> a class name, C<$ttl> is the
remaining time-to-live and C<@data> is resource-record-dependent data, in
seconds. For C<a> records, this will be the textual IPv4 addresses, for
C<ns> or C<cname> records this will be a domain name, for C<txt> records
these are all the strings and so on.

All types mentioned in RFC 1035, C<aaaa>, C<srv>, C<naptr> and C<spf> are
decoded. All resource records not known to this module will have the raw
C<rdata> field as fifth array element.

Note that this resolver is just a stub resolver: it requires a name server
supporting recursive queries, will not do any recursive queries itself and
is not secure when used against an untrusted name server.

The following options are supported:

=over 4

=item search => [$suffix...]

Use the given search list (which might be empty), by appending each one
in turn to the C<$qname>. If this option is missing then the configured
C<ndots> and C<search> values define its value (depending on C<ndots>, the
empty suffix will be prepended or appended to that C<search> value). If
the C<$qname> ends in a dot, then the searchlist will be ignored.

=item accept => [$type...]

Lists the acceptable result types: only result types in this set will be
accepted and returned. The default includes the C<$qtype> and nothing
else. If this list includes C<cname>, then CNAME-chains will not be
followed (because you asked for the CNAME record).

=item class => "class"

Specify the query class ("in" for internet, "ch" for chaosnet and "hs" for
hesiod are the only ones making sense). The default is "in", of course.

=back

Examples:

   # full example, you can paste this into perl:
   use Data::Dumper;
   use AnyEvent::DNS;
   AnyEvent::DNS::resolver->resolve (
      "google.com", "*", my $cv = AnyEvent->condvar);
   warn Dumper [$cv->recv];

   # shortened result:
   # [
   #   [ 'google.com', 'soa', 'in', 3600, 'ns1.google.com', 'dns-admin.google.com',
   #     2008052701, 7200, 1800, 1209600, 300 ],
   #   [
   #     'google.com', 'txt', 'in', 3600,
   #     'v=spf1 include:_netblocks.google.com ~all'
   #   ],
   #   [ 'google.com', 'a', 'in', 3600, '64.233.187.99' ],
   #   [ 'google.com', 'mx', 'in', 3600, 10, 'smtp2.google.com' ],
   #   [ 'google.com', 'ns', 'in', 3600, 'ns2.google.com' ],
   # ]

   # resolve a records:
   $res->resolve ("ruth.plan9.de", "a", sub { warn Dumper [@_] });

   # result:
   # [
   #   [ 'ruth.schmorp.de', 'a', 'in', 86400, '129.13.162.95' ]
   # ]

   # resolve any records, but return only a and aaaa records:
   $res->resolve ("test1.laendle", "*",
      accept => ["a", "aaaa"],
      sub {
         warn Dumper [@_];
      }
   );

   # result:
   # [
   #   [ 'test1.laendle', 'a', 'in', 86400, '10.0.0.255' ],
   #   [ 'test1.laendle', 'aaaa', 'in', 60, '3ffe:1900:4545:0002:0240:0000:0000:f7e1' ]
   # ]

=cut

sub resolve($%) {
   my $cb = pop;
   my ($self, $qname, $qtype, %opt) = @_;

   $self->wait_for_slot (sub {
      my $self = shift;

      my @search = $qname =~ s/\.$//
         ? ""
         : $opt{search}
           ? @{ $opt{search} }
           : ($qname =~ y/.//) >= $self->{ndots}
             ? ("", @{ $self->{search} })
             : (@{ $self->{search} }, "");

      my $class = $opt{class} || "in";

      my %atype = $opt{accept}