home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / dns / diff.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  7.1 KB  |  281 lines
  1. /*
  2.  * Copyright (C) 2004, 2005  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.6.18.2 2005/04/29 00:16:12 marka Exp $ */
  19.  
  20. #ifndef DNS_DIFF_H
  21. #define DNS_DIFF_H 1
  22.  
  23. /*****
  24.  ***** Module Info
  25.  *****/
  26.  
  27. /*! \file
  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 comparision 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.  * Maniuplation 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 */
  281.