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