cache.h revision dd2a0a6d2dec1c23787351e51b434a838dec5603
5cd4555ad444fd391002ae32450572054369fd42Rob Austein * Copyright (C) 2004-2007, 2009, 2011 Internet Systems Consortium, Inc. ("ISC")
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * Copyright (C) 1999-2001 Internet Software Consortium.
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrews * Permission to use, copy, modify, and/or distribute this software for any
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews * purpose with or without fee is hereby granted, provided that the above
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington * copyright notice and this permission notice appear in all copies.
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews * PERFORMANCE OF THIS SOFTWARE.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews/* $Id: cache.h,v 1.32 2011/08/02 23:47:52 tbox Exp $ */
c40265eba0c99708887d68e67901924065ba2514Brian Wellington ***** Module Info
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * Defines dns_cache_t, the cache object.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington *\li A cache object contains DNS data of a single class.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * Multiple classes will be handled by creating multiple
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * views, each with a different class and its own cache.
c1a883f2e04d94e99c433b1f6cfd0c0338f4ed85Mark Andrews *\li See notes at the individual functions.
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrews * Reliability:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * Resources:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * Standards:
c40265eba0c99708887d68e67901924065ba2514Brian Wellington *** Functions
92551304a9abff9284de5b79a48e83d781989339Mark Andrewsdns_cache_create(isc_mem_t *cmctx, isc_taskmgr_t *taskmgr,
c40265eba0c99708887d68e67901924065ba2514Brian Wellington isc_timermgr_t *timermgr, dns_rdataclass_t rdclass,
c40265eba0c99708887d68e67901924065ba2514Brian Wellington const char *db_type, unsigned int db_argc, char **db_argv,
c40265eba0c99708887d68e67901924065ba2514Brian Wellingtondns_cache_create2(isc_mem_t *cmctx, isc_taskmgr_t *taskmgr,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein isc_timermgr_t *timermgr, dns_rdataclass_t rdclass,
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt unsigned int db_argc, char **db_argv, dns_cache_t **cachep);
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Huntdns_cache_create3(isc_mem_t *cmctx, isc_mem_t *hmctx, isc_taskmgr_t *taskmgr,
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt isc_timermgr_t *timermgr, dns_rdataclass_t rdclass,
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt unsigned int db_argc, char **db_argv, dns_cache_t **cachep);
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt * Create a new DNS cache.
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt * dns_cache_create2() will create a named cache.
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt * dns_cache_create3() will create a named cache using two separate memory
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt * contexts, one for cache data which can be cleaned and a separate one for
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt * memory allocated for the heap (which can grow without an upper limit and
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * has no mechanism for shrinking).
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * dns_cache_create() is a backward compatible version that internally
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * specifies an empty cache name and a single memory context.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington *\li 'cmctx' (and 'hmctx' if applicable) is a valid memory context.
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews *\li 'taskmgr' is a valid task manager and 'timermgr' is a valid timer
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews * manager, or both are NULL. If NULL, no periodic cleaning of the
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews * cache will take place.
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews *\li 'cachename' is a valid string. This must not be NULL.
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews *\li 'cachep' is a valid pointer, and *cachep == NULL
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein *\li '*cachep' is attached to the newly created cache
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein *\li #ISC_R_SUCCESS
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein *\li #ISC_R_NOMEMORY
a26ad011f382d12058478704cb5e90e6f4366d01Andreas Gustafssondns_cache_attach(dns_cache_t *cache, dns_cache_t **targetp);
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * Attach *targetp to cache.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein *\li 'cache' is a valid cache.
a26ad011f382d12058478704cb5e90e6f4366d01Andreas Gustafsson *\li 'targetp' points to a NULL dns_cache_t *.
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews *\li *targetp is attached to cache.
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews * Detach *cachep from its cache.
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews *\li 'cachep' points to a valid cache.
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews *\li *cachep is NULL.
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews *\li If '*cachep' is the last reference to the cache,
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews * all resources used by the cache will be freed
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrewsdns_cache_attachdb(dns_cache_t *cache, dns_db_t **dbp);
92551304a9abff9284de5b79a48e83d781989339Mark Andrews * Attach *dbp to the cache's database.
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark Andrews *\li This may be used to get a reference to the database for
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * the purpose of cache lookups (XXX currently it is also
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * the way to add data to the cache, but having a
92551304a9abff9284de5b79a48e83d781989339Mark Andrews * separate dns_cache_add() interface instead would allow
92551304a9abff9284de5b79a48e83d781989339Mark Andrews * more control over memory usage).
7791dd06ea69d0fb2494788ad4c24d568f40bcdfMark Andrews * The caller should call dns_db_detach() on the reference
e9359db5e958bf05f9b9c5fe3c27d533f0f05550Mark Andrews * when it is no longer needed.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein *\li 'cache' is a valid cache.
7791dd06ea69d0fb2494788ad4c24d568f40bcdfMark Andrews *\li 'dbp' points to a NULL dns_db *.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein *\li *dbp is attached to the database.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeindns_cache_setfilename(dns_cache_t *cache, const char *filename);
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * If 'filename' is non-NULL, make the cache persistent.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * The cache's data will be stored in the given file.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * If 'filename' is NULL, make the cache non-persistent.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * Files that are no longer used are not unlinked automatically.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington *\li #ISC_R_SUCCESS
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein *\li #ISC_R_NOMEMORY
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein *\li Various file-related failures
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * If the cache has a file name, load the cache contents from the file.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * Previous cache contents are not discarded.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein * If no file name has been set, do nothing and return success.
6043e41fcf5dc91aa8a981c966512d73bdec31c1Mark Andrews *\li Multiple simultaneous attempts to load or dump the cache
6043e41fcf5dc91aa8a981c966512d73bdec31c1Mark Andrews * will be serialized with respect to one another, but
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * the cache may be read and updated while the dump is
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * in progress. Updates performed during loading
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * may or may not be preserved, and reads may return
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * either the old or the newly loaded data.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington *\li #ISC_R_SUCCESS
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * \li Various failures depending on the database implementation type
c40265eba0c99708887d68e67901924065ba2514Brian Wellington * If the cache has a file name, write the cache contents to disk,
#ifdef HAVE_LIBXML2