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