adb.h

bind-3.2.

 */

void
dns_adb_shutdown(dns_adb_t *adb);
/*
 * Shutdown 'adb'.
 *
 * Requires:
 *
 * 	'*adb' is a valid dns_adb_t.
 */

isc_result_t
dns_adb_createfind(dns_adb_t *adb, isc_task_t *task, isc_taskaction_t action,
		   void *arg, dns_name_t *name, dns_name_t *zone,
		   unsigned int options, isc_stdtime_t now, dns_name_t *target,
		   in_port_t port, dns_adbfind_t **find);
/*
 * Main interface for clients. The adb will look up the name given in
 * "name" and will build up a list of found addresses, and perhaps start
 * internal fetches to resolve names that are unknown currently.
 *
 * If other addresses resolve after this call completes, an event will
 * be sent to the <task, taskaction, arg> with the sender of that event
 * set to a pointer to the dns_adbfind_t returned by this function.
 *
 * If no events will be generated, the *find->result_v4 and/or result_v6
 * members may be examined for address lookup status.  The usual ISC_R_SUCCESS,
 * ISC_R_FAILURE, and DNS_R_NX{DOMAIN,RRSET} are returned, along with
 * ISC_R_NOTFOUND meaning the ADB has not _yet_ found the values.  In this
 * latter case, retrying may produce more addresses.
 *
 * If events will be returned, the result_v[46] members are only valid
 * when that event is actually returned.
 *
 * The list of addresses returned is unordered.  The caller must impose
 * any ordering required.  The list will not contain "known bad" addresses,
 * however.  For instance, it will not return hosts that are known to be
 * lame for the zone in question.
 *
 * The caller cannot (directly) modify the contents of the address list's
 * fields other than the "link" field.  All values can be read at any
 * time, however.
 *
 * The "now" parameter is used only for determining which entries that
 * have a specific time to live or expire time should be removed from
 * the running database.  If specified as zero, the current time will
 * be retrieved and used.
 *
 * If 'target' is not NULL and 'name' is an alias (i.e. the name is
 * CNAME'd or DNAME'd to another name), then 'target' will be updated with
 * the domain name that 'name' is aliased to.
 *
 * All addresses returned will have the sockaddr's port set to 'port.'
 * The caller may change them directly in the dns_adbaddrinfo_t since
 * they are copies of the internal address only.
 *
 * XXXMLG  Document options, especially the flags which control how
 *         events are sent.
 *
 * Requires:
 *
 *	*adb be a valid isc_adb_t object.
 *
 *	If events are to be sent, *task be a valid task,
 *	and isc_taskaction_t != NULL.
 *
 *	*name is a valid dns_name_t.
 *
 *	zone != NULL and *zone be a valid dns_name_t.
 *
 *	target == NULL or target is a valid name with a buffer.
 *
 *	find != NULL && *find == NULL.
 *
 * Returns:
 *
 *	ISC_R_SUCCESS	Addresses might have been returned, and events will be
 *			delivered for unresolved addresses.
 *	ISC_R_NOMORE	Addresses might have been returned, but no events
 *			will ever be posted for this context.  This is only
 *			returned if task != NULL.
 *	ISC_R_NOMEMORY	insufficient resources
 *	DNS_R_ALIAS	'name' is an alias for another name.
 *
 * Calls, and returns error codes from:
 *
 *	isc_stdtime_get()
 *
 * Notes:
 *
 *	No internal reference to "name" exists after this function
 *	returns.
 */

void
dns_adb_cancelfind(dns_adbfind_t *find);
/*
 * Cancels the find, and sends the event off to the caller.
 *
 * It is an error to call dns_adb_cancelfind() on a find where
 * no event is wanted, or will ever be sent.
 *
 * Note:
 *
 *	It is possible that the real completion event was posted just
 *	before the dns_adb_cancelfind() call was made.  In this case,
 *	dns_adb_cancelfind() will do nothing.  The event callback needs
 *	to be prepared to find this situation (i.e. result is valid but
 *	the caller expects it to be canceled).
 *
 * Requires:
 *
 *	'find' be a valid dns_adbfind_t pointer.
 *
 *	events would have been posted to the task.  This can be checked
 *	with (find->options & DNS_ADBFIND_WANTEVENT).
 *
 * Ensures:
 *
 *	The event was posted to the task.
 */

void
dns_adb_destroyfind(dns_adbfind_t **find);
/*
 * Destroys the find reference.
 *
 * Note:
 *
 *	This can only be called after the event was delivered for a
 *	find.  Additionally, the event MUST have been freed via
 *	isc_event_free() BEFORE this function is called.
 *
 * Requires:
 *
 *	'find' != NULL and *find be valid dns_adbfind_t pointer.
 *
 * Ensures:
 *
 *	No "address found" events will be posted to the originating task
 *	after this function returns.
 */

void
dns_adb_dump(dns_adb_t *adb, FILE *f);
/*
 * This function is only used for debugging.  It will dump as much of the
 * state of the running system as possible.
 *
 * Requires:
 *
 *	adb be valid.
 *
 *	f != NULL, and is a file open for writing.
 */

void
dns_adb_dumpfind(dns_adbfind_t *find, FILE *f);
/*
 * This function is only used for debugging.  Dump the data associated
 * with a find.
 *
 * Requires:
 *
 *	find is valid.
 *
 * 	f != NULL, and is a file open for writing.
 */

isc_result_t
dns_adb_marklame(dns_adb_t *adb, dns_adbaddrinfo_t *addr, dns_name_t *zone,
		 isc_stdtime_t expire_time);
/*
 * Mark the given address as lame for the zone "zone".  expire_time should
 * be set to the time when the entry should expire.  That is, if it is to
 * expire 10 minutes in the future, it should set it to (now + 10 * 60).
 *
 * Requires:
 *
 *	adb be valid.
 *
 *	addr be valid.
 *
 *	zone be the zone used in the dns_adb_createfind() call.
 *
 * Returns:
 *
 *	ISC_R_SUCCESS		-- all is well.
 *	ISC_R_NOMEMORY		-- could not mark address as lame.
 */

/*
 * A reasonable default for RTT adjustments
 */
#define DNS_ADB_RTTADJDEFAULT		7	/* default scale */
#define DNS_ADB_RTTADJREPLACE		0	/* replace with our rtt */
#define DNS_ADB_RTTADJAGE		10	/* age this rtt */

void
dns_adb_adjustsrtt(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
		   unsigned int rtt, unsigned int factor);
/*
 * Mix the round trip time into the existing smoothed rtt.  The formula used
 * (where srtt is the existing rtt value, and rtt and factor are arguments to
 * this function):
 *
 *	new_srtt = (old_srtt / 10 * factor) + (rtt / 10 * (10 - factor));
 *
 * XXXRTH  Do we want to publish the formula?  What if we want to change how
 *         this works later on?  Recommend/require that the units are
 *	   microseconds?
 *
 * Requires:
 *
 *	adb be valid.
 *
 *	addr be valid.
 *
 *	0 <= factor <= 10
 *
 * Note:
 *
 *	The srtt in addr will be updated to reflect the new global
 *	srtt value.  This may include changes made by others.
 */

void
dns_adb_changeflags(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
		    unsigned int bits, unsigned int mask);
/*
 * Set the flags as given by:
 *
 *	newflags = (oldflags & ~mask) | (bits & mask);
 *
 * Requires:
 *
 *	adb be valid.
 *
 *	addr be valid.
 */

isc_result_t
dns_adb_findaddrinfo(dns_adb_t *adb, isc_sockaddr_t *sa,
		     dns_adbaddrinfo_t **addrp, isc_stdtime_t now);
/*
 * Return a dns_adbaddrinfo_t that is associated with address 'sa'.
 *
 * Requires:
 *
 *	adb is valid.
 *
 *	sa is valid.
 *
 *	addrp != NULL && *addrp == NULL
 *
 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_NOMEMORY
 *	ISC_R_SHUTTINGDOWN
 */

void
dns_adb_freeaddrinfo(dns_adb_t *adb, dns_adbaddrinfo_t **addrp);
/*
 * Free a dns_adbaddrinfo_t allocated by dns_adb_findaddrinfo().
 *
 * Requires:
 *
 *	adb is valid.
 *
 *	*addrp is a valid dns_adbaddrinfo_t *.
 */

void
dns_adb_flush(dns_adb_t *adb);
/*
 * Flushes all cached data from the adb.
 *
 * Requires:
 * 	adb is valid.
 */

ISC_LANG_ENDDECLS

#endif /* DNS_ADB_H */