dmlite  0.6
any.h
Go to the documentation of this file.
1 /** @file include/dmlite/c/any.h
2  * @brief Opaque handler to pass different types of values to the API.
3  * @author Alejandro Álvarez Ayllon <aalvarez@cern.ch>
4  * @note Basically it wraps boost::any and dmlite::Extensible.
5  */
6 #ifndef DMLITE_ANY_H
7 #define DMLITE_ANY_H
8 
9 #include "../common/config.h"
10 #include <stddef.h>
11 
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15 
16 /**
17  * @brief Used to pass configuration values.
18  */
19 typedef struct dmlite_any dmlite_any;
20 
21 /**
22  * @brief Handles key->value pairs.
23  */
25 
26 /**
27  * @brief Creates a new dmlite_any.
28  * @param str The string that will be wrapped. It is safe to free afterwards.
29  * @return A newly allocated dmlite_any.
30  */
31 dmlite_any* dmlite_any_new_string(const char* str);
32 
33 /**
34  * @brief Creates a new dmlite_any.
35  * @param n The number of elements.
36  * @param strv The strings that will be wrapped. It is safe to free afterwards.
37  * @return A newly allocated dmlite_any.
38  */
39 dmlite_any* dmlite_any_new_string_array(unsigned n, const char** strv);
40 
41 /**
42  * @brief Creates a new dmlite_any.
43  * @param l The long that will be wrapped.
44  * @return A newly allocated dmlite_any.
45  */
47 
48 /**
49  * @brief Creates a new dmlite_any.
50  * @param n The number of elements.
51  * @param lv The longs that will be wrapped.
52  * @return A newly allocated dmlite_any.
53  */
54 dmlite_any* dmlite_any_new_long_array(unsigned n, long* lv);
55 
56 /**
57  * @brief Frees a dmlite_any.
58  * @param any The dmlite_any to destroy.
59  */
60 void dmlite_any_free(dmlite_any* any);
61 
62 /**
63  * @brief Gets the string interpretation of the dmlite_any.
64  * @details Defaults to "".
65  * @param any The dmlite_any to convert.
66  * @param buffer Where to put the string.
67  * @param bsize The size of the buffer.
68  */
69 void dmlite_any_to_string(const dmlite_any* any, char* buffer, size_t bsize);
70 
71 /**
72  * @brief Returns the long interpretation of they dmlite_any.
73  * @details Defaults to 0.
74  * @param any The dmlite_any to convert.
75  */
76 long dmlite_any_to_long(const dmlite_any* any);
77 
78 
79 /**
80  * @brief Created a new generic dictionary.
81  * @return A newly allocated dmlite_any_dict.
82  */
84 
85 /**
86  * @brief Make a copy of the dictionary.
87  * @param dict The original
88  * @return A newly allocated copy of dict.
89  */
91 
92 /**
93  * @brief Frees a dmlite_any_dict
94  */
96 
97 /**
98  * @brief Clears the dictionary.
99  */
101 
102 /**
103  * @brief Insert a new dmlite_any value into the dictionary.
104  * @details Replaces if already present.
105  * @param d The dictionary.
106  * @param k The key.
107  * @param v The value.
108  */
109 void dmlite_any_dict_insert(dmlite_any_dict* d, const char* k, const dmlite_any* v);
110 
111 /**
112  * @brief Returns how many elements there are in a specific dictionary.
113  */
114 unsigned long dmlite_any_dict_count(const dmlite_any_dict* d);
115 
116 /**
117  * @brief Returns the value associated with the key k.
118  * @return NULL if not found.
119  */
120 dmlite_any* dmlite_any_dict_get(const dmlite_any_dict* d, const char* k);
121 
122 /**
123  * @brief Removes a key-value from the dictionary.
124  * @param d The dictionary.
125  * @param k The key to be removed.
126  */
127 void dmlite_any_dict_erase(dmlite_any_dict* d, const char* k);
128 
129 /**
130  * @brief Generates a JSON serialization of the dictionary.
131  * @return The same pointer as buffer.
132  */
133 char* dmlite_any_dict_to_json(const dmlite_any_dict* d, char* buffer, size_t bsize);
134 
135 /**
136  * @brief Populates a dmlite_any_dict from a JSON string.
137  */
138 dmlite_any_dict* dmlite_any_dict_from_json(const char* json);
139 
140 /**
141  * @brief Puts in keys a pointer to an array of strings with all the available
142  * keys in d.
143  * @details Use dmlite_any_dict_keys_free to free.
144  * @param d The Dictionary.
145  * @param nkeys Will be set to the number of stored keys.
146  */
147 void dmlite_any_dict_keys(const dmlite_any_dict* d, unsigned* nkeys, char*** keys);
148 
149 /**
150  * @brief Frees an array of strings allocated by dmlite_any_dict_keys.
151  * @param n The number of keys in **keys
152  * @param keys The array of keys.
153  */
154 void dmlite_any_dict_keys_free(unsigned n, char** keys);
155 
156 #ifdef __cplusplus
157 }
158 #endif
159 
160 #endif /* DMLITE_ANY_H */
161