1/* 2 * Copyright (C) 2004-2007, 2009, 2011, 2012 Internet Systems Consortium, Inc. ("ISC") 3 * Copyright (C) 1999-2001 Internet Software Consortium. 4 * 5 * Permission to use, copy, modify, and/or distribute this software for any 6 * purpose with or without fee is hereby granted, provided that the above 7 * copyright notice and this permission notice appear in all copies. 8 * 9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 * PERFORMANCE OF THIS SOFTWARE. 16 */ 17 18/* $Id$ */ 19 20#ifndef DNS_CACHE_H 21#define DNS_CACHE_H 1 22 23/***** 24 ***** Module Info 25 *****/ 26 27/*! \file dns/cache.h 28 * \brief 29 * Defines dns_cache_t, the cache object. 30 * 31 * Notes: 32 *\li A cache object contains DNS data of a single class. 33 * Multiple classes will be handled by creating multiple 34 * views, each with a different class and its own cache. 35 * 36 * MP: 37 *\li See notes at the individual functions. 38 * 39 * Reliability: 40 * 41 * Resources: 42 * 43 * Security: 44 * 45 * Standards: 46 */ 47 48/*** 49 *** Imports 50 ***/ 51 52#include <isc/lang.h> 53#include <isc/stdtime.h> 54 55#include <dns/types.h> 56 57ISC_LANG_BEGINDECLS 58 59/*** 60 *** Functions 61 ***/ 62 63isc_result_t 64dns_cache_create(isc_mem_t *cmctx, isc_taskmgr_t *taskmgr, 65 isc_timermgr_t *timermgr, dns_rdataclass_t rdclass, 66 const char *db_type, unsigned int db_argc, char **db_argv, 67 dns_cache_t **cachep); 68isc_result_t 69dns_cache_create2(isc_mem_t *cmctx, isc_taskmgr_t *taskmgr, 70 isc_timermgr_t *timermgr, dns_rdataclass_t rdclass, 71 const char *cachename, const char *db_type, 72 unsigned int db_argc, char **db_argv, dns_cache_t **cachep); 73isc_result_t 74dns_cache_create3(isc_mem_t *cmctx, isc_mem_t *hmctx, isc_taskmgr_t *taskmgr, 75 isc_timermgr_t *timermgr, dns_rdataclass_t rdclass, 76 const char *cachename, const char *db_type, 77 unsigned int db_argc, char **db_argv, dns_cache_t **cachep); 78/*%< 79 * Create a new DNS cache. 80 * 81 * dns_cache_create2() will create a named cache. 82 * 83 * dns_cache_create3() will create a named cache using two separate memory 84 * contexts, one for cache data which can be cleaned and a separate one for 85 * memory allocated for the heap (which can grow without an upper limit and 86 * has no mechanism for shrinking). 87 * 88 * dns_cache_create() is a backward compatible version that internally 89 * specifies an empty cache name and a single memory context. 90 * 91 * Requires: 92 * 93 *\li 'cmctx' (and 'hmctx' if applicable) is a valid memory context. 94 * 95 *\li 'taskmgr' is a valid task manager and 'timermgr' is a valid timer 96 * manager, or both are NULL. If NULL, no periodic cleaning of the 97 * cache will take place. 98 * 99 *\li 'cachename' is a valid string. This must not be NULL. 100 * 101 *\li 'cachep' is a valid pointer, and *cachep == NULL 102 * 103 * Ensures: 104 * 105 *\li '*cachep' is attached to the newly created cache 106 * 107 * Returns: 108 * 109 *\li #ISC_R_SUCCESS 110 *\li #ISC_R_NOMEMORY 111 */ 112 113void 114dns_cache_attach(dns_cache_t *cache, dns_cache_t **targetp); 115/*%< 116 * Attach *targetp to cache. 117 * 118 * Requires: 119 * 120 *\li 'cache' is a valid cache. 121 * 122 *\li 'targetp' points to a NULL dns_cache_t *. 123 * 124 * Ensures: 125 * 126 *\li *targetp is attached to cache. 127 */ 128 129void 130dns_cache_detach(dns_cache_t **cachep); 131/*%< 132 * Detach *cachep from its cache. 133 * 134 * Requires: 135 * 136 *\li 'cachep' points to a valid cache. 137 * 138 * Ensures: 139 * 140 *\li *cachep is NULL. 141 * 142 *\li If '*cachep' is the last reference to the cache, 143 * all resources used by the cache will be freed 144 */ 145 146void 147dns_cache_attachdb(dns_cache_t *cache, dns_db_t **dbp); 148/*%< 149 * Attach *dbp to the cache's database. 150 * 151 * Notes: 152 * 153 *\li This may be used to get a reference to the database for 154 * the purpose of cache lookups (XXX currently it is also 155 * the way to add data to the cache, but having a 156 * separate dns_cache_add() interface instead would allow 157 * more control over memory usage). 158 * The caller should call dns_db_detach() on the reference 159 * when it is no longer needed. 160 * 161 * Requires: 162 * 163 *\li 'cache' is a valid cache. 164 * 165 *\li 'dbp' points to a NULL dns_db *. 166 * 167 * Ensures: 168 * 169 *\li *dbp is attached to the database. 170 */ 171 172 173isc_result_t 174dns_cache_setfilename(dns_cache_t *cache, const char *filename); 175/*%< 176 * If 'filename' is non-NULL, make the cache persistent. 177 * The cache's data will be stored in the given file. 178 * If 'filename' is NULL, make the cache non-persistent. 179 * Files that are no longer used are not unlinked automatically. 180 * 181 * Returns: 182 *\li #ISC_R_SUCCESS 183 *\li #ISC_R_NOMEMORY 184 *\li Various file-related failures 185 */ 186 187isc_result_t 188dns_cache_load(dns_cache_t *cache); 189/*%< 190 * If the cache has a file name, load the cache contents from the file. 191 * Previous cache contents are not discarded. 192 * If no file name has been set, do nothing and return success. 193 * 194 * MT: 195 *\li Multiple simultaneous attempts to load or dump the cache 196 * will be serialized with respect to one another, but 197 * the cache may be read and updated while the dump is 198 * in progress. Updates performed during loading 199 * may or may not be preserved, and reads may return 200 * either the old or the newly loaded data. 201 * 202 * Returns: 203 * 204 *\li #ISC_R_SUCCESS 205 * \li Various failures depending on the database implementation type 206 */ 207 208isc_result_t 209dns_cache_dump(dns_cache_t *cache); 210/*%< 211 * If the cache has a file name, write the cache contents to disk, 212 * overwriting any preexisting file. If no file name has been set, 213 * do nothing and return success. 214 * 215 * MT: 216 *\li Multiple simultaneous attempts to load or dump the cache 217 * will be serialized with respect to one another, but 218 * the cache may be read and updated while the dump is 219 * in progress. Updates performed during the dump may 220 * or may not be reflected in the dumped file. 221 * 222 * Returns: 223 * 224 *\li #ISC_R_SUCCESS 225 * \li Various failures depending on the database implementation type 226 */ 227 228isc_result_t 229dns_cache_clean(dns_cache_t *cache, isc_stdtime_t now); 230/*%< 231 * Force immediate cleaning of the cache, freeing all rdatasets 232 * whose TTL has expired as of 'now' and that have no pending 233 * references. 234 */ 235 236void 237dns_cache_setcleaninginterval(dns_cache_t *cache, unsigned int interval); 238/*%< 239 * Set the periodic cache cleaning interval to 'interval' seconds. 240 */ 241 242unsigned int 243dns_cache_getcleaninginterval(dns_cache_t *cache); 244/*%< 245 * Get the periodic cache cleaning interval to 'interval' seconds. 246 */ 247 248isc_uint32_t 249dns_cache_getcachesize(dns_cache_t *cache); 250/*%< 251 * Get the maximum cache size. 252 */ 253 254const char * 255dns_cache_getname(dns_cache_t *cache); 256/*%< 257 * Get the cache name. 258 */ 259 260void 261dns_cache_setcachesize(dns_cache_t *cache, isc_uint32_t size); 262/*%< 263 * Set the maximum cache size. 0 means unlimited. 264 */ 265 266isc_uint32_t 267dns_cache_getcachesize(dns_cache_t *cache); 268/*%< 269 * Get the maximum cache size. 270 */ 271 272isc_result_t 273dns_cache_flush(dns_cache_t *cache); 274/*%< 275 * Flushes all data from the cache. 276 * 277 * Returns: 278 *\li #ISC_R_SUCCESS 279 *\li #ISC_R_NOMEMORY 280 */ 281 282isc_result_t 283dns_cache_flushname(dns_cache_t *cache, dns_name_t *name); 284/* 285 * Flushes a given name from the cache. 286 * 287 * Requires: 288 *\li 'cache' to be valid. 289 *\li 'name' to be valid. 290 * 291 * Returns: 292 *\li #ISC_R_SUCCESS 293 *\li #ISC_R_NOMEMORY 294 *\li other error returns. 295 */ 296 297ISC_LANG_ENDDECLS 298 299#endif /* DNS_CACHE_H */ 300