1/* $NetBSD: zt.h,v 1.9 2024/02/21 22:52:11 christos Exp $ */ 2 3/* 4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5 * 6 * SPDX-License-Identifier: MPL-2.0 7 * 8 * This Source Code Form is subject to the terms of the Mozilla Public 9 * License, v. 2.0. If a copy of the MPL was not distributed with this 10 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11 * 12 * See the COPYRIGHT file distributed with this work for additional 13 * information regarding copyright ownership. 14 */ 15 16#pragma once 17 18/*! \file dns/zt.h */ 19 20#include <stdbool.h> 21 22#include <isc/lang.h> 23#include <isc/rwlock.h> 24 25#include <dns/types.h> 26 27#define DNS_ZTFIND_NOEXACT 0x01 28#define DNS_ZTFIND_MIRROR 0x02 29 30ISC_LANG_BEGINDECLS 31 32typedef isc_result_t (*dns_zt_allloaded_t)(void *arg); 33/*%< 34 * Method prototype: when all pending zone loads are complete, 35 * the zone table can inform the caller via a callback function with 36 * this signature. 37 */ 38 39typedef isc_result_t (*dns_zt_zoneloaded_t)(dns_zt_t *zt, dns_zone_t *zone, 40 isc_task_t *task); 41/*%< 42 * Method prototype: when a zone finishes loading, the zt object 43 * can be informed via a callback function with this signature. 44 */ 45 46isc_result_t 47dns_zt_create(isc_mem_t *mctx, dns_rdataclass_t rdclass, dns_zt_t **zt); 48/*%< 49 * Creates a new zone table. 50 * 51 * Requires: 52 * \li 'mctx' to be initialized. 53 * 54 * Returns: 55 * \li #ISC_R_SUCCESS on success. 56 * \li #ISC_R_NOMEMORY 57 */ 58 59isc_result_t 60dns_zt_mount(dns_zt_t *zt, dns_zone_t *zone); 61/*%< 62 * Mounts the zone on the zone table. 63 * 64 * Requires: 65 * \li 'zt' to be valid 66 * \li 'zone' to be valid 67 * 68 * Returns: 69 * \li #ISC_R_SUCCESS 70 * \li #ISC_R_EXISTS 71 * \li #ISC_R_NOSPACE 72 * \li #ISC_R_NOMEMORY 73 */ 74 75isc_result_t 76dns_zt_unmount(dns_zt_t *zt, dns_zone_t *zone); 77/*%< 78 * Unmount the given zone from the table. 79 * 80 * Requires: 81 * 'zt' to be valid 82 * \li 'zone' to be valid 83 * 84 * Returns: 85 * \li #ISC_R_SUCCESS 86 * \li #ISC_R_NOTFOUND 87 * \li #ISC_R_NOMEMORY 88 */ 89 90isc_result_t 91dns_zt_find(dns_zt_t *zt, const dns_name_t *name, unsigned int options, 92 dns_name_t *foundname, dns_zone_t **zone); 93/*%< 94 * Find the best match for 'name' in 'zt'. If foundname is non NULL 95 * then the name of the zone found is returned. 96 * 97 * Notes: 98 * \li If the DNS_ZTFIND_NOEXACT is set, the best partial match (if any) 99 * to 'name' will be returned. 100 * 101 * Requires: 102 * \li 'zt' to be valid 103 * \li 'name' to be valid 104 * \li 'foundname' to be initialized and associated with a fixedname or NULL 105 * \li 'zone' to be non NULL and '*zone' to be NULL 106 * 107 * Returns: 108 * \li #ISC_R_SUCCESS 109 * \li #DNS_R_PARTIALMATCH 110 * \li #ISC_R_NOTFOUND 111 * \li #ISC_R_NOSPACE 112 */ 113 114void 115dns_zt_detach(dns_zt_t **ztp); 116/*%< 117 * Detach the given zonetable, if the reference count goes to zero the 118 * zonetable will be freed. In either case 'ztp' is set to NULL. 119 * 120 * Requires: 121 * \li '*ztp' to be valid 122 */ 123 124void 125dns_zt_flush(dns_zt_t *ztp); 126/*%< 127 * Schedule flushing of the given zonetable, when reference count goes 128 * to zero. 129 * 130 * Requires: 131 * \li 'ztp' to be valid 132 */ 133 134void 135dns_zt_attach(dns_zt_t *zt, dns_zt_t **ztp); 136/*%< 137 * Attach 'zt' to '*ztp'. 138 * 139 * Requires: 140 * \li 'zt' to be valid 141 * \li '*ztp' to be NULL 142 */ 143 144isc_result_t 145dns_zt_load(dns_zt_t *zt, bool stop, bool newonly); 146 147isc_result_t 148dns_zt_asyncload(dns_zt_t *zt, bool newonly, dns_zt_allloaded_t alldone, 149 void *arg); 150/*%< 151 * Load all zones in the table. If 'stop' is true, 152 * stop on the first error and return it. If 'stop' 153 * is false, ignore errors. 154 * 155 * if newonly is set only zones that were never loaded are loaded. 156 * dns_zt_asyncload() loads zones asynchronously; when all 157 * zones in the zone table have finished loaded (or failed due 158 * to errors), the caller is informed by calling 'alldone' 159 * with an argument of 'arg'. 160 * 161 * Requires: 162 * \li 'zt' to be valid 163 */ 164 165isc_result_t 166dns_zt_freezezones(dns_zt_t *zt, dns_view_t *view, bool freeze); 167/*%< 168 * Freeze/thaw updates to primary zones. 169 * Any pending updates will be flushed. 170 * Zones will be reloaded on thaw. 171 */ 172 173isc_result_t 174dns_zt_apply(dns_zt_t *zt, isc_rwlocktype_t lock, bool stop, isc_result_t *sub, 175 isc_result_t (*action)(dns_zone_t *, void *), void *uap); 176/*%< 177 * Apply a given 'action' to all zone zones in the table. 178 * If 'stop' is 'true' then walking the zone tree will stop if 179 * 'action' does not return ISC_R_SUCCESS. 180 * 181 * Requires: 182 * \li 'zt' to be valid. 183 * \li 'action' to be non NULL. 184 * 185 * Returns: 186 * \li ISC_R_SUCCESS if action was applied to all nodes. If 'stop' is 187 * false and 'sub' is non NULL then the first error (if any) 188 * reported by 'action' is returned in '*sub'; 189 * any error code from 'action'. 190 */ 191 192bool 193dns_zt_loadspending(dns_zt_t *zt); 194/*%< 195 * Returns true if and only if there are zones still waiting to 196 * be loaded in zone table 'zt'. 197 * 198 * Requires: 199 * \li 'zt' to be valid. 200 */ 201 202void 203dns_zt_setviewcommit(dns_zt_t *zt); 204/*%< 205 * Commit dns_zone_setview() calls previously made for all zones in this 206 * zone table. 207 * 208 * Requires: 209 *\li 'view' to be valid. 210 */ 211 212void 213dns_zt_setviewrevert(dns_zt_t *zt); 214/*%< 215 * Revert dns_zone_setview() calls previously made for all zones in this 216 * zone table. 217 * 218 * Requires: 219 *\li 'view' to be valid. 220 */ 221 222ISC_LANG_ENDDECLS 223