contrib/bind-9.3/lib/dns/include/dns/diff.h

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