1 /* spmfilter - mail filtering framework 2 * Copyright (C) 2009-2012 Axel Steiner and SpaceNet AG 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 3 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 program. If not, see <http://www.gnu.org/licenses/>. 16 * 17 * Original implementation by N.Devillard 18 */ 19 20 /*! 21 * @file smf_dict.h 22 * @brief Defines the SMFDict_T data type and functions for a dictionary. 23 * @details A SMFDict_T provides associations between keys and values so that given a key, the associated 24 * value can be found very quickly. Please note that the keys and values are copied when inserted 25 * into the dictionary and will be freed with smf_dict_free() 26 * 27 * @details To create a new SMFDict_T, use smf_dict_new() 28 * @details To insert a key and value into a SMFDict_T, use smf_dict_set() 29 * @details To lookup a value corresponding to a given key, use smf_dict_get() 30 * @details To remove a key and value, use smf_dict_remove() 31 * @details To call a function for each key and value pair use smf_dict_map() 32 * @details To destroy a SMFDict_T use smf_dict_free() 33 */ 34 35 #ifndef _SMF_DICT_H 36 #define _SMF_DICT_H 37 38 #include "smf_list.h" 39 40 /*! 41 * @struct SMFDict_T smf_dict.h 42 * @brief Dictionary data type 43 */ 44 typedef struct { 45 int n; /**< number of entries in dictionary */ 46 int size; /**< storage size */ 47 char **val; /**< list of values */ 48 char **key; /**< list of string keys */ 49 unsigned *hash; /**< list of hash values for keys */ 50 } SMFDict_T; 51 52 /*! 53 * @fn SMFDict_T *smf_dict_new(void); 54 * @brief Create a new SMFDict_T. 55 * @return a newly allocated SMFDict_T. 56 */ 57 SMFDict_T *smf_dict_new(void); 58 59 /*! 60 * @fn void smf_dict_free(SMFDict_T *dict) 61 * @brief Frees a SMFDict_T with all keys and values 62 * @param dict SMFDict_T to deallocate. 63 */ 64 void smf_dict_free(SMFDict_T *dict); 65 66 /*! 67 * @fn int smf_dict_set(SMFDict_T *dict, const char *key, const char *val) 68 * @brief Inserts a key and value into a SMFDict_T 69 * @details If the given key is found in the dictionary, the associated value is 70 * replaced by the provided one. If the key cannot be found in the 71 * dictionary, it will be added to it. 72 * @param dict a SMFDict_T object to modify. 73 * @param key key to modify or add. 74 * @param val Value to add. 75 * @return 0 on success or -1 in case of error 76 */ 77 int smf_dict_set(SMFDict_T *dict, const char * key, const char * val); 78 79 /*! 80 * @fn char *smf_dict_get(SMFDict_T *dict, const char * key) 81 * @brief Looks up a key in a SMFDict_T and get the associated value 82 * @param dict a SMFDict_T object 83 * @param key key to look for in the dictionary. 84 * @return the associated value, or NULL if the key is not found 85 */ 86 char *smf_dict_get(SMFDict_T *dict, const char * key); 87 88 /*! 89 * @fn unsigned long smf_dict_get_ulong(SMFDict_T *dict, const char * key, int *success) 90 * @brief Looks up a key in a SMFDict_T and get the associated unsigned long value 91 * (if possible). 92 * The function tries to convert to value behind the key into a unsigned long value, 93 * returns it and sets the success-pointer to 1. If the key does not exists or if the 94 * convertion is not possible, then (unsigned long)-1 is returned and the success-pointer 95 * is set to 0. 96 * @param dict a SMFDict_T object 97 * @param key key to look for in the dictionary. 98 * @param success If set to non-NULL, then the function assigns here the result of the 99 * conversion 100 * @return The unsigned long value of the key or (unsigned long)-1 on any error. 101 */ 102 unsigned long smf_dict_get_ulong(SMFDict_T *dict, const char * key, int *success); 103 104 /*! 105 * @fn void smf_dict_remove(SMFDict_T *dict, const char * key) 106 * @brief Removes a key and its associated value from a SMFDict_T 107 * @param dict a SMFDict_T 108 * @param key the key to remove. 109 */ 110 void smf_dict_remove(SMFDict_T *dict, const char * key); 111 112 /*! 113 * @fn SMFList_T *smf_dict_get_keys(SMFDict_T *dict) 114 * @brief Retrieves every key inside a SMFDict_T 115 * @param dict a SMFDict_T object 116 * @return a SMFList_T containing all the keys inside the dictionary. 117 * Use smf_list_free() when done using the list. 118 */ 119 SMFList_T *smf_dict_get_keys(SMFDict_T *dict); 120 121 /*! 122 * @fn void smf_dict_map(SMFDict_T *dict, void(*func)(char *key,char *value, void *args), void *args) 123 * @brief Calls the given function for each of the key/value pairs in the SMFDict_T. The function is 124 * passed the key and value of each pair, and the given args parameter. 125 * @param dict a SMFDict_T object 126 * @param func function to call for each element 127 * @param args optional arguments to pass to the function 128 */ 129 void smf_dict_map(SMFDict_T *dict, void(*func)(char *key,char *value, void *args), void *args); 130 131 /*! 132 * @def smf_dict_count(dict) 133 * @brief Get the number of elements in a SMFDict_T 134 * @return number of elemtents in a SMFDict_T 135 */ 136 #define smf_dict_count(dict) ((dict)->n) 137 138 #endif /* _SMF_DICT_H */ 139 140