/* * Copyright (C) Internet Systems Consortium, Inc. ("ISC") * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, you can obtain one at https://mozilla.org/MPL/2.0/. * * See the COPYRIGHT file distributed with this work for additional * information regarding copyright ownership. */ #ifndef DNS_DYNDB_H #define DNS_DYNDB_H #include <stdbool.h> #include <isc/types.h> #include <dns/types.h> ISC_LANG_BEGINDECLS /*! * \brief * Context for initializing a dyndb module. * * This structure passes global server data to which a dyndb * module will need access -- the server memory context, hash * initializer, log context, etc. The structure doesn't persist * beyond configuring the dyndb module. The module's register function * should attach to all reference-counted variables and its destroy * function should detach from them. */ struct dns_dyndbctx { unsigned int magic; const void *hashinit; isc_mem_t *mctx; isc_log_t *lctx; dns_view_t *view; dns_zonemgr_t *zmgr; isc_task_t *task; isc_timermgr_t *timermgr; unsigned int *memdebug; }; #define DNS_DYNDBCTX_MAGIC ISC_MAGIC('D', 'd', 'b', 'c') #define DNS_DYNDBCTX_VALID(d) ISC_MAGIC_VALID(d, DNS_DYNDBCTX_MAGIC) /* * API version * * When the API changes, increment DNS_DYNDB_VERSION. If the * change is backward-compatible (e.g., adding a new function call * but not changing or removing an old one), increment DNS_DYNDB_AGE; * if not, set DNS_DYNDB_AGE to 0. */ #ifndef DNS_DYNDB_VERSION #define DNS_DYNDB_VERSION 1 #define DNS_DYNDB_AGE 0 #endif /* ifndef DNS_DYNDB_VERSION */ typedef isc_result_t dns_dyndb_register_t(isc_mem_t *mctx, const char *name, const char *parameters, const char *file, unsigned long line, const dns_dyndbctx_t *dctx, void **instp); /*% * Called when registering a new driver instance. 'name' must be unique. * 'parameters' contains the driver configuration text. 'dctx' is the * initialization context set up in dns_dyndb_createctx(). * * '*instp' will be set to the driver instance handle if the function * is successful. * * Returns: *\li #ISC_R_SUCCESS *\li #ISC_R_NOMEMORY *\li Other errors are possible */ typedef void dns_dyndb_destroy_t(void **instp); /*% * Destroy a driver instance. Dereference any reference-counted * variables passed in 'dctx' and 'inst' in the register function. * * \c *instp must be set to \c NULL by the function before it returns. */ typedef int dns_dyndb_version_t(unsigned int *flags); /*% * Return the API version number a dyndb module was compiled with. * * If the returned version number is no greater than than * DNS_DYNDB_VERSION, and no less than DNS_DYNDB_VERSION - DNS_DYNDB_AGE, * then the module is API-compatible with named. * * 'flags' is currently unused and may be NULL, but could be used in * the future to pass back driver capabilities or other information. */ isc_result_t dns_dyndb_load(const char *libname, const char *name, const char *parameters, const char *file, unsigned long line, isc_mem_t *mctx, const dns_dyndbctx_t *dctx); /*% * Load a dyndb module. * * This loads a dyndb module using dlopen() or equivalent, calls its register * function (see dns_dyndb_register_t above), and if successful, adds * the instance handle to a list of dyndb instances so it can be cleaned * up later. * * 'file' and 'line' can be used to indicate the name of the file and * the line number from which the parameters were taken, so that logged * error messages, if any, will display the correct locations. * * Returns: *\li #ISC_R_SUCCESS *\li #ISC_R_NOMEMORY *\li Other errors are possible */ void dns_dyndb_cleanup(bool exiting); /*% * Shut down and destroy all running dyndb modules. * * 'exiting' indicates whether the server is shutting down, * as opposed to merely being reconfigured. */ isc_result_t dns_dyndb_createctx(isc_mem_t *mctx, const void *hashinit, isc_log_t *lctx, dns_view_t *view, dns_zonemgr_t *zmgr, isc_task_t *task, isc_timermgr_t *tmgr, dns_dyndbctx_t **dctxp); /*% * Create a dyndb initialization context structure, with * pointers to structures in the server that the dyndb module will * need to access (view, zone manager, memory context, hash initializer, * etc). This structure is expected to last only until all dyndb * modules have been loaded and initialized; after that it will be * destroyed with dns_dyndb_destroyctx(). * * Returns: *\li #ISC_R_SUCCESS *\li #ISC_R_NOMEMORY *\li Other errors are possible */ void dns_dyndb_destroyctx(dns_dyndbctx_t **dctxp); /*% * Destroys a dyndb initialization context structure; all * reference-counted members are detached and the structure is freed. */ ISC_LANG_ENDDECLS #endif /* DNS_DYNDB_H */