bind - Removed version tag from contrib directory and updated README.DRAGONFLY.
[dragonfly.git] / contrib / bind / lib / dns / include / dns / cache.h
1 /*
2  * Copyright (C) 2004-2007  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: cache.h,v 1.26 2007/06/19 23:47:16 tbox Exp $ */
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
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 */