adb.h

bind-3.2.

/*
 * Copyright (C) 1999-2003  Internet Software Consortium.
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
 * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
 * INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

/* $Id: adb.h,v 1.66.2.5 2003/07/22 04:03:45 marka Exp $ */

#ifndef DNS_ADB_H
#define DNS_ADB_H 1

/*****
 ***** Module Info
 *****/

/*
 * DNS Address Database
 *
 * This module implements an address database (ADB) for mapping a name
 * to an isc_sockaddr_t. It also provides statistical information on
 * how good that address might be.
 *
 * A client will pass in a dns_name_t, and the ADB will walk through
 * the rdataset looking up addresses associated with the name.  If it
 * is found on the internal lists, a structure is filled in with the
 * address information and stats for found addresses.
 *
 * If the name cannot be found on the internal lists, a new entry will
 * be created for a name if all the information needed can be found
 * in the zone table or cache.  This new address will then be returned.
 *
 * If a request must be made to remote servers to satisfy a name lookup,
 * this module will start fetches to try to complete these addresses.  When
 * at least one more completes, an event is sent to the caller.  If none of
 * them resolve before the fetch times out, an event indicating this is
 * sent instead.
 *
 * Records are stored internally until a timer expires. The timer is the
 * smaller of the TTL or signature validity period. For A6 records, the timer
 * is the smallest of all the TTL or signature validity periods in the A6
 * chain.
 *
 * Lameness is stored per-zone, and this data hangs off each address field.
 * When an address is marked lame for a given zone the address will not
 * be returned to a caller.
 *
 *
 * MP:
 *
 *	The ADB takes care of all necessary locking.
 *
 *	Only the task which initiated the name lookup can cancel the lookup.
 *
 *
 * Security:
 *
 *	None, since all data stored is required to be pre-filtered.
 *	(Cache needs to be sane, fetches return bounds-checked and sanity-
 *       checked data, caller passes a good dns_name_t for the zone, etc)
 */

/***
 *** Imports
 ***/

#include <isc/lang.h>
#include <isc/magic.h>
#include <isc/mem.h>
#include <isc/sockaddr.h>

#include <dns/types.h>
#include <dns/view.h>

ISC_LANG_BEGINDECLS

/***
 *** Magic number checks
 ***/

#define DNS_ADBFIND_MAGIC	  ISC_MAGIC('a','d','b','H')
#define DNS_ADBFIND_VALID(x)	  ISC_MAGIC_VALID(x, DNS_ADBFIND_MAGIC)
#define DNS_ADBADDRINFO_MAGIC	  ISC_MAGIC('a','d','A','I')
#define DNS_ADBADDRINFO_VALID(x)  ISC_MAGIC_VALID(x, DNS_ADBADDRINFO_MAGIC)


/***
 *** TYPES
 ***/

typedef struct dns_adbname		dns_adbname_t;

/* dns_adbfind_t
 *
 * Represents a lookup for a single name.
 *
 * On return, the client can safely use "list", and can reorder the list.
 * Items may not be _deleted_ from this list, however, or added to it
 * other than by using the dns_adb_*() API.
 */
struct dns_adbfind {
	/* Public */
	unsigned int			magic;		/* RO: magic */
	dns_adbaddrinfolist_t		list;		/* RO: list of addrs */
	unsigned int			query_pending;	/* RO: partial list */
	unsigned int			partial_result;	/* RO: addrs missing */
	unsigned int			options;	/* RO: options */
	isc_result_t			result_v4;	/* RO: v4 result */
	isc_result_t			result_v6;	/* RO: v6 result */
	ISC_LINK(dns_adbfind_t)		publink;	/* RW: client use */

	/* Private */
	isc_mutex_t			lock;		/* locks all below */
	in_port_t			port;
	int				name_bucket;
	unsigned int			flags;
	dns_adbname_t		       *adbname;
	dns_adb_t		       *adb;
	isc_event_t			event;
	ISC_LINK(dns_adbfind_t)		plink;
};

/*
 * _INET:
 * _INET6:
 *	return addresses of that type.
 *
 * _EMPTYEVENT:
 *	Only schedule an event if no addresses are known.
 *	Must set _WANTEVENT for this to be meaningful.
 *
 * _WANTEVENT:
 *	An event is desired.  Check this bit in the returned find to see
 *	if one will actually be generated.
 *
 * _AVOIDFETCHES:
 *	If set, fetches will not be generated unless no addresses are
 *	available in any of the address families requested.
 *
 * _STARTATZONE:
 *	Fetches will start using the closest zone data or use the root servers.
 *	This is useful for reestablishing glue that has expired.
 *
 * _GLUEOK:
 * _HINTOK:
 *	Glue or hints are ok.  These are used when matching names already
 *	in the adb, and when dns databases are searched.
 *
 * _RETURNLAME:
 *	Return lame servers in a find, so that all addresses are returned.
 *
 * _LAMEPRUNED:
 *	At least one address was omitted from the list because it was lame.
 *	This bit will NEVER be set if _RETURNLAME is set in the createfind().
 */
#define DNS_ADBFIND_INET		0x00000001
#define DNS_ADBFIND_INET6		0x00000002
#define DNS_ADBFIND_ADDRESSMASK		0x00000003

#define DNS_ADBFIND_EMPTYEVENT		0x00000004
#define DNS_ADBFIND_WANTEVENT		0x00000008
#define DNS_ADBFIND_AVOIDFETCHES	0x00000010
#define DNS_ADBFIND_STARTATZONE		0x00000020
#define DNS_ADBFIND_GLUEOK		0x00000040
#define DNS_ADBFIND_HINTOK		0x00000080
#define DNS_ADBFIND_RETURNLAME		0x00000100
#define DNS_ADBFIND_LAMEPRUNED		0x00000200

/* dns_adbaddrinfo_t
 *
 * The answers to queries come back as a list of these.
 */
struct dns_adbaddrinfo {
	unsigned int			magic;		/* private */

	isc_sockaddr_t			sockaddr;	/* [rw] */
	unsigned int			srtt;		/* [rw] microseconds */
	unsigned int			flags;		/* [rw] */
	dns_adbentry_t		       *entry;		/* private */
	ISC_LINK(dns_adbaddrinfo_t)	publink;
};

/*
 * The event sent to the caller task is just a plain old isc_event_t.  It
 * contains no data other than a simple status, passed in the "type" field
 * to indicate that another address resolved, or all partially resolved
 * addresses have failed to resolve.
 *
 * "sender" is the dns_adbfind_t used to issue this query.
 *
 * This is simply a standard event, with the "type" set to:
 *
 *	DNS_EVENT_ADBMOREADDRESSES   -- another address resolved.
 *	DNS_EVENT_ADBNOMOREADDRESSES -- all pending addresses failed,
 *					were canceled, or otherwise will
 *					not be usable.
 *	DNS_EVENT_ADBCANCELED	     -- The request was canceled by a
 *					3rd party.
 *	DNS_EVENT_ADBNAMEDELETED     -- The name was deleted, so this request
 *					was canceled.
 *
 * In each of these cases, the addresses returned by the initial call
 * to dns_adb_createfind() can still be used until they are no longer needed.
 */

/****
 **** FUNCTIONS
 ****/


isc_result_t
dns_adb_create(isc_mem_t *mem, dns_view_t *view, isc_timermgr_t *tmgr,
	       isc_taskmgr_t *taskmgr, dns_adb_t **newadb);
/*
 * Create a new ADB.
 *
 * Notes:
 *
 *	Generally, applications should not create an ADB directly, but
 *	should instead call dns_view_createresolver().
 *
 * Requires:
 *
 *	'mem' must be a valid memory context.
 *
 *	'view' be a pointer to a valid view.
 *
 *	'tmgr' be a pointer to a valid timer manager.
 *
 *	'taskmgr' be a pointer to a valid task manager.
 *
 *	'newadb' != NULL && '*newadb' == NULL.
 *
 * Returns:
 *
 *	ISC_R_SUCCESS	after happiness.
 *	ISC_R_NOMEMORY	after resource allocation failure.
 */

void
dns_adb_attach(dns_adb_t *adb, dns_adb_t **adbp);
/*
 * Attach to an 'adb' to 'adbp'.
 *
 * Requires:
 *	'adb' to be a valid dns_adb_t, created via dns_adb_create().
 *	'adbp' to be a valid pointer to a *dns_adb_t which is initialized
 *		to NULL.
 */

void
dns_adb_detach(dns_adb_t **adb);
/*
 * Delete the ADB. Sets *ADB to NULL. Cancels any outstanding requests.
 *
 * Requires:
 *
 *	'adb' be non-NULL and '*adb' be a valid dns_adb_t, created via
 *	dns_adb_create().
 */

void
dns_adb_whenshutdown(dns_adb_t *adb, isc_task_t *task, isc_event_t **eventp);
/*
 * Send '*eventp' to 'task' when 'adb' has shutdown.
 *
 * Requires:
 *
 *	'*adb' is a valid dns_adb_t.
 *
 *	eventp != NULL && *eventp is a valid event.
 *
 * Ensures:
 *
 *	*eventp == NULL
 *
 *	The event's sender field is set to the value of adb when the event
 *	is sent.