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