rbt.h

bind 9.3结合mysql数据库

 *	If result is ISC_R_SUCCESS:
 *		*node is the terminal node for 'name'.
 *
 *		'foundname' and 'name' represent the same name (though not
 *		the same memory).
 *
 *		'chain' points to the DNSSEC predecessor, if any, of 'name'.
 *
 *		chain->level_matches and chain->level_count are equal.
 *
 * 	If result is DNS_R_PARTIALMATCH:
 *		*node is the data associated with the deepest superdomain
 * 		of 'name' which has data.
 *
 *		'foundname' is the name of deepest superdomain (which has
 *		data, unless the DNS_RBTFIND_EMPTYDATA option is set).
 *
 *		'chain' points to the DNSSEC predecessor, if any, of 'name'.
 *
 *	If result is ISC_R_NOTFOUND:
 *		Neither the name nor a superdomain was found.  *node is NULL.
 *
 *		'chain' points to the DNSSEC predecessor, if any, of 'name'.
 *
 *		chain->level_matches is 0.
 *
 * Returns:
 *	ISC_R_SUCCESS		Success
 *	DNS_R_PARTIALMATCH	Superdomain found with data
 *	ISC_R_NOTFOUND		No match, or superdomain with no data
 *	ISC_R_NOSPACE Concatenating nodes to form foundname failed
 */

isc_result_t
dns_rbt_deletename(dns_rbt_t *rbt, dns_name_t *name, isc_boolean_t recurse);
/*
 * Delete 'name' from the tree of trees.
 *
 * Notes:
 *	When 'name' is removed, if recurse is ISC_TRUE then all of its
 *      subnames are removed too.
 *
 * Requires:
 *	rbt is a valid rbt manager.
 *	dns_name_isabsolute(name) == TRUE
 *
 * Ensures:
 *	'name' is not altered in any way.
 *
 *	Does NOT ensure that any external references to nodes in the tree
 *	are unaffected by node joins.
 *
 *	If result is ISC_R_SUCCESS:
 *		'name' does not appear in the tree with data; however,
 *		the node for the name might still exist which can be
 *		found with dns_rbt_findnode (but not dns_rbt_findname).
 *
 *	If result is ISC_R_NOTFOUND:
 *		'name' does not appear in the tree with data, because
 *		it did not appear in the tree before the function was called.
 *
 *	If result is something else:
 *		See result codes for dns_rbt_findnode (if it fails, the
 *		node is not deleted) or dns_rbt_deletenode (if it fails,
 *		the node is deleted, but the tree is not optimized when
 *		it could have been).
 *
 * Returns:
 *	ISC_R_SUCCESS	Success
 *	ISC_R_NOTFOUND	No match
 *	something_else	Any return code from dns_rbt_findnode except
 *			DNS_R_PARTIALMATCH (which causes ISC_R_NOTFOUND
 *			to be returned instead), and any code from
 *			dns_rbt_deletenode.
 */

isc_result_t
dns_rbt_deletenode(dns_rbt_t *rbt, dns_rbtnode_t *node, isc_boolean_t recurse);
/*
 * Delete 'node' from the tree of trees.
 *
 * Notes:
 *	When 'node' is removed, if recurse is ISC_TRUE then all nodes
 *	in levels down from it are removed too.
 *
 * Requires:
 *	rbt is a valid rbt manager.
 *	node != NULL.
 *
 * Ensures:
 *	Does NOT ensure that any external references to nodes in the tree
 *	are unaffected by node joins.
 *
 *	If result is ISC_R_SUCCESS:
 *		'node' does not appear in the tree with data; however,
 *		the node might still exist if it serves as a pointer to
 *		a lower tree level as long as 'recurse' was false, hence
 *		the node could can be found with dns_rbt_findnode whem
 *		that function's empty_data_ok parameter is true.
 *
 *	If result is ISC_R_NOMEMORY or ISC_R_NOSPACE:
 *		The node was deleted, but the tree structure was not
 *		optimized.
 *
 * Returns:
 *	ISC_R_SUCCESS	Success
 *	ISC_R_NOMEMORY	Resource Limit: Out of Memory when joining nodes.
 *	ISC_R_NOSPACE	dns_name_concatenate failed when joining nodes.
 */

void
dns_rbt_namefromnode(dns_rbtnode_t *node, dns_name_t *name);
/*
 * Convert the sequence of labels stored at 'node' into a 'name'.
 *
 * Notes:
 *	This function does not return the full name, from the root, but
 *	just the labels at the indicated node.
 *
 *	The name data pointed to by 'name' is the information stored
 *	in the node, not a copy.  Altering the data at this pointer
 *	will likely cause grief.
 *
 * Requires:
 *	name->offsets == NULL
 *
 * Ensures:
 *	'name' is DNS_NAMEATTR_READONLY.
 *
 *	'name' will point directly to the labels stored after the
 *	dns_rbtnode_t struct.
 *
 *	'name' will have offsets that also point to the information stored
 *	as part of the node.
 */

isc_result_t
dns_rbt_fullnamefromnode(dns_rbtnode_t *node, dns_name_t *name);
/*
 * Like dns_rbt_namefromnode, but returns the full name from the root.
 *
 * Notes:
 *	Unlike dns_rbt_namefromnode, the name will not point directly
 *	to node data.  Rather, dns_name_concatenate will be used to copy
 *	the name data from each node into the 'name' argument.
 *
 * Requires:
 *	name != NULL
 *	name has a dedicated buffer.
 *
 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_NOSPACE		(possible via dns_name_concatenate)
 *	DNS_R_NAMETOOLONG	(possible via dns_name_concatenate)
 */

char *
dns_rbt_formatnodename(dns_rbtnode_t *node, char *printname,
		       unsigned int size);
/*
 * Format the full name of a node for printing, using dns_name_format().
 *
 * Notes:
 *	'size' is the length of the printname buffer.  This should be
 *	DNS_NAME_FORMATSIZE or larger.
 *
 * Requires:
 *	node and printname are not NULL.
 *
 * Returns:
 *	The 'printname' pointer.
 */

unsigned int
dns_rbt_nodecount(dns_rbt_t *rbt);
/*
 * Obtain the number of nodes in the tree of trees.
 *
 * Requires:
 *	rbt is a valid rbt manager.
 */

void
dns_rbt_destroy(dns_rbt_t **rbtp);
isc_result_t
dns_rbt_destroy2(dns_rbt_t **rbtp, unsigned int quantum);
/*
 * Stop working with a red-black tree of trees.  Once dns_rbt_destroy2()
 * has been called on a 'rbt' only dns_rbt_destroy() or dns_rbt_destroy2()
 * may be used on the tree.  If 'quantum' is zero then the entire tree will
 * be destroyed.
 *
 * Requires:
 * 	*rbt is a valid rbt manager.
 *
 * Ensures:
 *	All space allocated by the RBT library has been returned.
 *
 *	*rbt is invalidated as an rbt manager.
 *
 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_QUOTA if 'quantum' nodes have been destroyed.
 */

void
dns_rbt_printall(dns_rbt_t *rbt);
/*
 * Print an ASCII representation of the internal structure of the red-black
 * tree of trees.
 *
 * Notes:
 *	The name stored at each node, along with the node's color, is printed.
 *	Then the down pointer, left and right pointers are displayed
 *	recursively in turn.  NULL down pointers are silently omitted;
 *	NULL left and right pointers are printed.
 */

/*****
 ***** Chain Functions
 *****/

void
dns_rbtnodechain_init(dns_rbtnodechain_t *chain, isc_mem_t *mctx);
/*
 * Initialize 'chain'.
 *
 * Requires:
 *	'chain' is a valid pointer.
 *
 *	'mctx' is a valid memory context.
 *
 * Ensures:
 *	'chain' is suitable for use.
 */

void
dns_rbtnodechain_reset(dns_rbtnodechain_t *chain);
/*
 * Free any dynamic storage associated with 'chain', and then reinitialize
 * 'chain'.
 *
 * Requires:
 *	'chain' is a valid pointer.
 *
 * Ensures:
 *	'chain' is suitable for use, and uses no dynamic storage.
 */

void
dns_rbtnodechain_invalidate(dns_rbtnodechain_t *chain);
/*
 * Free any dynamic storage associated with 'chain', and then invalidates it.
 *
 * Notes:
 * 	Future calls to any dns_rbtnodechain_ function will need to call
 * 	dns_rbtnodechain_init on the chain first (except, of course,
 *	dns_rbtnodechain_init itself).
 *
 * Requires:
 *	'chain' is a valid chain.
 *
 * Ensures:
 *	'chain' is no longer suitable for use, and uses no dynamic storage.
 */

isc_result_t
dns_rbtnodechain_current(dns_rbtnodechain_t *chain, dns_name_t *name,
			 dns_name_t *origin, dns_rbtnode_t **node);
/*
 * Provide the name, origin and node to which the chain is currently pointed.
 *
 * Notes:
 *	The tree need not have be locked against additions for the chain
 *	to remain valid, however there are no guarantees if any deletion
 *	has been made since the chain was established.
 *
 * Requires:
 *	'chain' is a valid chain.
 *
 * Ensures:
 *	'node', if non-NULL, is the node to which the chain was pointed
 *	by dns_rbt_findnode, dns_rbtnodechain_first or dns_rbtnodechain_last.
 *	If none were called for the chain since it was initialized or reset,
 *	or if the was no predecessor to the name searched for with
 *	dns_rbt_findnode, then '*node' is NULL and ISC_R_NOTFOUND is returned.
 *
 *	'name', if non-NULL, is the name stored at the terminal level of
 *	the chain.  This is typically a single label, like the "www" of
 *	"www.isc.org", but need not be so.  At the root of the tree of trees,
 *	if the node is "." then 'name' is ".", otherwise it is relative to ".".
 *	(Minimalist and atypical case:  if the tree has just the name
 *	"isc.org." then the root node's stored name is "isc.org." but 'name'
 *	will be "isc.org".)
 *
 *	'origin', if non-NULL, is the sequence of labels in the levels
 *	above the terminal level, such as "isc.org." in the above example.
 *	'origin' is always "." for the root node.
 *
 *
 * Returns:
 *	ISC_R_SUCCESS		name, origin & node were successfully set.
 *	ISC_R_NOTFOUND		The chain does not point to any node.
 *	<something_else>	Any error return from dns_name_concatenate.
 */

isc_result_t
dns_rbtnodechain_first(dns_rbtnodechain_t *chain, dns_rbt_t *rbt,
		       dns_name_t *name, dns_name_t *origin);
/*
 * Set the chain to the lexically first node in the tree of trees.
 *
 * Notes:
 *	By the definition of ordering for DNS names, the root of the tree of
 *	trees is the very first node, since everything else in the megatree
 *	uses it as a common suffix.
 *
 * Requires:
 *	'chain' is a valid chain.
 *	'rbt' is a valid rbt manager.
 *
 * Ensures:
 *	The chain points to the very first node of the tree.
 *
 *	'name' and 'origin', if non-NULL, are set as described for
 *	dns_rbtnodechain_current.  Thus 'origin' will always be ".".
 *
 * Returns:
 *	DNS_R_NEWORIGIN		The name & origin were successfully set.
 *	<something_else>	Any error result from dns_rbtnodechain_current.
 */

isc_result_t
dns_rbtnodechain_last(dns_rbtnodechain_t *chain, dns_rbt_t *rbt,
		       dns_name_t *name, dns_name_t *origin);
/*
 * Set the chain to the lexically last node in the tree of trees.
 *
 * Requires:
 *	'chain' is a valid chain.
 *	'rbt' is a valid rbt manager.
 *
 * Ensures:
 *	The chain points to the very last node of the tree.
 *
 *	'name' and 'origin', if non-NULL, are set as described for
 *	dns_rbtnodechain_current.
 *
 * Returns:
 *	DNS_R_NEWORIGIN		The name & origin were successfully set.
 *	ISC_R_NOMEMORY		Resource Limit: Out of Memory building chain.
 *	<something_else>	Any error result from dns_name_concatenate.
 */

isc_result_t
dns_rbtnodechain_prev(dns_rbtnodechain_t *chain, dns_name_t *name,
		      dns_name_t *origin);
/*
 * Adjusts chain to point the DNSSEC predecessor of the name to which it
 * is currently pointed.
 *
 * Requires:
 *	'chain' is a valid chain.
 *	'chain' has been pointed somewhere in the tree with dns_rbt_findnode,
 *	dns_rbtnodechain_first or dns_rbtnodechain_last -- and remember that
 *	dns_rbt_findnode is not guaranteed to point the chain somewhere,
 *	since there may have been no predecessor to the searched for name.
 *
 * Ensures:
 *	The chain is pointed to the predecessor of its current target.
 *
 *	'name' and 'origin', if non-NULL, are set as described for
 *	dns_rbtnodechain_current.
 *
 *	'origin' is only if a new origin was found.
 *
 * Returns:
 *	ISC_R_SUCCESS		The predecessor was found and 'name' was set.
 *	DNS_R_NEWORIGIN		The predecessor was found with a different
 *				origin and 'name' and 'origin' were set.
 *	ISC_R_NOMORE		There was no predecessor.
 *	<something_else>	Any error result from dns_rbtnodechain_current.
 */

isc_result_t
dns_rbtnodechain_next(dns_rbtnodechain_t *chain, dns_name_t *name,
		      dns_name_t *origin);
/*
 * Adjusts chain to point the DNSSEC successor of the name to which it
 * is currently pointed.
 *
 * Requires:
 *	'chain' is a valid chain.
 *	'chain' has been pointed somewhere in the tree with dns_rbt_findnode,
 *	dns_rbtnodechain_first or dns_rbtnodechain_last -- and remember that
 *	dns_rbt_findnode is not guaranteed to point the chain somewhere,
 *	since there may have been no predecessor to the searched for name.
 *
 * Ensures:
 *	The chain is pointed to the successor of its current target.
 *
 *	'name' and 'origin', if non-NULL, are set as described for
 *	dns_rbtnodechain_current.
 *
 *	'origin' is only if a new origin was found.
 *
 * Returns:
 *	ISC_R_SUCCESS		The successor was found and 'name' was set.
 *	DNS_R_NEWORIGIN		The successor was found with a different
 *				origin and 'name' and 'origin' were set.
 *	ISC_R_NOMORE		There was no successor.
 *	<something_else>	Any error result from dns_name_concatenate.
 */

ISC_LANG_ENDDECLS

#endif /* DNS_RBT_H */