mirror of
https://github.com/isc-projects/bind9.git
synced 2026-03-03 05:50:39 -05:00
297 lines
7.7 KiB
C
297 lines
7.7 KiB
C
/*
|
|
* 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 */
|