diff options
Diffstat (limited to 'lib/dns/include/dns/dbiterator.h')
| -rw-r--r-- | lib/dns/include/dns/dbiterator.h | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/lib/dns/include/dns/dbiterator.h b/lib/dns/include/dns/dbiterator.h new file mode 100644 index 0000000..366d676 --- /dev/null +++ b/lib/dns/include/dns/dbiterator.h @@ -0,0 +1,297 @@ +/* + * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 1999-2001 Internet Software Consortium. + * + * Permission to use, copy, modify, and/or 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 ISC DISCLAIMS ALL WARRANTIES WITH + * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + * AND FITNESS. IN NO EVENT SHALL ISC 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: dbiterator.h,v 1.25 2007/06/19 23:47:16 tbox Exp $ */ + +#ifndef DNS_DBITERATOR_H +#define DNS_DBITERATOR_H 1 + +/***** + ***** Module Info + *****/ + +/*! \file dns/dbiterator.h + * \brief + * The DNS DB Iterator interface allows iteration of all of the nodes in a + * database. + * + * The dns_dbiterator_t type is like a "virtual class". To actually use + * it, an implementation of the class is required. This implementation is + * supplied by the database. + * + * It is the client's responsibility to call dns_db_detachnode() on all + * nodes returned. + * + * XXX <more> XXX + * + * MP: + *\li The iterator itself is not locked. The caller must ensure + * synchronization. + * + *\li The iterator methods ensure appropriate database locking. + * + * Reliability: + *\li No anticipated impact. + * + * Resources: + *\li TBS + * + * Security: + *\li No anticipated impact. + * + * Standards: + *\li None. + */ + +/***** + ***** Imports + *****/ + +#include <isc/lang.h> +#include <isc/magic.h> + +#include <dns/types.h> + +ISC_LANG_BEGINDECLS + +/***** + ***** Types + *****/ + +typedef struct dns_dbiteratormethods { + void (*destroy)(dns_dbiterator_t **iteratorp); + isc_result_t (*first)(dns_dbiterator_t *iterator); + isc_result_t (*last)(dns_dbiterator_t *iterator); + isc_result_t (*seek)(dns_dbiterator_t *iterator, dns_name_t *name); + isc_result_t (*prev)(dns_dbiterator_t *iterator); + isc_result_t (*next)(dns_dbiterator_t *iterator); + isc_result_t (*current)(dns_dbiterator_t *iterator, + dns_dbnode_t **nodep, dns_name_t *name); + isc_result_t (*pause)(dns_dbiterator_t *iterator); + isc_result_t (*origin)(dns_dbiterator_t *iterator, + dns_name_t *name); +} dns_dbiteratormethods_t; + +#define DNS_DBITERATOR_MAGIC ISC_MAGIC('D','N','S','I') +#define DNS_DBITERATOR_VALID(dbi) ISC_MAGIC_VALID(dbi, DNS_DBITERATOR_MAGIC) +/*% + * This structure is actually just the common prefix of a DNS db + * implementation's version of a dns_dbiterator_t. + * + * Clients may use the 'db' field of this structure. Except for that field, + * direct use of this structure by clients is forbidden. DB implementations + * may change the structure. 'magic' must be DNS_DBITERATOR_MAGIC for any of + * the dns_dbiterator routines to work. DB iterator implementations must + * maintain all DB iterator invariants. + */ +struct dns_dbiterator { + /* Unlocked. */ + unsigned int magic; + dns_dbiteratormethods_t * methods; + dns_db_t * db; + isc_boolean_t relative_names; + isc_boolean_t cleaning; +}; + +void +dns_dbiterator_destroy(dns_dbiterator_t **iteratorp); +/*%< + * Destroy '*iteratorp'. + * + * Requires: + * + *\li '*iteratorp' is a valid iterator. + * + * Ensures: + * + *\li All resources used by the iterator are freed. + * + *\li *iteratorp == NULL. + */ + +isc_result_t +dns_dbiterator_first(dns_dbiterator_t *iterator); +/*%< + * Move the node cursor to the first node in the database (if any). + * + * Requires: + *\li 'iterator' is a valid iterator. + * + * Returns: + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE There are no nodes in the database. + * + *\li Other results are possible, depending on the DB implementation. + */ + +isc_result_t +dns_dbiterator_last(dns_dbiterator_t *iterator); +/*%< + * Move the node cursor to the last node in the database (if any). + * + * Requires: + *\li 'iterator' is a valid iterator. + * + * Returns: + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE There are no nodes in the database. + * + *\li Other results are possible, depending on the DB implementation. + */ + +isc_result_t +dns_dbiterator_seek(dns_dbiterator_t *iterator, dns_name_t *name); +/*%< + * Move the node cursor to the node with name 'name'. + * + * Requires: + *\li 'iterator' is a valid iterator. + * + *\li 'name' is a valid name. + * + * Returns: + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOTFOUND + * + *\li Other results are possible, depending on the DB implementation. + */ + +isc_result_t +dns_dbiterator_prev(dns_dbiterator_t *iterator); +/*%< + * Move the node cursor to the previous node in the database (if any). + * + * Requires: + *\li 'iterator' is a valid iterator. + * + * Returns: + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE There are no more nodes in the + * database. + * + *\li Other results are possible, depending on the DB implementation. + */ + +isc_result_t +dns_dbiterator_next(dns_dbiterator_t *iterator); +/*%< + * Move the node cursor to the next node in the database (if any). + * + * Requires: + *\li 'iterator' is a valid iterator. + * + * Returns: + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE There are no more nodes in the + * database. + * + *\li Other results are possible, depending on the DB implementation. + */ + +isc_result_t +dns_dbiterator_current(dns_dbiterator_t *iterator, dns_dbnode_t **nodep, + dns_name_t *name); +/*%< + * Return the current node. + * + * Notes: + *\li If 'name' is not NULL, it will be set to the name of the node. + * + * Requires: + *\li 'iterator' is a valid iterator. + * + *\li nodep != NULL && *nodep == NULL + * + *\li The node cursor of 'iterator' is at a valid location (i.e. the + * result of last call to a cursor movement command was ISC_R_SUCCESS). + * + *\li 'name' is NULL, or is a valid name with a dedicated buffer. + * + * Returns: + * + *\li #ISC_R_SUCCESS + *\li #DNS_R_NEWORIGIN If this iterator was created with + * 'relative_names' set to ISC_TRUE, + * then #DNS_R_NEWORIGIN will be returned + * when the origin the names are + * relative to changes. This result + * can occur only when 'name' is not + * NULL. This is also a successful + * result. + * + *\li Other results are possible, depending on the DB implementation. + */ + +isc_result_t +dns_dbiterator_pause(dns_dbiterator_t *iterator); +/*%< + * Pause iteration. + * + * Calling a cursor movement method or dns_dbiterator_current() may cause + * database locks to be acquired. Rather than reacquire these locks every + * time one of these routines is called, the locks may simply be held. + * Calling dns_dbiterator_pause() releases any such locks. Iterator clients + * should call this routine any time they are not going to execute another + * iterator method in the immediate future. + * + * Requires: + *\li 'iterator' is a valid iterator. + * + * Ensures: + *\li Any database locks being held for efficiency of iterator access are + * released. + * + * Returns: + *\li #ISC_R_SUCCESS + * + *\li Other results are possible, depending on the DB implementation. + */ + +isc_result_t +dns_dbiterator_origin(dns_dbiterator_t *iterator, dns_name_t *name); +/*%< + * Return the origin to which returned node names are relative. + * + * Requires: + * + *\li 'iterator' is a valid relative_names iterator. + * + *\li 'name' is a valid name with a dedicated buffer. + * + * Returns: + * + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOSPACE + * + *\li Other results are possible, depending on the DB implementation. + */ + +void +dns_dbiterator_setcleanmode(dns_dbiterator_t *iterator, isc_boolean_t mode); +/*%< + * Indicate that the given iterator is/is not cleaning the DB. + * + * Notes: + *\li When 'mode' is ISC_TRUE, + * + * Requires: + *\li 'iterator' is a valid iterator. + */ + +ISC_LANG_ENDDECLS + +#endif /* DNS_DBITERATOR_H */ |