# adns.pm
# - the Perl part of the interface between adns and perl
#
# $Id: adns.pm,v 1.9 1999/11/30 11:40:01 fanf Exp $

#  This file is
#    Copyright (C) 1999 Tony Finch <dot@dotat.at>
#
#  It is part of adns, which is
#    Copyright (C) 1997-1999 Ian Jackson <ian@davenant.greenend.org.uk>
#    Copyright (C) 1999 Tony Finch <dot@dotat.at>
# 
#  This program is free software; you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation; either version 2, or (at your option)
#  any later version.
#  
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#  
#  You should have received a copy of the GNU General Public License
#  along with this program; if not, write to the Free Software Foundation,
#  Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 

package Net::adns;

use strict;
use Carp;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD);

require Exporter;
require DynaLoader;
require AutoLoader;

@ISA = qw(Exporter DynaLoader);

# Items to export into callers namespace by default.
@EXPORT = qw(

  adns_if_noenv
  adns_if_noerrprint
  adns_if_noserverwarn
  adns_if_debug
  adns_if_logpid
  adns_if_noautosys
  adns_if_eintr
  adns_if_nosigpipe
  adns_if_checkc_entex
  adns_if_checkc_freq

  adns_qf_search
  adns_qf_usevc
  adns_qf_owner
  adns_qf_quoteok_query
  adns_qf_quoteok_cname
  adns_qf_quoteok_anshost
  adns_qf_quotefail_cname
  adns_qf_cname_loose
  adns_qf_cname_forbid
  
  adns_r_none
  adns_r_a
  adns_r_ns_raw
  adns_r_ns
  adns_r_cname
  adns_r_soa_raw
  adns_r_soa
  adns_r_ptr_raw
  adns_r_ptr
  adns_r_hinfo
  adns_r_mx_raw
  adns_r_mx
  adns_r_txt
  adns_r_rp_raw
  adns_r_rp
  adns_r_addr

  adns_s_ok
  adns_s_nomemory
  adns_s_unknownrrtype
  adns_s_systemfail
  adns_s_timeout
  adns_s_allservfail
  adns_s_norecurse
  adns_s_invalidresponse
  adns_s_unknownformat
  adns_s_rcodeservfail
  adns_s_rcodeformaterror
  adns_s_rcodenotimplemented
  adns_s_rcoderefused
  adns_s_rcodeunknown
  adns_s_inconsistent
  adns_s_prohibitedcname
  adns_s_answerdomaininvalid
  adns_s_answerdomaintoolong
  adns_s_invaliddata
  adns_s_querydomainwrong
  adns_s_querydomaininvalid
  adns_s_querydomaintoolong
  adns_s_nxdomain
  adns_s_nodata

);

@EXPORT_OK = ();

$VERSION = '0.06';

sub AUTOLOAD {
    # This AUTOLOAD is used to 'autoload' constants from the constant()
    # XS function.  If a constant is not found then control is passed
    # to the AUTOLOAD in AutoLoader.

    my $constname;
    ($constname = $AUTOLOAD) =~ s/.*:://;
    croak "& not defined" if $constname eq 'constant';
    my $val = constant($constname, @_ ? $_[0] : 0);
    if ($! != 0) {
	$AutoLoader::AUTOLOAD = $AUTOLOAD;
	goto &AutoLoader::AUTOLOAD;
    }
    eval "sub $AUTOLOAD { $val }";
    goto &$AUTOLOAD;
}

bootstrap Net::adns $VERSION;

# a slightly more perlish interface to Net::adns::init
sub new {
    my $proto = shift;
    my $class = ref($proto) || $proto;
    my %arg = @_;

    if(exists $arg{configtext}) {
	return init($arg{initflags} || 0,
		    $arg{diagfile} || \*STDERR,
		    $arg{configtext});
    } else {
	return init($arg{initflags} || 0,
		    $arg{diagfile} || \*STDERR);
    }
}

# define the answer object hierarchy

@Net::adns::answer::a::ISA	= ("Net::adns::answer");
@Net::adns::answer::addr::ISA	= ("Net::adns::answer");
@Net::adns::answer::mx::ISA	= ("Net::adns::answer");
@Net::adns::answer::mx_raw::ISA	= ("Net::adns::answer");
@Net::adns::answer::ns::ISA	= ("Net::adns::answer");
@Net::adns::answer::ns_raw::ISA	= ("Net::adns::answer");
@Net::adns::answer::rp::ISA	= ("Net::adns::answer");
@Net::adns::answer::ptr::ISA	= ("Net::adns::answer");
@Net::adns::answer::ptr_raw::ISA= ("Net::adns::answer");
@Net::adns::answer::soa::ISA	= ("Net::adns::answer");
@Net::adns::answer::txt::ISA	= ("Net::adns::answer");
@Net::adns::answer::cname::ISA	= ("Net::adns::answer");
@Net::adns::answer::hinfo::ISA	= ("Net::adns::answer");


# Autoload methods go after =cut, and are processed by the autosplit program.

1;
__END__

# A bit of documentation

=head1 NAME

Net::adns - Perl interface to I<adns>, an advanced, easy to use,
		asynchronous-capable DNS client library.

=head1 SYNOPSIS

    use Net::adns;
    my $adns = new Net::adns;

    # blocking lookups
    my $answer = $adns->synchronous("www.perl.com", adns_r_a);

    # deferred lookups
    my $query = $adns->submit("ftp.perl.com", adns_r_a, adns_qf_owner, $ctx);
    my $answer = $query->wait;
    die unless $answer->status == adns_s_ok;

    # access to various information about the answer
    print "cname of ", $answer->owner, " is ", $answer->cname, "\n";
    print $answer->cname, " ", scalar $answer->type, " ", $answer->txt, "\n";

=head1 DESCRIPTION

A C<Net::adns> object keeps the state of the I<adns> library.
They can be created using either the C<init> or C<new> functions.

=over 4

=item Net::adns::init INITFLAGS, DIAGFILE, CONFIGTEXT

=item Net::adns::init INITFLAGS, DIAGFILE

=item Net::adns::init INITFLAGS

=item Net::adns::init

Returns a new C<Net::adns> object initialized according to any
specified INITFLAGS. If DIAGFILE is specified it should be a file
handle to which diagnostics will be printed. If some CONFIGTEXT is
specified then it is used instead of F</etc/resolv.conf>. INITFLAGS
can be any of the following values orred together:

	adns_if_noenv		do not look at environment
	adns_if_noerrprint	never print output to stderr (_debug overrides)
	adns_if_noserverwarn	do not warn to stderr about duff nameservers etc.
	adns_if_debug		enable all output to stderr plus debug msgs
	adns_if_logpid		include pid in diagnostic output
	adns_if_noautosys	do not make syscalls at every opportunity
	adns_if_eintr		allow _wait and _synchronous to return EINTR
	adns_if_nosigpipe	applic has SIGPIPE set to SIG_IGN, do not protect
	adns_if_checkc_entex	do consistency checks on entry/exit to adns funcs
	adns_if_checkc_freq	do consistency checks very frequently (slow!)

=item new Net::adns (ARGS)

An object-oriented wrapper around C<init>. The ARGS are key-value
pairs so these two expressions are equivalent:

    $adns = Net::adns::init (adns_if_debug, \*STDOUT, "nameserver 127.0.0.1");

    $adns = new Net::adns (initflags	=> adns_if_debug,
			   diagfile	=> \*STDOUT,
			   configtext	=> "nameserver 127.0.0.1");

=back

=head1 AUTHOR

Net::adns is written by Tony Finch, dot@dotat.at

adns is written by Ian Jackson, ian@davenant.greenend.org.uk

=head1 SEE ALSO

adns.h

=cut