/*

[0] Fix | Delete

* Copyright (C) Internet Systems Consortium, Inc. ("ISC")

[1] Fix | Delete

*

[2] Fix | Delete

* This Source Code Form is subject to the terms of the Mozilla Public

[3] Fix | Delete

* License, v. 2.0. If a copy of the MPL was not distributed with this

[4] Fix | Delete

* file, you can obtain one at https://mozilla.org/MPL/2.0/.

[5] Fix | Delete

*

[6] Fix | Delete

* See the COPYRIGHT file distributed with this work for additional

[7] Fix | Delete

* information regarding copyright ownership.

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

[11] Fix | Delete

#ifndef DNS_CACHE_H

[12] Fix | Delete

#define DNS_CACHE_H 1

[13] Fix | Delete

[14] Fix | Delete

/*****

[15] Fix | Delete

***** Module Info

[16] Fix | Delete

*****/

[17] Fix | Delete

[18] Fix | Delete

/*! \file dns/cache.h

[19] Fix | Delete

* \brief

[20] Fix | Delete

* Defines dns_cache_t, the cache object.

[21] Fix | Delete

*

[22] Fix | Delete

* Notes:

[23] Fix | Delete

*\li A cache object contains DNS data of a single class.

[24] Fix | Delete

* Multiple classes will be handled by creating multiple

[25] Fix | Delete

* views, each with a different class and its own cache.

[26] Fix | Delete

*

[27] Fix | Delete

* MP:

[28] Fix | Delete

*\li See notes at the individual functions.

[29] Fix | Delete

*

[30] Fix | Delete

* Reliability:

[31] Fix | Delete

*

[32] Fix | Delete

* Resources:

[33] Fix | Delete

*

[34] Fix | Delete

* Security:

[35] Fix | Delete

*

[36] Fix | Delete

* Standards:

[37] Fix | Delete

*/

[38] Fix | Delete

[39] Fix | Delete

/***

[40] Fix | Delete

*** Imports

[41] Fix | Delete

***/

[42] Fix | Delete

[43] Fix | Delete

#include <stdbool.h>

[44] Fix | Delete

[45] Fix | Delete

#include <isc/json.h>

[46] Fix | Delete

#include <isc/lang.h>

[47] Fix | Delete

#include <isc/stats.h>

[48] Fix | Delete

#include <isc/stdtime.h>

[49] Fix | Delete

[50] Fix | Delete

#include <dns/types.h>

[51] Fix | Delete

[52] Fix | Delete

ISC_LANG_BEGINDECLS

[53] Fix | Delete

[54] Fix | Delete

/***

[55] Fix | Delete

*** Functions

[56] Fix | Delete

***/

[57] Fix | Delete

[58] Fix | Delete

isc_result_t

[59] Fix | Delete

dns_cache_create(isc_mem_t *cmctx, isc_taskmgr_t *taskmgr,

[60] Fix | Delete

isc_timermgr_t *timermgr, dns_rdataclass_t rdclass,

[61] Fix | Delete

const char *db_type, unsigned int db_argc, char **db_argv,

[62] Fix | Delete

dns_cache_t **cachep);

[63] Fix | Delete

isc_result_t

[64] Fix | Delete

dns_cache_create2(isc_mem_t *cmctx, isc_taskmgr_t *taskmgr,

[65] Fix | Delete

isc_timermgr_t *timermgr, dns_rdataclass_t rdclass,

[66] Fix | Delete

const char *cachename, const char *db_type,

[67] Fix | Delete

unsigned int db_argc, char **db_argv, dns_cache_t **cachep);

[68] Fix | Delete

isc_result_t

[69] Fix | Delete

dns_cache_create3(isc_mem_t *cmctx, isc_mem_t *hmctx, isc_taskmgr_t *taskmgr,

[70] Fix | Delete

isc_timermgr_t *timermgr, dns_rdataclass_t rdclass,

[71] Fix | Delete

const char *cachename, const char *db_type,

[72] Fix | Delete

unsigned int db_argc, char **db_argv, dns_cache_t **cachep);

[73] Fix | Delete

/*%<

[74] Fix | Delete

* Create a new DNS cache.

[75] Fix | Delete

*

[76] Fix | Delete

* dns_cache_create2() will create a named cache.

[77] Fix | Delete

*

[78] Fix | Delete

* dns_cache_create3() will create a named cache using two separate memory

[79] Fix | Delete

* contexts, one for cache data which can be cleaned and a separate one for

[80] Fix | Delete

* memory allocated for the heap (which can grow without an upper limit and

[81] Fix | Delete

* has no mechanism for shrinking).

[82] Fix | Delete

*

[83] Fix | Delete

* dns_cache_create() is a backward compatible version that internally

[84] Fix | Delete

* specifies an empty cache name and a single memory context.

[85] Fix | Delete

*

[86] Fix | Delete

* Requires:

[87] Fix | Delete

*

[88] Fix | Delete

*\li 'cmctx' (and 'hmctx' if applicable) is a valid memory context.

[89] Fix | Delete

*

[90] Fix | Delete

*\li 'taskmgr' is a valid task manager and 'timermgr' is a valid timer

[91] Fix | Delete

* manager, or both are NULL. If NULL, no periodic cleaning of the

[92] Fix | Delete

* cache will take place.

[93] Fix | Delete

*

[94] Fix | Delete

*\li 'cachename' is a valid string. This must not be NULL.

[95] Fix | Delete

*

[96] Fix | Delete

*\li 'cachep' is a valid pointer, and *cachep == NULL

[97] Fix | Delete

*

[98] Fix | Delete

* Ensures:

[99] Fix | Delete

*

[100] Fix | Delete

*\li '*cachep' is attached to the newly created cache

[101] Fix | Delete

*

[102] Fix | Delete

* Returns:

[103] Fix | Delete

*

[104] Fix | Delete

*\li #ISC_R_SUCCESS

[105] Fix | Delete

*\li #ISC_R_NOMEMORY

[106] Fix | Delete

*/

[107] Fix | Delete

[108] Fix | Delete

void

[109] Fix | Delete

dns_cache_attach(dns_cache_t *cache, dns_cache_t **targetp);

[110] Fix | Delete

/*%<

[111] Fix | Delete

* Attach *targetp to cache.

[112] Fix | Delete

*

[113] Fix | Delete

* Requires:

[114] Fix | Delete

*

[115] Fix | Delete

*\li 'cache' is a valid cache.

[116] Fix | Delete

*

[117] Fix | Delete

*\li 'targetp' points to a NULL dns_cache_t *.

[118] Fix | Delete

*

[119] Fix | Delete

* Ensures:

[120] Fix | Delete

*

[121] Fix | Delete

*\li *targetp is attached to cache.

[122] Fix | Delete

*/

[123] Fix | Delete

[124] Fix | Delete

void

[125] Fix | Delete

dns_cache_detach(dns_cache_t **cachep);

[126] Fix | Delete

/*%<

[127] Fix | Delete

* Detach *cachep from its cache.

[128] Fix | Delete

*

[129] Fix | Delete

* Requires:

[130] Fix | Delete

*

[131] Fix | Delete

*\li 'cachep' points to a valid cache.

[132] Fix | Delete

*

[133] Fix | Delete

* Ensures:

[134] Fix | Delete

*

[135] Fix | Delete

*\li *cachep is NULL.

[136] Fix | Delete

*

[137] Fix | Delete

*\li If '*cachep' is the last reference to the cache,

[138] Fix | Delete

* all resources used by the cache will be freed

[139] Fix | Delete

*/

[140] Fix | Delete

[141] Fix | Delete

void

[142] Fix | Delete

dns_cache_attachdb(dns_cache_t *cache, dns_db_t **dbp);

[143] Fix | Delete

/*%<

[144] Fix | Delete

* Attach *dbp to the cache's database.

[145] Fix | Delete

*

[146] Fix | Delete

* Notes:

[147] Fix | Delete

*

[148] Fix | Delete

*\li This may be used to get a reference to the database for

[149] Fix | Delete

* the purpose of cache lookups (XXX currently it is also

[150] Fix | Delete

* the way to add data to the cache, but having a

[151] Fix | Delete

* separate dns_cache_add() interface instead would allow

[152] Fix | Delete

* more control over memory usage).

[153] Fix | Delete

* The caller should call dns_db_detach() on the reference

[154] Fix | Delete

* when it is no longer needed.

[155] Fix | Delete

*

[156] Fix | Delete

* Requires:

[157] Fix | Delete

*

[158] Fix | Delete

*\li 'cache' is a valid cache.

[159] Fix | Delete

*

[160] Fix | Delete

*\li 'dbp' points to a NULL dns_db *.

[161] Fix | Delete

*

[162] Fix | Delete

* Ensures:

[163] Fix | Delete

*

[164] Fix | Delete

*\li *dbp is attached to the database.

[165] Fix | Delete

*/

[166] Fix | Delete

[167] Fix | Delete

[168] Fix | Delete

isc_result_t

[169] Fix | Delete

dns_cache_setfilename(dns_cache_t *cache, const char *filename);

[170] Fix | Delete

/*%<

[171] Fix | Delete

* If 'filename' is non-NULL, make the cache persistent.

[172] Fix | Delete

* The cache's data will be stored in the given file.

[173] Fix | Delete

* If 'filename' is NULL, make the cache non-persistent.

[174] Fix | Delete

* Files that are no longer used are not unlinked automatically.

[175] Fix | Delete

*

[176] Fix | Delete

* Returns:

[177] Fix | Delete

*\li #ISC_R_SUCCESS

[178] Fix | Delete

*\li #ISC_R_NOMEMORY

[179] Fix | Delete

*\li Various file-related failures

[180] Fix | Delete

*/

[181] Fix | Delete

[182] Fix | Delete

isc_result_t

[183] Fix | Delete

dns_cache_load(dns_cache_t *cache);

[184] Fix | Delete

/*%<

[185] Fix | Delete

* If the cache has a file name, load the cache contents from the file.

[186] Fix | Delete

* Previous cache contents are not discarded.

[187] Fix | Delete

* If no file name has been set, do nothing and return success.

[188] Fix | Delete

*

[189] Fix | Delete

* MT:

[190] Fix | Delete

*\li Multiple simultaneous attempts to load or dump the cache

[191] Fix | Delete

* will be serialized with respect to one another, but

[192] Fix | Delete

* the cache may be read and updated while the dump is

[193] Fix | Delete

* in progress. Updates performed during loading

[194] Fix | Delete

* may or may not be preserved, and reads may return

[195] Fix | Delete

* either the old or the newly loaded data.

[196] Fix | Delete

*

[197] Fix | Delete

* Returns:

[198] Fix | Delete

*

[199] Fix | Delete

*\li #ISC_R_SUCCESS

[200] Fix | Delete

* \li Various failures depending on the database implementation type

[201] Fix | Delete

*/

[202] Fix | Delete

[203] Fix | Delete

isc_result_t

[204] Fix | Delete

dns_cache_dump(dns_cache_t *cache);

[205] Fix | Delete

/*%<

[206] Fix | Delete

* If the cache has a file name, write the cache contents to disk,

[207] Fix | Delete

* overwriting any preexisting file. If no file name has been set,

[208] Fix | Delete

* do nothing and return success.

[209] Fix | Delete

*

[210] Fix | Delete

* MT:

[211] Fix | Delete

*\li Multiple simultaneous attempts to load or dump the cache

[212] Fix | Delete

* will be serialized with respect to one another, but

[213] Fix | Delete

* the cache may be read and updated while the dump is

[214] Fix | Delete

* in progress. Updates performed during the dump may

[215] Fix | Delete

* or may not be reflected in the dumped file.

[216] Fix | Delete

*

[217] Fix | Delete

* Returns:

[218] Fix | Delete

*

[219] Fix | Delete

*\li #ISC_R_SUCCESS

[220] Fix | Delete

* \li Various failures depending on the database implementation type

[221] Fix | Delete

*/

[222] Fix | Delete

[223] Fix | Delete

isc_result_t

[224] Fix | Delete

dns_cache_clean(dns_cache_t *cache, isc_stdtime_t now);

[225] Fix | Delete

/*%<

[226] Fix | Delete

* Force immediate cleaning of the cache, freeing all rdatasets

[227] Fix | Delete

* whose TTL has expired as of 'now' and that have no pending

[228] Fix | Delete

* references.

[229] Fix | Delete

*/

[230] Fix | Delete

[231] Fix | Delete

void

[232] Fix | Delete

dns_cache_setcleaninginterval(dns_cache_t *cache, unsigned int interval);

[233] Fix | Delete

/*%<

[234] Fix | Delete

* Set the periodic cache cleaning interval to 'interval' seconds.

[235] Fix | Delete

*/

[236] Fix | Delete

[237] Fix | Delete

unsigned int

[238] Fix | Delete

dns_cache_getcleaninginterval(dns_cache_t *cache);

[239] Fix | Delete

/*%<

[240] Fix | Delete

* Get the periodic cache cleaning interval to 'interval' seconds.

[241] Fix | Delete

*/

[242] Fix | Delete

[243] Fix | Delete

const char *

[244] Fix | Delete

dns_cache_getname(dns_cache_t *cache);

[245] Fix | Delete

/*%<

[246] Fix | Delete

* Get the cache name.

[247] Fix | Delete

*/

[248] Fix | Delete

[249] Fix | Delete

void

[250] Fix | Delete

dns_cache_setcachesize(dns_cache_t *cache, size_t size);

[251] Fix | Delete

/*%<

[252] Fix | Delete

* Set the maximum cache size. 0 means unlimited.

[253] Fix | Delete

*/

[254] Fix | Delete

[255] Fix | Delete

size_t

[256] Fix | Delete

dns_cache_getcachesize(dns_cache_t *cache);

[257] Fix | Delete

/*%<

[258] Fix | Delete

* Get the maximum cache size.

[259] Fix | Delete

*/

[260] Fix | Delete

[261] Fix | Delete

void

[262] Fix | Delete

dns_cache_setservestalettl(dns_cache_t *cache, dns_ttl_t ttl);

[263] Fix | Delete

/*%<

[264] Fix | Delete

* Sets the maximum length of time that cached answers may be retained

[265] Fix | Delete

* past their normal TTL. Default value for the library is 0, disabling

[266] Fix | Delete

* the use of stale data.

[267] Fix | Delete

*

[268] Fix | Delete

* Requires:

[269] Fix | Delete

*\li 'cache' to be valid.

[270] Fix | Delete

*/

[271] Fix | Delete

[272] Fix | Delete

dns_ttl_t

[273] Fix | Delete

dns_cache_getservestalettl(dns_cache_t *cache);

[274] Fix | Delete

/*%<

[275] Fix | Delete

* Gets the maximum length of time that cached answers may be kept past

[276] Fix | Delete

* normal expiry.

[277] Fix | Delete

*

[278] Fix | Delete

* Requires:

[279] Fix | Delete

*\li 'cache' to be valid.

[280] Fix | Delete

*/

[281] Fix | Delete

[282] Fix | Delete

isc_result_t

[283] Fix | Delete

dns_cache_flush(dns_cache_t *cache);

[284] Fix | Delete

/*%<

[285] Fix | Delete

* Flushes all data from the cache.

[286] Fix | Delete

*

[287] Fix | Delete

* Returns:

[288] Fix | Delete

*\li #ISC_R_SUCCESS

[289] Fix | Delete

*\li #ISC_R_NOMEMORY

[290] Fix | Delete

*/

[291] Fix | Delete

[292] Fix | Delete

isc_result_t

[293] Fix | Delete

dns_cache_flushnode(dns_cache_t *cache, dns_name_t *name,

[294] Fix | Delete

bool tree);

[295] Fix | Delete

/*

[296] Fix | Delete

* Flush a given name from the cache. If 'tree' is true, then

[297] Fix | Delete

* also flush all names under 'name'.

[298] Fix | Delete

*

[299] Fix | Delete

* Requires:

[300] Fix | Delete

*\li 'cache' to be valid.

[301] Fix | Delete

*\li 'name' to be valid.

[302] Fix | Delete

*

[303] Fix | Delete

* Returns:

[304] Fix | Delete

*\li #ISC_R_SUCCESS

[305] Fix | Delete

*\li #ISC_R_NOMEMORY

[306] Fix | Delete

*\li other error returns.

[307] Fix | Delete

*/

[308] Fix | Delete

[309] Fix | Delete

isc_result_t

[310] Fix | Delete

dns_cache_flushname(dns_cache_t *cache, dns_name_t *name);

[311] Fix | Delete

/*

[312] Fix | Delete

* Flush a given name from the cache. Equivalent to

[313] Fix | Delete

* dns_cache_flushpartial(cache, name, false).

[314] Fix | Delete

*

[315] Fix | Delete

* Requires:

[316] Fix | Delete

*\li 'cache' to be valid.

[317] Fix | Delete

*\li 'name' to be valid.

[318] Fix | Delete

*

[319] Fix | Delete

* Returns:

[320] Fix | Delete

*\li #ISC_R_SUCCESS

[321] Fix | Delete

*\li #ISC_R_NOMEMORY

[322] Fix | Delete

*\li other error returns.

[323] Fix | Delete

*/

[324] Fix | Delete

[325] Fix | Delete

isc_stats_t *

[326] Fix | Delete

dns_cache_getstats(dns_cache_t *cache);

[327] Fix | Delete

/*

[328] Fix | Delete

* Return a pointer to the stats collection object for 'cache'

[329] Fix | Delete

*/

[330] Fix | Delete

[331] Fix | Delete

void

[332] Fix | Delete

dns_cache_dumpstats(dns_cache_t *cache, FILE *fp);

[333] Fix | Delete

/*

[334] Fix | Delete

* Dump cache statistics and status in text to 'fp'

[335] Fix | Delete

*/

[336] Fix | Delete

[337] Fix | Delete

void

[338] Fix | Delete

dns_cache_updatestats(dns_cache_t *cache, isc_result_t result);

[339] Fix | Delete

/*

[340] Fix | Delete

* Update cache statistics based on result code in 'result'

[341] Fix | Delete

*/

[342] Fix | Delete

[343] Fix | Delete

#ifdef HAVE_LIBXML2

[344] Fix | Delete

int

[345] Fix | Delete

dns_cache_renderxml(dns_cache_t *cache, xmlTextWriterPtr writer);

[346] Fix | Delete

/*

[347] Fix | Delete

* Render cache statistics and status in XML for 'writer'.

[348] Fix | Delete

*/

[349] Fix | Delete

#endif /* HAVE_LIBXML2 */

[350] Fix | Delete

[351] Fix | Delete

#ifdef HAVE_JSON

[352] Fix | Delete

isc_result_t

[353] Fix | Delete

dns_cache_renderjson(dns_cache_t *cache, json_object *cstats);

[354] Fix | Delete

/*

[355] Fix | Delete

* Render cache statistics and status in JSON

[356] Fix | Delete

*/

[357] Fix | Delete

#endif /* HAVE_JSON */

[358] Fix | Delete

[359] Fix | Delete

ISC_LANG_ENDDECLS

[360] Fix | Delete

[361] Fix | Delete

#endif /* DNS_CACHE_H */

[362] Fix | Delete

[363] Fix | Delete