[BACK]Return to diff.h CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / external / mpl / bind / dist / lib / dns / include / dns

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>