/*
* Copyright (C) Internet Systems Consortium, Inc. ("ISC")
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, you can obtain one at https://mozilla.org/MPL/2.0/.
*
* See the COPYRIGHT file distributed with this work for additional
* information regarding copyright ownership.
*/
#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 <stdbool.h>
#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,
const 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;
bool relative_names;
bool 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, const 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 #DNS_R_PARTIALMATCH
* (node is at name above requested named when name has children)
*
*\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 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, bool mode);
/*%<
* Indicate that the given iterator is/is not cleaning the DB.
*
* Notes:
*\li When 'mode' is true,
*
* Requires:
*\li 'iterator' is a valid iterator.
*/
ISC_LANG_ENDDECLS
#endif /* DNS_DBITERATOR_H */
