contrib/bind/lib/isc/include/isc/symtab.h

   1 /*
   2  * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1996-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: symtab.h,v 1.24.128.2 2009/01/19 23:47:03 tbox Exp $ */
  19
  20 #ifndef ISC_SYMTAB_H
  21 #define ISC_SYMTAB_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file isc/symtab.h
  28  * \brief Provides a simple memory-based symbol table.
  29  *
  30  * Keys are C strings, and key comparisons are case-insensitive.  A type may
  31  * be specified when looking up, defining, or undefining.  A type value of
  32  * 0 means "match any type"; any other value will only match the given
  33  * type.
  34  *
  35  * It's possible that a client will attempt to define a <key, type, value>
  36  * tuple when a tuple with the given key and type already exists in the table.
  37  * What to do in this case is specified by the client.  Possible policies are:
  38  *
  39  *\li   #isc_symexists_reject   Disallow the define, returning #ISC_R_EXISTS
  40  *\li   #isc_symexists_replace  Replace the old value with the new.  The
  41  *                              undefine action (if provided) will be called
  42  *                              with the old <key, type, value> tuple.
  43  *\li   #isc_symexists_add      Add the new tuple, leaving the old tuple in
  44  *                              the table.  Subsequent lookups will retrieve
  45  *                              the most-recently-defined tuple.
  46  *
  47  * A lookup of a key using type 0 will return the most-recently defined
  48  * symbol with that key.  An undefine of a key using type 0 will undefine the
  49  * most-recently defined symbol with that key.  Trying to define a key with
  50  * type 0 is illegal.
  51  *
  52  * The symbol table library does not make a copy the key field, so the
  53  * caller must ensure that any key it passes to isc_symtab_define() will not
  54  * change until it calls isc_symtab_undefine() or isc_symtab_destroy().
  55  *
  56  * A user-specified action will be called (if provided) when a symbol is
  57  * undefined.  It can be used to free memory associated with keys and/or
  58  * values.
  59  *
  60  * \li MP:
  61  *      The callers of this module must ensure any required synchronization.
  62  *
  63  * \li Reliability:
  64  *      No anticipated impact.
  65  *
  66  * \li Resources:
  67  *      TBS
  68  *
  69  * \li Security:
  70  *      No anticipated impact.
  71  *
  72  * \li Standards:
  73  *      None.
  74  */
  75
  76 /***
  77  *** Imports.
  78  ***/
  79
  80 #include <isc/lang.h>
  81 #include <isc/types.h>
  82
  83 /*
  84  *** Symbol Tables.
  85  ***/
  86 /*% Symbol table value. */
  87 typedef union isc_symvalue {
  88         void *                          as_pointer;
  89         const void *                    as_cpointer;
  90         int                             as_integer;
  91         unsigned int                    as_uinteger;
  92 } isc_symvalue_t;
  93
  94 typedef void (*isc_symtabaction_t)(char *key, unsigned int type,
  95                                    isc_symvalue_t value, void *userarg);
  96 /*% Symbol table exists. */
  97 typedef enum {
  98         isc_symexists_reject = 0,       /*%< Disallow the define */
  99         isc_symexists_replace = 1,      /*%< Replace the old value with the new */
 100         isc_symexists_add = 2           /*%< Add the new tuple */
 101 } isc_symexists_t;
 102
 103 ISC_LANG_BEGINDECLS
 104
 105 /*% Create a symbol table. */
 106 isc_result_t
 107 isc_symtab_create(isc_mem_t *mctx, unsigned int size,
 108                   isc_symtabaction_t undefine_action, void *undefine_arg,
 109                   isc_boolean_t case_sensitive, isc_symtab_t **symtabp);
 110
 111 /*% Destroy a symbol table. */
 112 void
 113 isc_symtab_destroy(isc_symtab_t **symtabp);
 114
 115 /*% Lookup a symbol table. */
 116 isc_result_t
 117 isc_symtab_lookup(isc_symtab_t *symtab, const char *key, unsigned int type,
 118                   isc_symvalue_t *value);
 119
 120 /*% Define a symbol table. */
 121 isc_result_t
 122 isc_symtab_define(isc_symtab_t *symtab, const char *key, unsigned int type,
 123                   isc_symvalue_t value, isc_symexists_t exists_policy);
 124
 125 /*% Undefine a symbol table. */
 126 isc_result_t
 127 isc_symtab_undefine(isc_symtab_t *symtab, const char *key, unsigned int type);
 128
 129 ISC_LANG_ENDDECLS
 130
 131 #endif /* ISC_SYMTAB_H */