1 /* $NetBSD: dyndb.h,v 1.9 2025/01/26 16:25:27 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 #include <stdbool.h> 19 20 #include <isc/types.h> 21 22 #include <dns/types.h> 23 24 ISC_LANG_BEGINDECLS 25 26 /*! 27 * \brief 28 * Context for initializing a dyndb module. 29 * 30 * This structure passes global server data to which a dyndb 31 * module will need access -- the server memory context, hash 32 * initializer, log context, etc. The structure doesn't persist 33 * beyond configuring the dyndb module. The module's register function 34 * should attach to all reference-counted variables and its destroy 35 * function should detach from them. 36 */ 37 struct dns_dyndbctx { 38 unsigned int magic; 39 const void *hashinit; 40 isc_mem_t *mctx; 41 isc_log_t *lctx; 42 dns_view_t *view; 43 dns_zonemgr_t *zmgr; 44 isc_loopmgr_t *loopmgr; 45 const bool *refvar; /* unused, but retained for API compatibility */ 46 }; 47 48 #define DNS_DYNDBCTX_MAGIC ISC_MAGIC('D', 'd', 'b', 'c') 49 #define DNS_DYNDBCTX_VALID(d) ISC_MAGIC_VALID(d, DNS_DYNDBCTX_MAGIC) 50 51 /* 52 * API version 53 * 54 * When the API changes, increment DNS_DYNDB_VERSION. If the 55 * change is backward-compatible (e.g., adding a new function call 56 * but not changing or removing an old one), increment DNS_DYNDB_AGE; 57 * if not, set DNS_DYNDB_AGE to 0. 58 */ 59 #ifndef DNS_DYNDB_VERSION 60 #define DNS_DYNDB_VERSION 2 61 #define DNS_DYNDB_AGE 0 62 #endif /* ifndef DNS_DYNDB_VERSION */ 63 64 typedef isc_result_t 65 dns_dyndb_register_t(isc_mem_t *mctx, const char *name, const char *parameters, 66 const char *file, unsigned long line, 67 const dns_dyndbctx_t *dctx, void **instp); 68 /*% 69 * Called when registering a new driver instance. 'name' must be unique. 70 * 'parameters' contains the driver configuration text. 'dctx' is the 71 * initialization context set up in dns_dyndb_createctx(). 72 * 73 * '*instp' will be set to the driver instance handle if the function 74 * is successful. 75 * 76 * Returns: 77 *\li #ISC_R_SUCCESS 78 *\li #ISC_R_NOMEMORY 79 *\li Other errors are possible 80 */ 81 82 typedef void 83 dns_dyndb_destroy_t(void **instp); 84 /*% 85 * Destroy a driver instance. Dereference any reference-counted 86 * variables passed in 'dctx' and 'inst' in the register function. 87 * 88 * \c *instp must be set to \c NULL by the function before it returns. 89 */ 90 91 typedef int 92 dns_dyndb_version_t(unsigned int *flags); 93 /*% 94 * Return the API version number a dyndb module was compiled with. 95 * 96 * If the returned version number is no greater than than 97 * DNS_DYNDB_VERSION, and no less than DNS_DYNDB_VERSION - DNS_DYNDB_AGE, 98 * then the module is API-compatible with named. 99 * 100 * 'flags' is currently unused and may be NULL, but could be used in 101 * the future to pass back driver capabilities or other information. 102 */ 103 104 isc_result_t 105 dns_dyndb_load(const char *libname, const char *name, const char *parameters, 106 const char *file, unsigned long line, isc_mem_t *mctx, 107 const dns_dyndbctx_t *dctx); 108 /*% 109 * Load a dyndb module. 110 * 111 * This loads a dyndb module using dlopen() or equivalent, calls its register 112 * function (see dns_dyndb_register_t above), and if successful, adds 113 * the instance handle to a list of dyndb instances so it can be cleaned 114 * up later. 115 * 116 * 'file' and 'line' can be used to indicate the name of the file and 117 * the line number from which the parameters were taken, so that logged 118 * error messages, if any, will display the correct locations. 119 * 120 * Returns: 121 *\li #ISC_R_SUCCESS 122 *\li #ISC_R_NOMEMORY 123 *\li Other errors are possible 124 */ 125 126 void 127 dns_dyndb_cleanup(bool exiting); 128 /*% 129 * Shut down and destroy all running dyndb modules. 130 * 131 * 'exiting' indicates whether the server is shutting down, 132 * as opposed to merely being reconfigured. 133 */ 134 135 isc_result_t 136 dns_dyndb_createctx(isc_mem_t *mctx, const void *hashinit, isc_log_t *lctx, 137 dns_view_t *view, dns_zonemgr_t *zmgr, 138 isc_loopmgr_t *loopmgr, dns_dyndbctx_t **dctxp); 139 /*% 140 * Create a dyndb initialization context structure, with 141 * pointers to structures in the server that the dyndb module will 142 * need to access (view, zone manager, memory context, hash initializer, 143 * etc). This structure is expected to last only until all dyndb 144 * modules have been loaded and initialized; after that it will be 145 * destroyed with dns_dyndb_destroyctx(). 146 * 147 * Returns: 148 *\li #ISC_R_SUCCESS 149 *\li #ISC_R_NOMEMORY 150 *\li Other errors are possible 151 */ 152 153 void 154 dns_dyndb_destroyctx(dns_dyndbctx_t **dctxp); 155 /*% 156 * Destroys a dyndb initialization context structure; all 157 * reference-counted members are detached and the structure is freed. 158 */ 159 160 ISC_LANG_ENDDECLS 161