1135446Strhodes/* 2193149Sdougb * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC") 3135446Strhodes * Copyright (C) 1999-2001 Internet Software Consortium. 4135446Strhodes * 5193149Sdougb * Permission to use, copy, modify, and/or distribute this software for any 6135446Strhodes * purpose with or without fee is hereby granted, provided that the above 7135446Strhodes * copyright notice and this permission notice appear in all copies. 8135446Strhodes * 9135446Strhodes * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10135446Strhodes * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11135446Strhodes * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12135446Strhodes * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13135446Strhodes * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14135446Strhodes * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15135446Strhodes * PERFORMANCE OF THIS SOFTWARE. 16135446Strhodes */ 17135446Strhodes 18234010Sdougb/* $Id: rdatasetiter.h,v 1.21 2007/06/19 23:47:17 tbox Exp $ */ 19135446Strhodes 20135446Strhodes#ifndef DNS_RDATASETITER_H 21135446Strhodes#define DNS_RDATASETITER_H 1 22135446Strhodes 23135446Strhodes/***** 24135446Strhodes ***** Module Info 25135446Strhodes *****/ 26135446Strhodes 27193149Sdougb/*! \file dns/rdatasetiter.h 28170222Sdougb * \brief 29135446Strhodes * The DNS Rdataset Iterator interface allows iteration of all of the 30135446Strhodes * rdatasets at a node. 31135446Strhodes * 32135446Strhodes * The dns_rdatasetiter_t type is like a "virtual class". To actually use 33135446Strhodes * it, an implementation of the class is required. This implementation is 34135446Strhodes * supplied by the database. 35135446Strhodes * 36135446Strhodes * It is the client's responsibility to call dns_rdataset_disassociate() 37135446Strhodes * on all rdatasets returned. 38135446Strhodes * 39170222Sdougb * XXX more XXX 40135446Strhodes * 41135446Strhodes * MP: 42170222Sdougb *\li The iterator itself is not locked. The caller must ensure 43135446Strhodes * synchronization. 44135446Strhodes * 45170222Sdougb *\li The iterator methods ensure appropriate database locking. 46135446Strhodes * 47135446Strhodes * Reliability: 48170222Sdougb *\li No anticipated impact. 49135446Strhodes * 50135446Strhodes * Resources: 51170222Sdougb *\li TBS 52135446Strhodes * 53135446Strhodes * Security: 54170222Sdougb *\li No anticipated impact. 55135446Strhodes * 56135446Strhodes * Standards: 57170222Sdougb *\li None. 58135446Strhodes */ 59135446Strhodes 60135446Strhodes/***** 61135446Strhodes ***** Imports 62135446Strhodes *****/ 63135446Strhodes 64135446Strhodes#include <isc/lang.h> 65135446Strhodes#include <isc/magic.h> 66135446Strhodes#include <isc/stdtime.h> 67135446Strhodes 68135446Strhodes#include <dns/types.h> 69135446Strhodes 70135446StrhodesISC_LANG_BEGINDECLS 71135446Strhodes 72135446Strhodes/***** 73135446Strhodes ***** Types 74135446Strhodes *****/ 75135446Strhodes 76135446Strhodestypedef struct dns_rdatasetitermethods { 77135446Strhodes void (*destroy)(dns_rdatasetiter_t **iteratorp); 78135446Strhodes isc_result_t (*first)(dns_rdatasetiter_t *iterator); 79135446Strhodes isc_result_t (*next)(dns_rdatasetiter_t *iterator); 80135446Strhodes void (*current)(dns_rdatasetiter_t *iterator, 81135446Strhodes dns_rdataset_t *rdataset); 82135446Strhodes} dns_rdatasetitermethods_t; 83135446Strhodes 84135446Strhodes#define DNS_RDATASETITER_MAGIC ISC_MAGIC('D','N','S','i') 85135446Strhodes#define DNS_RDATASETITER_VALID(i) ISC_MAGIC_VALID(i, DNS_RDATASETITER_MAGIC) 86135446Strhodes 87170222Sdougb/*% 88135446Strhodes * This structure is actually just the common prefix of a DNS db 89135446Strhodes * implementation's version of a dns_rdatasetiter_t. 90170222Sdougb * \brief 91135446Strhodes * Direct use of this structure by clients is forbidden. DB implementations 92170222Sdougb * may change the structure. 'magic' must be #DNS_RDATASETITER_MAGIC for 93135446Strhodes * any of the dns_rdatasetiter routines to work. DB implementations must 94135446Strhodes * maintain all DB rdataset iterator invariants. 95135446Strhodes */ 96135446Strhodesstruct dns_rdatasetiter { 97135446Strhodes /* Unlocked. */ 98135446Strhodes unsigned int magic; 99135446Strhodes dns_rdatasetitermethods_t * methods; 100135446Strhodes dns_db_t * db; 101135446Strhodes dns_dbnode_t * node; 102135446Strhodes dns_dbversion_t * version; 103135446Strhodes isc_stdtime_t now; 104135446Strhodes}; 105135446Strhodes 106135446Strhodesvoid 107135446Strhodesdns_rdatasetiter_destroy(dns_rdatasetiter_t **iteratorp); 108170222Sdougb/*%< 109135446Strhodes * Destroy '*iteratorp'. 110135446Strhodes * 111135446Strhodes * Requires: 112135446Strhodes * 113170222Sdougb *\li '*iteratorp' is a valid iterator. 114135446Strhodes * 115135446Strhodes * Ensures: 116135446Strhodes * 117170222Sdougb *\li All resources used by the iterator are freed. 118135446Strhodes * 119170222Sdougb *\li *iteratorp == NULL. 120135446Strhodes */ 121135446Strhodes 122135446Strhodesisc_result_t 123135446Strhodesdns_rdatasetiter_first(dns_rdatasetiter_t *iterator); 124170222Sdougb/*%< 125135446Strhodes * Move the rdataset cursor to the first rdataset at the node (if any). 126135446Strhodes * 127135446Strhodes * Requires: 128170222Sdougb *\li 'iterator' is a valid iterator. 129135446Strhodes * 130135446Strhodes * Returns: 131170222Sdougb *\li ISC_R_SUCCESS 132170222Sdougb *\li ISC_R_NOMORE There are no rdatasets at the node. 133135446Strhodes * 134170222Sdougb *\li Other results are possible, depending on the DB implementation. 135135446Strhodes */ 136135446Strhodes 137135446Strhodesisc_result_t 138135446Strhodesdns_rdatasetiter_next(dns_rdatasetiter_t *iterator); 139170222Sdougb/*%< 140135446Strhodes * Move the rdataset cursor to the next rdataset at the node (if any). 141135446Strhodes * 142135446Strhodes * Requires: 143170222Sdougb *\li 'iterator' is a valid iterator. 144135446Strhodes * 145135446Strhodes * Returns: 146170222Sdougb *\li ISC_R_SUCCESS 147170222Sdougb *\li ISC_R_NOMORE There are no more rdatasets at the 148135446Strhodes * node. 149135446Strhodes * 150170222Sdougb *\li Other results are possible, depending on the DB implementation. 151135446Strhodes */ 152135446Strhodes 153135446Strhodesvoid 154135446Strhodesdns_rdatasetiter_current(dns_rdatasetiter_t *iterator, 155135446Strhodes dns_rdataset_t *rdataset); 156170222Sdougb/*%< 157135446Strhodes * Return the current rdataset. 158135446Strhodes * 159135446Strhodes * Requires: 160170222Sdougb *\li 'iterator' is a valid iterator. 161135446Strhodes * 162170222Sdougb *\li 'rdataset' is a valid, disassociated rdataset. 163135446Strhodes * 164170222Sdougb *\li The rdataset cursor of 'iterator' is at a valid location (i.e. the 165170222Sdougb * result of last call to a cursor movement command was #ISC_R_SUCCESS). 166135446Strhodes */ 167135446Strhodes 168135446StrhodesISC_LANG_ENDDECLS 169135446Strhodes 170135446Strhodes#endif /* DNS_RDATASETITER_H */ 171