any.h

Go to the documentation of this file.
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 

Generated on 3 Mar 2013 for dmlite by  doxygen 1.4.7