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