/contrib/bind9/lib/dns/include/dns/dbiterator.h
https://bitbucket.org/freebsd/freebsd-head/ · C Header · 297 lines · 51 code · 23 blank · 223 comment · 0 complexity · ebb17eb3dc4567cc438ccc3dd22d7654 MD5 · raw file
- /*
- * 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 */