1 /* 2 * Copyright (C) 2004-2009 Christos Tsantilas 3 * 4 * This program is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2.1 of the License, or (at your option) any later version. 8 * 9 * This program is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this library; if not, write to the Free Software 16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 17 * MA 02110-1301 USA. 18 */ 19 20 #ifndef __LOOKUP_TABLE_H 21 #define __LOOKUP_TABLE_H 22 23 #include "c-icap.h" 24 #include "mem.h" 25 #include "types_ops.h" 26 #include "array.h" 27 28 #ifdef __cplusplus 29 extern "C" 30 { 31 #endif 32 33 /** 34 \defgroup LOOKUPTABLE Lookup tables api 35 \ingroup API 36 \brief Macros, functions and structures used to implement and use lookup tables 37 * 38 * Lookup tables can considered as simple read only databases where the user 39 * can search a set of values using a key 40 */ 41 42 43 struct ci_lookup_table; 44 struct ci_lookup_table_type { 45 void *(*open)(struct ci_lookup_table *table); 46 void (*close)(struct ci_lookup_table *table); 47 void *(*search)(struct ci_lookup_table *table, void *key, void ***vals); 48 void (*release_result)(struct ci_lookup_table *table_data, void **val); 49 const void * (*get_row)(struct ci_lookup_table *table, const void *key, const char *columns[], void ***vals); 50 char *type; 51 }; 52 53 /** 54 * \brief The lookup table struct 55 * \ingroup LOOKUPTABLE 56 */ 57 struct ci_lookup_table { 58 void *(*open)(struct ci_lookup_table *table); 59 void (*close)(struct ci_lookup_table *table); 60 void *(*search)(struct ci_lookup_table *table, void *key, void ***vals); 61 void (*release_result)(struct ci_lookup_table *table, void **val); 62 const void * (*get_row)(struct ci_lookup_table *table, const void *key, const char *columns[], void ***vals); 63 char *type; 64 char *path; 65 char *args; 66 int cols; 67 ci_str_vector_t *col_names; 68 const ci_type_ops_t *key_ops; 69 const ci_type_ops_t *val_ops; 70 ci_mem_allocator_t *allocator; 71 const struct ci_lookup_table_type *_lt_type; 72 void *data; 73 }; 74 75 CI_DECLARE_FUNC(struct ci_lookup_table_type *) ci_lookup_table_type_register(struct ci_lookup_table_type *lt_type); 76 CI_DECLARE_FUNC(void) ci_lookup_table_type_unregister(struct ci_lookup_table_type *lt_type); 77 CI_DECLARE_FUNC(const struct ci_lookup_table_type *) ci_lookup_table_type_search(const char *type); 78 79 /** 80 * \brief Create a lookup table 81 * \ingroup LOOKUPTABLE 82 * 83 \param table The path of the lookup table (eg file:/etc/c-icap/users.txt or 84 * ldap://hostname/o=base?cn,uid?uid=chtsanti) 85 \return A pointer to a lookup table object 86 */ 87 CI_DECLARE_FUNC(struct ci_lookup_table *) ci_lookup_table_create(const char *table); 88 89 /** 90 * \brief Destroy a lookup table. 91 * \ingroup LOOKUPTABLE 92 * 93 \param lt Pointer to the lookup table will be destroyed. 94 */ 95 CI_DECLARE_FUNC(void) ci_lookup_table_destroy(struct ci_lookup_table *lt); 96 97 /** 98 * \brief Initializes the lookup table. 99 * 100 * \param table The lookup table object 101 */ 102 CI_DECLARE_FUNC(void *) ci_lookup_table_open(struct ci_lookup_table *table); 103 104 105 /** 106 * \brief Search for an object in the lookup table which matches a key. 107 * 108 * \param table The lookup table object 109 * \param key The key value to search for 110 * \param vals In this variable stored a 2d array which contains the return 111 * values 112 * \return NULL if none object matches, pointer to the object key value. 113 */ 114 CI_DECLARE_FUNC(const char *) ci_lookup_table_search(struct ci_lookup_table *table, const char *key, char ***vals); 115 116 /** 117 * \brief Releases the data values returned from the search method. 118 * 119 * \param table The lookup table object 120 * \param val The 2d array returned from the search method 121 */ 122 CI_DECLARE_FUNC(void) ci_lookup_table_release_result(struct ci_lookup_table *table, void **val); 123 124 /** 125 * \brief Search for an object in the lookup table which supports named columns. 126 * 127 * \param table The lookup table object 128 * \param key The key value to search for 129 * \param columns NULL terminated array with the names of the columns to 130 * retrieve. 131 * \param vals In this variable stored a 2d array which contains the 132 * requested row 133 * \return NULL if none object matches, pointer to the object key value. 134 */ 135 136 CI_DECLARE_FUNC(const char *) ci_lookup_table_get_row(struct ci_lookup_table *table, const char *key, const char *columns[], char ***vals); 137 138 #ifdef __cplusplus 139 } 140 #endif 141 142 #endif 143