contrib/bind-9.5.2/lib/isccc/include/isccc/symtab.h

   1 /*
   2  * Portions Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
   3  * Portions Copyright (C) 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 AND NOMINUM DISCLAIMS ALL
  10  * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
  11  * OF MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY
  12  * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16  *
  17  * Portions Copyright (C) 2001  Nominum, Inc.
  18  *
  19  * Permission to use, copy, modify, and/or distribute this software for any
  20  * purpose with or without fee is hereby granted, provided that the above
  21  * copyright notice and this permission notice appear in all copies.
  22  *
  23  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC AND NOMINUM DISCLAIMS ALL
  24  * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
  25  * OF MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY
  26  * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  27  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  28  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  29  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  30  */
  31
  32 /* $Id: symtab.h,v 1.10 2007/08/28 07:20:43 tbox Exp $ */
  33
  34 #ifndef ISCCC_SYMTAB_H
  35 #define ISCCC_SYMTAB_H 1
  36
  37 /*****
  38  ***** Module Info
  39  *****/
  40
  41 /*! \file isccc/symtab.h
  42  * \brief
  43  * Provides a simple memory-based symbol table.
  44  *
  45  * Keys are C strings.  A type may be specified when looking up,
  46  * defining, or undefining.  A type value of 0 means "match any type";
  47  * any other value will only match the given type.
  48  *
  49  * It's possible that a client will attempt to define a <key, type,
  50  * value> tuple when a tuple with the given key and type already
  51  * exists in the table.  What to do in this case is specified by the
  52  * client.  Possible policies are:
  53  *
  54  *\li   isccc_symexists_reject  Disallow the define, returning #ISC_R_EXISTS
  55  *\li   isccc_symexists_replace Replace the old value with the new.  The
  56  *                              undefine action (if provided) will be called
  57  *                              with the old <key, type, value> tuple.
  58  *\li   isccc_symexists_add     Add the new tuple, leaving the old tuple in
  59  *                              the table.  Subsequent lookups will retrieve
  60  *                              the most-recently-defined tuple.
  61  *
  62  * A lookup of a key using type 0 will return the most-recently
  63  * defined symbol with that key.  An undefine of a key using type 0
  64  * will undefine the most-recently defined symbol with that key.
  65  * Trying to define a key with type 0 is illegal.
  66  *
  67  * The symbol table library does not make a copy the key field, so the
  68  * caller must ensure that any key it passes to isccc_symtab_define()
  69  * will not change until it calls isccc_symtab_undefine() or
  70  * isccc_symtab_destroy().
  71  *
  72  * A user-specified action will be called (if provided) when a symbol
  73  * is undefined.  It can be used to free memory associated with keys
  74  * and/or values.
  75  */
  76
  77 /***
  78  *** Imports.
  79  ***/
  80
  81 #include <isc/lang.h>
  82 #include <isccc/types.h>
  83
  84 /***
  85  *** Symbol Tables.
  86  ***/
  87
  88 typedef union isccc_symvalue {
  89         void *                          as_pointer;
  90         int                             as_integer;
  91         unsigned int                    as_uinteger;
  92 } isccc_symvalue_t;
  93
  94 typedef void (*isccc_symtabundefaction_t)(char *key, unsigned int type,
  95                                         isccc_symvalue_t value, void *userarg);
  96
  97 typedef isc_boolean_t (*isccc_symtabforeachaction_t)(char *key,
  98                                                    unsigned int type,
  99                                                    isccc_symvalue_t value,
 100                                                    void *userarg);
 101
 102 typedef enum {
 103         isccc_symexists_reject = 0,
 104         isccc_symexists_replace = 1,
 105         isccc_symexists_add = 2
 106 } isccc_symexists_t;
 107
 108 ISC_LANG_BEGINDECLS
 109
 110 isc_result_t
 111 isccc_symtab_create(unsigned int size,
 112                   isccc_symtabundefaction_t undefine_action, void *undefine_arg,
 113                   isc_boolean_t case_sensitive, isccc_symtab_t **symtabp);
 114
 115 void
 116 isccc_symtab_destroy(isccc_symtab_t **symtabp);
 117
 118 isc_result_t
 119 isccc_symtab_lookup(isccc_symtab_t *symtab, const char *key, unsigned int type,
 120                   isccc_symvalue_t *value);
 121
 122 isc_result_t
 123 isccc_symtab_define(isccc_symtab_t *symtab, char *key, unsigned int type,
 124                   isccc_symvalue_t value, isccc_symexists_t exists_policy);
 125
 126 isc_result_t
 127 isccc_symtab_undefine(isccc_symtab_t *symtab, const char *key, unsigned int type);
 128
 129 void
 130 isccc_symtab_foreach(isccc_symtab_t *symtab, isccc_symtabforeachaction_t action,
 131                    void *arg);
 132
 133 ISC_LANG_ENDDECLS
 134
 135 #endif /* ISCCC_SYMTAB_H */