contrib/bind9/lib/isccc/include/isccc/symtab.h

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