home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / dns / cache.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  5.9 KB  |  254 lines
  1. /*
  2.  * Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
  3.  * Copyright (C) 1999-2001  Internet Software Consortium.
  4.  *
  5.  * Permission to use, copy, modify, and 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: cache.h,v 1.19.18.3 2005/08/23 02:31:38 marka Exp $ */
  19.  
  20. #ifndef DNS_CACHE_H
  21. #define DNS_CACHE_H 1
  22.  
  23. /*****
  24.  ***** Module Info
  25.  *****/
  26.  
  27. /*! \file
  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.  
  57. ISC_LANG_BEGINDECLS
  58.  
  59. /***
  60.  ***    Functions
  61.  ***/
  62.  
  63. isc_result_t
  64. dns_cache_create(isc_mem_t *mctx, 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);
  68. /*%<
  69.  * Create a new DNS cache.
  70.  *
  71.  * Requires:
  72.  *
  73.  *\li    'mctx' is a valid memory context
  74.  *
  75.  *\li    'taskmgr' is a valid task manager and 'timermgr' is a valid timer
  76.  *     manager, or both are NULL.  If NULL, no periodic cleaning of the
  77.  *     cache will take place.
  78.  *
  79.  *\li    'cachep' is a valid pointer, and *cachep == NULL
  80.  *
  81.  * Ensures:
  82.  *
  83.  *\li    '*cachep' is attached to the newly created cache
  84.  *
  85.  * Returns:
  86.  *
  87.  *\li    #ISC_R_SUCCESS
  88.  *\li    #ISC_R_NOMEMORY
  89.  */
  90.  
  91. void
  92. dns_cache_attach(dns_cache_t *cache, dns_cache_t **targetp);
  93. /*%<
  94.  * Attach *targetp to cache.
  95.  *
  96.  * Requires:
  97.  *
  98.  *\li    'cache' is a valid cache.
  99.  *
  100.  *\li    'targetp' points to a NULL dns_cache_t *.
  101.  *
  102.  * Ensures:
  103.  *
  104.  *\li    *targetp is attached to cache.
  105.  */
  106.  
  107. void
  108. dns_cache_detach(dns_cache_t **cachep);
  109. /*%<
  110.  * Detach *cachep from its cache.
  111.  *
  112.  * Requires:
  113.  *
  114.  *\li    'cachep' points to a valid cache.
  115.  *
  116.  * Ensures:
  117.  *
  118.  *\li    *cachep is NULL.
  119.  *
  120.  *\li    If '*cachep' is the last reference to the cache,
  121.  *        all resources used by the cache will be freed
  122.  */
  123.  
  124. void
  125. dns_cache_attachdb(dns_cache_t *cache, dns_db_t **dbp);
  126. /*%<
  127.  * Attach *dbp to the cache's database.
  128.  *
  129.  * Notes:
  130.  *
  131.  *\li    This may be used to get a reference to the database for
  132.  *    the purpose of cache lookups (XXX currently it is also
  133.  *     the way to add data to the cache, but having a
  134.  *     separate dns_cache_add() interface instead would allow
  135.  *     more control over memory usage).
  136.  *    The caller should call dns_db_detach() on the reference
  137.  *    when it is no longer needed.
  138.  *
  139.  * Requires:
  140.  *
  141.  *\li    'cache' is a valid cache.
  142.  *
  143.  *\li    'dbp' points to a NULL dns_db *.
  144.  *
  145.  * Ensures:
  146.  *
  147.  *\li    *dbp is attached to the database.
  148.  */
  149.  
  150.  
  151. isc_result_t
  152. dns_cache_setfilename(dns_cache_t *cache, const char *filename);
  153. /*%<
  154.  * If 'filename' is non-NULL, make the cache persistent.
  155.  * The cache's data will be stored in the given file.
  156.  * If 'filename' is NULL, make the cache non-persistent.
  157.  * Files that are no longer used are not unlinked automatically.
  158.  *
  159.  * Returns:
  160.  *\li    #ISC_R_SUCCESS
  161.  *\li    #ISC_R_NOMEMORY
  162.  *\li    Various file-related failures
  163.  */
  164.  
  165. isc_result_t
  166. dns_cache_load(dns_cache_t *cache);
  167. /*%<
  168.  * If the cache has a file name, load the cache contents from the file.
  169.  * Previous cache contents are not discarded.
  170.  * If no file name has been set, do nothing and return success.
  171.  *
  172.  * MT:
  173.  *\li    Multiple simultaneous attempts to load or dump the cache
  174.  *     will be serialized with respect to one another, but
  175.  *    the cache may be read and updated while the dump is
  176.  *    in progress.  Updates performed during loading
  177.  *    may or may not be preserved, and reads may return
  178.  *     either the old or the newly loaded data.
  179.  *
  180.  * Returns:
  181.  *
  182.  *\li    #ISC_R_SUCCESS
  183.  *  \li    Various failures depending on the database implementation type
  184.  */
  185.  
  186. isc_result_t
  187. dns_cache_dump(dns_cache_t *cache);
  188. /*%<
  189.  * If the cache has a file name, write the cache contents to disk,
  190.  * overwriting any preexisting file.  If no file name has been set,
  191.  * do nothing and return success.
  192.  *
  193.  * MT:
  194.  *\li    Multiple simultaneous attempts to load or dump the cache
  195.  *     will be serialized with respect to one another, but
  196.  *    the cache may be read and updated while the dump is
  197.  *    in progress.  Updates performed during the dump may
  198.  *     or may not be reflected in the dumped file.
  199.  *
  200.  * Returns:
  201.  *
  202.  *\li    #ISC_R_SUCCESS
  203.  *  \li    Various failures depending on the database implementation type
  204.  */
  205.  
  206. isc_result_t
  207. dns_cache_clean(dns_cache_t *cache, isc_stdtime_t now);
  208. /*%<
  209.  * Force immediate cleaning of the cache, freeing all rdatasets
  210.  * whose TTL has expired as of 'now' and that have no pending
  211.  * references.
  212.  */
  213.  
  214. void
  215. dns_cache_setcleaninginterval(dns_cache_t *cache, unsigned int interval);
  216. /*%<
  217.  * Set the periodic cache cleaning interval to 'interval' seconds.
  218.  */
  219.  
  220. void
  221. dns_cache_setcachesize(dns_cache_t *cache, isc_uint32_t size);
  222. /*%<
  223.  * Set the maximum cache size.  0 means unlimited.
  224.  */
  225.  
  226. isc_result_t
  227. dns_cache_flush(dns_cache_t *cache);
  228. /*%<
  229.  * Flushes all data from the cache.
  230.  *
  231.  * Returns:
  232.  *\li    #ISC_R_SUCCESS
  233.  *\li    #ISC_R_NOMEMORY
  234.  */
  235.  
  236. isc_result_t
  237. dns_cache_flushname(dns_cache_t *cache, dns_name_t *name);
  238. /*
  239.  * Flushes a given name from the cache.
  240.  *
  241.  * Requires:
  242.  *\li    'cache' to be valid.
  243.  *\li    'name' to be valid.
  244.  *
  245.  * Returns:
  246.  *\li    #ISC_R_SUCCESS
  247.  *\li    #ISC_R_NOMEMORY
  248.  *\li    other error returns.
  249.  */
  250.  
  251. ISC_LANG_ENDDECLS
  252.  
  253. #endif /* DNS_CACHE_H */
  254.