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

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