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 <stddef.h> 00010 00011 #ifdef __cplusplus 00012 extern "C" { 00013 #endif 00014 00015 /** 00016 * @brief Used to pass configuration values. 00017 */ 00018 typedef struct dmlite_any dmlite_any; 00019 00020 /** 00021 * @brief Handles key->value pairs. 00022 */ 00023 typedef struct dmlite_any_dict dmlite_any_dict; 00024 00025 /** 00026 * @brief Creates a new dmlite_any. 00027 * @param str The string that will be wrapped. It is safe to free afterwards. 00028 * @return A newly allocated dmlite_any. 00029 */ 00030 dmlite_any* dmlite_any_new_string(const char* str); 00031 00032 /** 00033 * @brief Creates a new dmlite_any. 00034 * @param n The number of elements. 00035 * @param strv The strings that will be wrapped. It is safe to free afterwards. 00036 * @return A newly allocated dmlite_any. 00037 */ 00038 dmlite_any* dmlite_any_new_string_array(unsigned n, const char** strv); 00039 00040 /** 00041 * @brief Creates a new dmlite_any. 00042 * @param l The long that will be wrapped. 00043 * @return A newly allocated dmlite_any. 00044 */ 00045 dmlite_any* dmlite_any_new_long(long l); 00046 00047 /** 00048 * @brief Creates a new dmlite_any. 00049 * @param n The number of elements. 00050 * @param lv The longs that will be wrapped. 00051 * @return A newly allocated dmlite_any. 00052 */ 00053 dmlite_any* dmlite_any_new_long_array(unsigned n, long* lv); 00054 00055 /** 00056 * @brief Frees a dmlite_any. 00057 * @param any The dmlite_any to destroy. 00058 */ 00059 void dmlite_any_free(dmlite_any* any); 00060 00061 /** 00062 * @brief Gets the string interpretation of the dmlite_any. 00063 * @details Defaults to "". 00064 * @param any The dmlite_any to convert. 00065 * @param buffer Where to put the string. 00066 * @param bsize The size of the buffer. 00067 */ 00068 void dmlite_any_to_string(const dmlite_any* any, char* buffer, size_t bsize); 00069 00070 /** 00071 * @brief Returns the long interpretation of they dmlite_any. 00072 * @details Defaults to 0. 00073 * @param any The dmlite_any to convert. 00074 */ 00075 long dmlite_any_to_long(const dmlite_any* any); 00076 00077 00078 /** 00079 * @brief Created a new generic dictionary. 00080 * @return A newly allocated dmlite_any_dict. 00081 */ 00082 dmlite_any_dict* dmlite_any_dict_new(); 00083 00084 /** 00085 * @brief Make a copy of the dictionary. 00086 * @param dict The original 00087 * @return A newly allocated copy of dict. 00088 */ 00089 dmlite_any_dict* dmlite_any_dict_copy(const dmlite_any_dict* dict); 00090 00091 /** 00092 * @brief Frees a dmlite_any_dict 00093 */ 00094 void dmlite_any_dict_free(dmlite_any_dict* d); 00095 00096 /** 00097 * @brief Clears the dictionary. 00098 */ 00099 void dmlite_any_dict_clear(dmlite_any_dict* d); 00100 00101 /** 00102 * @brief Insert a new dmlite_any value into the dictionary. 00103 * @details Replaces if already present. 00104 * @param d The dictionary. 00105 * @param k The key. 00106 * @param v The value. 00107 */ 00108 void dmlite_any_dict_insert(dmlite_any_dict* d, const char* k, const dmlite_any* v); 00109 00110 /** 00111 * @brief Returns how many elements there are in a specific dictionary. 00112 */ 00113 unsigned long dmlite_any_dict_count(const dmlite_any_dict* d); 00114 00115 /** 00116 * @brief Returns the value associated with the key k. 00117 * @return NULL if not found. 00118 */ 00119 dmlite_any* dmlite_any_dict_get(const dmlite_any_dict* d, const char* k); 00120 00121 /** 00122 * @brief Removes a key-value from the dictionary. 00123 * @param d The dictionary. 00124 * @param k The key to be removed. 00125 */ 00126 void dmlite_any_dict_erase(dmlite_any_dict* d, const char* k); 00127 00128 /** 00129 * @brief Generates a JSON serialization of the dictionary. 00130 * @return The same pointer as buffer. 00131 */ 00132 char* dmlite_any_dict_to_json(const dmlite_any_dict* d, char* buffer, size_t bsize); 00133 00134 /** 00135 * @brief Populates a dmlite_any_dict from a JSON string. 00136 */ 00137 dmlite_any_dict* dmlite_any_dict_from_json(const char* json); 00138 00139 /** 00140 * @brief Puts in keys a pointer to an array of strings with all the available 00141 * keys in d. 00142 * @details Use dmlite_any_dict_keys_free to free. 00143 * @param d The Dictionary. 00144 * @param nkeys Will be set to the number of stored keys. 00145 */ 00146 void dmlite_any_dict_keys(const dmlite_any_dict* d, unsigned* nkeys, char*** keys); 00147 00148 /** 00149 * @brief Frees an array of strings allocated by dmlite_any_dict_keys. 00150 * @param n The number of keys in **keys 00151 * @param keys The array of keys. 00152 */ 00153 void dmlite_any_dict_keys_free(unsigned n, char** keys); 00154 00155 #ifdef __cplusplus 00156 } 00157 #endif 00158 00159 #endif /* DMLITE_ANY_H */ 00160