00001 /** @file include/dmlite/c/any.h 00002 * @brief Opaque handler to pass different types of values to the API. 00003 * @author Alejandro Álvarez Ayllon <aalvarez@cern.ch> 00004 * @note Basically it wraps boost::any and dmlite::Extensible. 00005 */ 00006 #ifndef DMLITE_ANY_H 00007 #define DMLITE_ANY_H 00008 00009 #include "dmlite/common/config.h" 00010 #include <stddef.h> 00011 #include <stdint.h> 00012 00013 #ifdef __cplusplus 00014 extern "C" { 00015 #endif 00016 00017 /** 00018 * @brief Used to pass configuration values. 00019 */ 00020 typedef struct dmlite_any dmlite_any; 00021 00022 /** 00023 * @brief Handles key->value pairs. 00024 */ 00025 typedef struct dmlite_any_dict dmlite_any_dict; 00026 00027 /** 00028 * @brief Creates a new dmlite_any. 00029 * @param str The string that will be wrapped. It is safe to free afterwards. 00030 * @return A newly allocated dmlite_any. 00031 */ 00032 dmlite_any* dmlite_any_new_string(const char* str); 00033 00034 /** 00035 * @brief Creates a new dmlite_any. 00036 * @param l The long that will be wrapped. 00037 * @return A newly allocated dmlite_any. 00038 */ 00039 dmlite_any* dmlite_any_new_long(long l); 00040 00041 /** 00042 * @brief Creates a new dmlite_any from an int64_t type. 00043 * @param i The int64_t value. 00044 * @return A newly allocated dmlite_any. 00045 */ 00046 dmlite_any* dmlite_any_new_s64(int64_t i); 00047 00048 /** 00049 * @brief Creates a new dmlite_any from an uint64_t type. 00050 * @param i The uint64_t value. 00051 * @return A newly allocated dmlite_any. 00052 */ 00053 dmlite_any* dmlite_any_new_u64(uint64_t i); 00054 00055 /** 00056 * @brief Creates a new dmlite_any. 00057 * @param n The number of elements. 00058 * @param strv The strings that will be wrapped. It is safe to free afterwards. 00059 * @return A newly allocated dmlite_any. 00060 * @deprecated Use dmlite_set_array instead. 00061 */ 00062 dmlite_any* dmlite_any_new_string_array(unsigned n, const char** strv); 00063 00064 /** 00065 * @brief Creates a new dmlite_any. 00066 * @param n The number of elements. 00067 * @param lv The longs that will be wrapped. 00068 * @return A newly allocated dmlite_any. 00069 * @deprecated Use dmlite_set_array instead. 00070 */ 00071 dmlite_any* dmlite_any_new_long_array(unsigned n, long* lv); 00072 00073 /** 00074 * @brief Frees a dmlite_any. 00075 * @param any The dmlite_any to destroy. 00076 */ 00077 void dmlite_any_free(dmlite_any* any); 00078 00079 /** 00080 * @brief Gets the string interpretation of the dmlite_any. 00081 * @details Defaults to "". 00082 * @param any The dmlite_any to convert. 00083 * @param buffer Where to put the string. 00084 * @param bsize The size of the buffer. 00085 */ 00086 void dmlite_any_to_string(const dmlite_any* any, char* buffer, size_t bsize); 00087 00088 /** 00089 * @brief Returns the long interpretation of they dmlite_any. 00090 * @details Defaults to 0. 00091 * @param any The dmlite_any to convert. 00092 */ 00093 long dmlite_any_to_long(const dmlite_any* any); 00094 00095 /** 00096 * @brief Returns the int64_t interpretation of they dmlite_any. 00097 * @details Defaults to 0. 00098 * @param any The dmlite_any to convert. 00099 */ 00100 int64_t dmlite_any_to_s64(const dmlite_any* any); 00101 00102 /** 00103 * @brief Returns the uint64_t interpretation of they dmlite_any. 00104 * @details Defaults to 0. 00105 * @param any The dmlite_any to convert. 00106 */ 00107 uint64_t dmlite_any_to_u64(const dmlite_any* any); 00108 00109 00110 /** 00111 * @brief Created a new generic dictionary. 00112 * @return A newly allocated dmlite_any_dict. 00113 */ 00114 dmlite_any_dict* dmlite_any_dict_new(); 00115 00116 /** 00117 * @brief Make a copy of the dictionary. 00118 * @param dict The original 00119 * @return A newly allocated copy of dict. 00120 */ 00121 dmlite_any_dict* dmlite_any_dict_copy(const dmlite_any_dict* dict); 00122 00123 /** 00124 * @brief Frees a dmlite_any_dict 00125 */ 00126 void dmlite_any_dict_free(dmlite_any_dict* d); 00127 00128 /** 00129 * @brief Clears the dictionary. 00130 */ 00131 void dmlite_any_dict_clear(dmlite_any_dict* d); 00132 00133 /** 00134 * @brief Insert a new dmlite_any value into the dictionary. 00135 * @details Replaces if already present. 00136 * @param d The dictionary. 00137 * @param k The key. 00138 * @param v The value. 00139 */ 00140 void dmlite_any_dict_insert(dmlite_any_dict* d, const char* k, const dmlite_any* v); 00141 00142 /** 00143 * @brief Returns how many elements there are in a specific dictionary. 00144 */ 00145 unsigned long dmlite_any_dict_count(const dmlite_any_dict* d); 00146 00147 /** 00148 * @brief Returns the value associated with the key k. 00149 * @return NULL if not found. 00150 */ 00151 dmlite_any* dmlite_any_dict_get(const dmlite_any_dict* d, const char* k); 00152 00153 /** 00154 * @brief Removes a key-value from the dictionary. 00155 * @param d The dictionary. 00156 * @param k The key to be removed. 00157 */ 00158 void dmlite_any_dict_erase(dmlite_any_dict* d, const char* k); 00159 00160 /** 00161 * @brief Generates a JSON serialization of the dictionary. 00162 * @return The same pointer as buffer. 00163 */ 00164 char* dmlite_any_dict_to_json(const dmlite_any_dict* d, char* buffer, size_t bsize); 00165 00166 /** 00167 * @brief Populates a dmlite_any_dict from a JSON string. 00168 */ 00169 dmlite_any_dict* dmlite_any_dict_from_json(const char* json); 00170 00171 /** 00172 * @brief Puts in keys a pointer to an array of strings with all the available 00173 * keys in d. 00174 * @details Use dmlite_any_dict_keys_free to free. 00175 * @param d The Dictionary. 00176 * @param nkeys Will be set to the number of stored keys. 00177 */ 00178 void dmlite_any_dict_keys(const dmlite_any_dict* d, unsigned* nkeys, char*** keys); 00179 00180 /** 00181 * @brief Frees an array of strings allocated by dmlite_any_dict_keys. 00182 * @param n The number of keys in **keys 00183 * @param keys The array of keys. 00184 */ 00185 void dmlite_any_dict_keys_free(unsigned n, char** keys); 00186 00187 #ifdef __cplusplus 00188 } 00189 #endif 00190 00191 #endif /* DMLITE_ANY_H */ 00192