1 /* $NetBSD: diff.h,v 1.5 2014/12/10 04:37:58 christos Exp $ */ 2 3 /* 4 * Copyright (C) 2004-2010, 2013 Internet Systems Consortium, Inc. ("ISC") 5 * Copyright (C) 2000, 2001 Internet Software Consortium. 6 * 7 * Permission to use, copy, modify, and/or distribute this software for any 8 * purpose with or without fee is hereby granted, provided that the above 9 * copyright notice and this permission notice appear in all copies. 10 * 11 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 12 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 13 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 14 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 15 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 16 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 17 * PERFORMANCE OF THIS SOFTWARE. 18 */ 19 20 /* Id: diff.h,v 1.19 2010/06/04 23:51:14 tbox Exp */ 21 22 #ifndef DNS_DIFF_H 23 #define DNS_DIFF_H 1 24 25 /***** 26 ***** Module Info 27 *****/ 28 29 /*! \file dns/diff.h 30 * \brief 31 * A diff is a convenience type representing a list of changes to be 32 * made to a database. 33 */ 34 35 /*** 36 *** Imports 37 ***/ 38 39 #include <isc/lang.h> 40 #include <isc/magic.h> 41 42 #include <dns/name.h> 43 #include <dns/rdata.h> 44 #include <dns/types.h> 45 46 /*** 47 *** Types 48 ***/ 49 50 /*% 51 * A dns_difftuple_t represents a single RR being added or deleted. 52 * The RR type and class are in the 'rdata' member; the class is always 53 * the real one, not a DynDNS meta-class, so that the rdatas can be 54 * compared using dns_rdata_compare(). The TTL is significant 55 * even for deletions, because a deletion/addition pair cannot 56 * be canceled out if the TTL differs (it might be an explicit 57 * TTL update). 58 * 59 * Tuples are also used to represent complete RRs with owner 60 * names for a couple of other purposes, such as the 61 * individual RRs of a "RRset exists (value dependent)" 62 * prerequisite set. In this case, op==DNS_DIFFOP_EXISTS, 63 * and the TTL is ignored. 64 * 65 * DNS_DIFFOP_*RESIGN will cause the 'resign' attribute of the resulting 66 * RRset to be recomputed to be 'resign' seconds before the earliest RRSIG 67 * timeexpire. 68 */ 69 70 typedef enum { 71 DNS_DIFFOP_ADD = 0, /*%< Add an RR. */ 72 DNS_DIFFOP_DEL = 1, /*%< Delete an RR. */ 73 DNS_DIFFOP_EXISTS = 2, /*%< Assert RR existence. */ 74 DNS_DIFFOP_ADDRESIGN = 4, /*%< ADD + RESIGN. */ 75 DNS_DIFFOP_DELRESIGN = 5 /*%< DEL + RESIGN. */ 76 } dns_diffop_t; 77 78 typedef struct dns_difftuple dns_difftuple_t; 79 80 #define DNS_DIFFTUPLE_MAGIC ISC_MAGIC('D','I','F','T') 81 #define DNS_DIFFTUPLE_VALID(t) ISC_MAGIC_VALID(t, DNS_DIFFTUPLE_MAGIC) 82 83 struct dns_difftuple { 84 unsigned int magic; 85 isc_mem_t *mctx; 86 dns_diffop_t op; 87 dns_name_t name; 88 dns_ttl_t ttl; 89 dns_rdata_t rdata; 90 ISC_LINK(dns_difftuple_t) link; 91 /* Variable-size name data and rdata follows. */ 92 }; 93 94 /*% 95 * A dns_diff_t represents a set of changes being applied to 96 * a zone. Diffs are also used to represent "RRset exists 97 * (value dependent)" prerequisites. 98 */ 99 typedef struct dns_diff dns_diff_t; 100 101 #define DNS_DIFF_MAGIC ISC_MAGIC('D','I','F','F') 102 #define DNS_DIFF_VALID(t) ISC_MAGIC_VALID(t, DNS_DIFF_MAGIC) 103 104 struct dns_diff { 105 unsigned int magic; 106 isc_mem_t * mctx; 107 ISC_LIST(dns_difftuple_t) tuples; 108 }; 109 110 /* Type of comparison function for sorting diffs. */ 111 typedef int dns_diff_compare_func(const void *, const void *); 112 113 /*** 114 *** Functions 115 ***/ 116 117 ISC_LANG_BEGINDECLS 118 119 /**************************************************************************/ 120 /* 121 * Manipulation of diffs and tuples. 122 */ 123 124 isc_result_t 125 dns_difftuple_create(isc_mem_t *mctx, 126 dns_diffop_t op, dns_name_t *name, dns_ttl_t ttl, 127 dns_rdata_t *rdata, dns_difftuple_t **tp); 128 /*%< 129 * Create a tuple. Deep copies are made of the name and rdata, so 130 * they need not remain valid after the call. 131 * 132 * Requires: 133 *\li *tp != NULL && *tp == NULL. 134 * 135 * Returns: 136 *\li ISC_R_SUCCESS 137 * \li ISC_R_NOMEMORY 138 */ 139 140 void 141 dns_difftuple_free(dns_difftuple_t **tp); 142 /*%< 143 * Free a tuple. 144 * 145 * Requires: 146 * \li **tp is a valid tuple. 147 * 148 * Ensures: 149 * \li *tp == NULL 150 * \li All memory used by the tuple is freed. 151 */ 152 153 isc_result_t 154 dns_difftuple_copy(dns_difftuple_t *orig, dns_difftuple_t **copyp); 155 /*%< 156 * Copy a tuple. 157 * 158 * Requires: 159 * \li 'orig' points to a valid tuple 160 *\li copyp != NULL && *copyp == NULL 161 */ 162 163 void 164 dns_diff_init(isc_mem_t *mctx, dns_diff_t *diff); 165 /*%< 166 * Initialize a diff. 167 * 168 * Requires: 169 * \li 'diff' points to an uninitialized dns_diff_t 170 * \li allocated by the caller. 171 * 172 * Ensures: 173 * \li '*diff' is a valid, empty diff. 174 */ 175 176 void 177 dns_diff_clear(dns_diff_t *diff); 178 /*%< 179 * Clear a diff, destroying all its tuples. 180 * 181 * Requires: 182 * \li 'diff' points to a valid dns_diff_t. 183 * 184 * Ensures: 185 * \li Any tuples in the diff are destroyed. 186 * The diff now empty, but it is still valid 187 * and may be reused without calling dns_diff_init 188 * again. The only memory used is that of the 189 * dns_diff_t structure itself. 190 * 191 * Notes: 192 * \li Managing the memory of the dns_diff_t structure itself 193 * is the caller's responsibility. 194 */ 195 196 void 197 dns_diff_append(dns_diff_t *diff, dns_difftuple_t **tuple); 198 /*%< 199 * Append a single tuple to a diff. 200 * 201 *\li 'diff' is a valid diff. 202 * \li '*tuple' is a valid tuple. 203 * 204 * Ensures: 205 *\li *tuple is NULL. 206 *\li The tuple has been freed, or will be freed when the diff is cleared. 207 */ 208 209 void 210 dns_diff_appendminimal(dns_diff_t *diff, dns_difftuple_t **tuple); 211 /*%< 212 * Append 'tuple' to 'diff', removing any duplicate 213 * or conflicting updates as needed to create a minimal diff. 214 * 215 * Requires: 216 *\li 'diff' is a minimal diff. 217 * 218 * Ensures: 219 *\li 'diff' is still a minimal diff. 220 * \li *tuple is NULL. 221 * \li The tuple has been freed, or will be freed when the diff is cleared. 222 * 223 */ 224 225 isc_result_t 226 dns_diff_sort(dns_diff_t *diff, dns_diff_compare_func *compare); 227 /*%< 228 * Sort 'diff' in-place according to the comparison function 'compare'. 229 */ 230 231 isc_result_t 232 dns_diff_apply(dns_diff_t *diff, dns_db_t *db, dns_dbversion_t *ver); 233 isc_result_t 234 dns_diff_applysilently(dns_diff_t *diff, dns_db_t *db, dns_dbversion_t *ver); 235 /*%< 236 * Apply 'diff' to the database 'db'. 237 * 238 * dns_diff_apply() logs warnings about updates with no effect or 239 * with inconsistent TTLs; dns_diff_applysilently() does not. 240 * 241 * For efficiency, the diff should be sorted by owner name. 242 * If it is not sorted, operation will still be correct, 243 * but less efficient. 244 * 245 * Requires: 246 *\li *diff is a valid diff (possibly empty), containing 247 * tuples of type #DNS_DIFFOP_ADD and/or 248 * For #DNS_DIFFOP_DEL tuples, the TTL is ignored. 249 * 250 */ 251 252 isc_result_t 253 dns_diff_load(dns_diff_t *diff, dns_addrdatasetfunc_t addfunc, 254 void *add_private); 255 /*%< 256 * Like dns_diff_apply, but for use when loading a new database 257 * instead of modifying an existing one. This bypasses the 258 * database transaction mechanisms. 259 * 260 * Requires: 261 *\li 'addfunc' is a valid dns_addradatasetfunc_t obtained from 262 * dns_db_beginload() 263 * 264 *\li 'add_private' points to a corresponding dns_dbload_t * 265 * (XXX why is it a void pointer, then?) 266 */ 267 268 isc_result_t 269 dns_diff_print(dns_diff_t *diff, FILE *file); 270 271 /*%< 272 * Print the differences to 'file' or if 'file' is NULL via the 273 * logging system. 274 * 275 * Require: 276 *\li 'diff' to be valid. 277 *\li 'file' to refer to a open file or NULL. 278 * 279 * Returns: 280 *\li #ISC_R_SUCCESS 281 *\li #ISC_R_NOMEMORY 282 *\li #ISC_R_UNEXPECTED 283 *\li any error from dns_rdataset_totext() 284 */ 285 286 ISC_LANG_ENDDECLS 287 288 #endif /* DNS_DIFF_H */ 289