db.h

package of develop dns

 * Requires:
 *
 *	'db' is a valid database.
 *
 *	'source' is a valid node.
 *
 *	'targetp' points to a NULL dns_node_t *.
 *
 * Ensures:
 *
 *	*targetp is attached to source.
 */

void
dns_db_detachnode(dns_db_t *db, dns_dbnode_t **nodep);
/*
 * Detach *nodep from its node.
 *
 * Requires:
 *
 *	'db' is a valid database.
 *
 *	'nodep' points to a valid node.
 *
 * Ensures:
 *
 *	*nodep is NULL.
 */

isc_result_t
dns_db_expirenode(dns_db_t *db, dns_dbnode_t *node, isc_stdtime_t now);
/*
 * Mark as stale all records at 'node' which expire at or before 'now'.
 *
 * Note: if 'now' is zero, then the current time will be used.
 *
 * Requires:
 *
 *	'db' is a valid cache database.
 *
 *	'node' is a valid node.
 */

void
dns_db_printnode(dns_db_t *db, dns_dbnode_t *node, FILE *out);
/*
 * Print a textual representation of the contents of the node to
 * 'out'.
 *
 * Note: this function is intended for debugging, not general use.
 *
 * Requires:
 *
 *	'db' is a valid database.
 *
 *	'node' is a valid node.
 */

/***
 *** DB Iterator Creation
 ***/

isc_result_t
dns_db_createiterator(dns_db_t *db, isc_boolean_t relative_names,
		      dns_dbiterator_t **iteratorp);
/*
 * Create an iterator for version 'version' of 'db'.
 *
 * Notes:
 *
 *	If 'relative_names' is ISC_TRUE, then node names returned by the
 *	iterator will be relative to the iterator's current origin.  If
 *	ISC_FALSE, then the node names will be absolute.
 *
 * Requires:
 *
 *	'db' is a valid database.
 *
 *	iteratorp != NULL && *iteratorp == NULL
 *
 * Ensures:
 *
 *	On success, *iteratorp will be a valid database iterator.
 *
 * Returns:
 *
 *	ISC_R_SUCCESS
 *	ISC_R_NOMEMORY
 */

/***
 *** Rdataset Methods
 ***/

/*
 * XXXRTH  Should we check for glue and pending data in dns_db_findrdataset()?
 */

isc_result_t
dns_db_findrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
		    dns_rdatatype_t type, dns_rdatatype_t covers,
		    isc_stdtime_t now, dns_rdataset_t *rdataset,
		    dns_rdataset_t *sigrdataset);
/*
 * Search for an rdataset of type 'type' at 'node' that are in version
 * 'version' of 'db'.  If found, make 'rdataset' refer to it.
 *
 * Notes:
 *
 *	If 'version' is NULL, then the current version will be used.
 *
 *	Care must be used when using this routine to build a DNS response:
 *	'node' should have been found with dns_db_find(), not
 *	dns_db_findnode().  No glue checking is done.  No checking for
 *	pending data is done.
 *
 *	The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
 *	cache database, an rdataset will not be found unless it expires after
 *	'now'.  If 'now' is zero, then the current time will be used.
 *
 * Requires:
 *
 *	'db' is a valid database.
 *
 *	'node' is a valid node.
 *
 *	'rdataset' is a valid, disassociated rdataset.
 *
 *	'sigrdataset' is a valid, disassociated rdataset, or it is NULL.
 *
 *	If 'covers' != 0, 'type' must be SIG.
 *
 *	'type' is not a meta-RR type such as 'ANY' or 'OPT'.
 *
 * Ensures:
 *
 *	On success, 'rdataset' is associated with the found rdataset.
 *
 * Returns:
 *
 *	ISC_R_SUCCESS
 *	ISC_R_NOTFOUND
 *
 *	Other results are possible, depending upon the database
 *	implementation used.
 */

isc_result_t
dns_db_allrdatasets(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
		    isc_stdtime_t now, dns_rdatasetiter_t **iteratorp);
/*
 * Make '*iteratorp' an rdataset iteratator for all rdatasets at 'node' in
 * version 'version' of 'db'.
 *
 * Notes:
 *
 *	If 'version' is NULL, then the current version will be used.
 *
 *	The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
 *	cache database, an rdataset will not be found unless it expires after
 *	'now'.  Any ANY query will not match unless at least one rdataset at
 *	the node expires after 'now'.  If 'now' is zero, then the current time
 *	will be used.
 *
 * Requires:
 *
 *	'db' is a valid database.
 *
 *	'node' is a valid node.
 *
 *	iteratorp != NULL && *iteratorp == NULL
 *
 * Ensures:
 *
 *	On success, '*iteratorp' is a valid rdataset iterator.
 *
 * Returns:
 *
 *	ISC_R_SUCCESS
 *	ISC_R_NOTFOUND
 *
 *	Other results are possible, depending upon the database
 *	implementation used.
 */

isc_result_t
dns_db_addrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
		   isc_stdtime_t now, dns_rdataset_t *rdataset,
		   unsigned int options, dns_rdataset_t *addedrdataset);
/*
 * Add 'rdataset' to 'node' in version 'version' of 'db'.
 *
 * Notes:
 *
 *	If the database has zone semantics, the DNS_DBADD_MERGE option is set,
 *	and an rdataset of the same type as 'rdataset' already exists at
 *	'node' then the contents of 'rdataset' will be merged with the existing
 *	rdataset.  If the option is not set, then rdataset will replace any
 *	existing rdataset of the same type.  If not merging and the
 *	DNS_DBADD_FORCE option is set, then the data will update the database
 *	without regard to trust levels.  If not forcing the data, then the
 *	rdataset will only be added if its trust level is >= the trust level of
 *	any existing rdataset.  Forcing is only meaningful for cache databases.
 *	If DNS_DBADD_EXACT is set then there must be no rdata in common between
 *	the old and new rdata sets.  If DNS_DBADD_EXACTTTL is set then both
 *	the old and new rdata sets must have the same ttl.
 *
 *	The 'now' field is ignored if 'db' is a zone database.  If 'db' is
 *	a cache database, then the added rdataset will expire no later than
 *	now + rdataset->ttl.
 *
 *	If 'addedrdataset' is not NULL, then it will be attached to the
 *	resulting new rdataset in the database, or to the existing data if
 *	the existing data was better.
 *
 * Requires:
 *
 *	'db' is a valid database.
 *
 *	'node' is a valid node.
 *
 *	'rdataset' is a valid, associated rdataset with the same class
 *	as 'db'.
 *
 *	'addedrdataset' is NULL, or a valid, unassociated rdataset.
 *
 *	The database has zone semantics and 'version' is a valid
 *	read-write version, or the database has cache semantics
 *	and version is NULL.
 *
 *	If the database has cache semantics, the DNS_DBADD_MERGE option must
 *	not be set.
 *
 * Returns:
 *
 *	ISC_R_SUCCESS
 *	DNS_R_UNCHANGED			The operation did not change anything.
 *	ISC_R_NOMEMORY
 *	DNS_R_NOTEXACT
 *
 *	Other results are possible, depending upon the database
 *	implementation used.
 */

isc_result_t
dns_db_subtractrdataset(dns_db_t *db, dns_dbnode_t *node,
			dns_dbversion_t *version, dns_rdataset_t *rdataset,
			unsigned int options, dns_rdataset_t *newrdataset);
/*
 * Remove any rdata in 'rdataset' from 'node' in version 'version' of
 * 'db'.
 *
 * Notes:
 *
 *	If 'newrdataset' is not NULL, then it will be attached to the
 *	resulting new rdataset in the database, unless the rdataset has
 *	become nonexistent.  If DNS_DBSUB_EXACT is set then all elements
 *	of 'rdataset' must exist at 'node'.
 *
 * Requires:
 *
 *	'db' is a valid database.
 *
 *	'node' is a valid node.
 *
 *	'rdataset' is a valid, associated rdataset with the same class
 *	as 'db'.
 *
 *	'newrdataset' is NULL, or a valid, unassociated rdataset.
 *
 *	The database has zone semantics and 'version' is a valid
 *	read-write version.
 *
 * Returns:
 *
 *	ISC_R_SUCCESS
 *	DNS_R_UNCHANGED			The operation did not change anything.
 *	DNS_R_NXRRSET			All rdata of the same type as those
 *					in 'rdataset' have been deleted.
 *	DNS_R_NOTEXACT			Some part of 'rdataset' did not
 *					exist and DNS_DBSUB_EXACT was set.
 *
 *	Other results are possible, depending upon the database
 *	implementation used.
 */

isc_result_t
dns_db_deleterdataset(dns_db_t *db, dns_dbnode_t *node,
		      dns_dbversion_t *version, dns_rdatatype_t type,
		      dns_rdatatype_t covers);
/*
 * Make it so that no rdataset of type 'type' exists at 'node' in version
 * version 'version' of 'db'.
 *
 * Notes:
 *
 *	If 'type' is dns_rdatatype_any, then no rdatasets will exist in
 *	'version' (provided that the dns_db_deleterdataset() isn't followed
 *	by one or more dns_db_addrdataset() calls).
 *
 * Requires:
 *
 *	'db' is a valid database.
 *
 *	'node' is a valid node.
 *
 *	The database has zone semantics and 'version' is a valid
 *	read-write version, or the database has cache semantics
 *	and version is NULL.
 *
 *	'type' is not a meta-RR type, except for dns_rdatatype_any, which is
 *	allowed.
 *
 *	If 'covers' != 0, 'type' must be SIG.
 *
 * Returns:
 *
 *	ISC_R_SUCCESS
 *	DNS_R_UNCHANGED			No rdatasets of 'type' existed before
 *					the operation was attempted.
 *
 *	Other results are possible, depending upon the database
 *	implementation used.
 */

isc_result_t
dns_db_getsoaserial(dns_db_t *db, dns_dbversion_t *ver, isc_uint32_t *serialp);
/*
 * Get the current SOA serial number from a zone database.
 *
 * Requires:
 *      'db' is a valid database with zone semantics.
 *      'ver' is a valid version.
 */

void
dns_db_overmem(dns_db_t *db, isc_boolean_t overmem);
/*
 * Enable / disable agressive cache cleaning.
 */

unsigned int
dns_db_nodecount(dns_db_t *db);
/*
 * Count the number of nodes in 'db'.
 *
 * Requires:
 *
 *	'db' is a valid database.
 *
 * Returns:
 * 	The number of nodes in the database
 */

void
dns_db_settask(dns_db_t *db, isc_task_t *task);
/*
 * If task is set then the final detach maybe performed asynchronously.
 *
 * Requires:
 *	'db' is a valid database.
 *	'task' to be valid or NULL.
 */

isc_boolean_t
dns_db_ispersistent(dns_db_t *db);
/*
 * Is 'db' persistent?  A persistent database does not need to be loaded
 * from disk or written to disk.
 *
 * Requires:
 *
 *	'db' is a valid database.
 *
 * Returns:
 *	ISC_TRUE	'db' is persistent.
 *	ISC_FALSE	'db' is not persistent.
 */

isc_result_t
dns_db_register(const char *name, dns_dbcreatefunc_t create, void *driverarg,
		isc_mem_t *mctx, dns_dbimplementation_t **dbimp);

/*
 * Register a new database implementation and add it to the list of
 * supported implementations.
 *
 * Requires:
 *
 * 	'name' is not NULL
 * 	'order' is a valid function pointer
 * 	'mctx' is a valid memory context
 * 	dbimp != NULL && *dbimp == NULL
 *
 * Returns:
 * 	ISC_R_SUCCESS	The registration succeeded
 * 	ISC_R_NOMEMORY	Out of memory
 * 	ISC_R_EXISTS	A database implementation with the same name exists
 *
 * Ensures:
 *
 *	*dbimp points to an opaque structure which must be passed to
 *	dns_db_unregister().
 */

void
dns_db_unregister(dns_dbimplementation_t **dbimp);
/*
 * Remove a database implementation from the the list of supported
 * implementations.  No databases of this type can be active when this
 * is called.
 *
 * Requires:
 * 	dbimp != NULL && *dbimp == NULL
 *
 * Ensures:
 *
 * 	Any memory allocated in *dbimp will be freed.
 */

ISC_LANG_ENDDECLS

#endif /* DNS_DB_H */