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