diff options
Diffstat (limited to 'src/include/gnunet_psyc_env.h')
-rw-r--r-- | src/include/gnunet_psyc_env.h | 340 |
1 files changed, 340 insertions, 0 deletions
diff --git a/src/include/gnunet_psyc_env.h b/src/include/gnunet_psyc_env.h new file mode 100644 index 0000000..0d878cb --- /dev/null +++ b/src/include/gnunet_psyc_env.h | |||
@@ -0,0 +1,340 @@ | |||
1 | /* | ||
2 | * This file is part of GNUnet. | ||
3 | * Copyright (C) 2013 GNUnet e.V. | ||
4 | * | ||
5 | * GNUnet is free software: you can redistribute it and/or modify it | ||
6 | * under the terms of the GNU Affero General Public License as published | ||
7 | * by the Free Software Foundation, either version 3 of the License, | ||
8 | * or (at your option) any later version. | ||
9 | * | ||
10 | * GNUnet is distributed in the hope that it will be useful, but | ||
11 | * WITHOUT ANY WARRANTY; without even the implied warranty of | ||
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
13 | * Affero General Public License for more details. | ||
14 | * | ||
15 | * You should have received a copy of the GNU Affero General Public License | ||
16 | * along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Gabor X Toth | ||
23 | * | ||
24 | * @file | ||
25 | * PSYC Environment library | ||
26 | * | ||
27 | * @defgroup psyc-util-env PSYC Utilities library: Environment | ||
28 | * Environment data structure operations for PSYC and Social messages. | ||
29 | * | ||
30 | * Library providing operations for the @e environment of | ||
31 | * PSYC and Social messages, and for (de)serializing variable values. | ||
32 | * | ||
33 | * @{ | ||
34 | */ | ||
35 | |||
36 | |||
37 | #ifndef GNUNET_PSYC_ENV_H | ||
38 | #define GNUNET_PSYC_ENV_H | ||
39 | |||
40 | #ifdef __cplusplus | ||
41 | extern "C" | ||
42 | { | ||
43 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
44 | } | ||
45 | #endif | ||
46 | #endif | ||
47 | |||
48 | |||
49 | /** | ||
50 | * Possible operations on PSYC state (persistent) and transient variables (per message). | ||
51 | */ | ||
52 | enum GNUNET_PSYC_Operator | ||
53 | { | ||
54 | /** | ||
55 | * Set value of a transient variable. | ||
56 | */ | ||
57 | GNUNET_PSYC_OP_SET = ':', | ||
58 | |||
59 | /** | ||
60 | * Assign value for a persistent state variable. | ||
61 | * | ||
62 | * If an assigned value is NULL, the variable is deleted. | ||
63 | */ | ||
64 | GNUNET_PSYC_OP_ASSIGN = '=', | ||
65 | |||
66 | /** | ||
67 | * Augment state variable. | ||
68 | * | ||
69 | * Used for appending strings, adding numbers, and adding new items to a list or dictionary. | ||
70 | */ | ||
71 | GNUNET_PSYC_OP_AUGMENT = '+', | ||
72 | |||
73 | /** | ||
74 | * Diminish state variable. | ||
75 | * | ||
76 | * Used for subtracting numbers, and removing items from a list or dictionary. | ||
77 | */ | ||
78 | GNUNET_PSYC_OP_DIMINISH = '-', | ||
79 | |||
80 | /** | ||
81 | * Update state variable. | ||
82 | * | ||
83 | * Used for modifying a single item of a list or dictionary. | ||
84 | */ | ||
85 | GNUNET_PSYC_OP_UPDATE = '@', | ||
86 | }; | ||
87 | |||
88 | |||
89 | /** | ||
90 | * PSYC variable types. | ||
91 | */ | ||
92 | enum GNUNET_PSYC_Type | ||
93 | { | ||
94 | GNUNET_PSYC_TYPE_DATA = 0, | ||
95 | GNUNET_PSYC_TYPE_NUMBER, | ||
96 | GNUNET_PSYC_TYPE_LIST, | ||
97 | GNUNET_PSYC_TYPE_DICT | ||
98 | }; | ||
99 | |||
100 | |||
101 | /** | ||
102 | * PSYC state modifier. | ||
103 | */ | ||
104 | struct GNUNET_PSYC_Modifier | ||
105 | { | ||
106 | /** | ||
107 | * State operation. | ||
108 | */ | ||
109 | enum GNUNET_PSYC_Operator oper; | ||
110 | |||
111 | /** | ||
112 | * Variable name. | ||
113 | */ | ||
114 | const char *name; | ||
115 | |||
116 | /** | ||
117 | * Size of @a value. | ||
118 | */ | ||
119 | size_t value_size; | ||
120 | |||
121 | /** | ||
122 | * Value of variable. | ||
123 | */ | ||
124 | const void *value; | ||
125 | |||
126 | /** | ||
127 | * Next modifier. | ||
128 | */ | ||
129 | struct GNUNET_PSYC_Modifier *next; | ||
130 | |||
131 | /** | ||
132 | * Previous modifier. | ||
133 | */ | ||
134 | struct GNUNET_PSYC_Modifier *prev; | ||
135 | }; | ||
136 | |||
137 | |||
138 | /** | ||
139 | * Environment for a message. | ||
140 | * | ||
141 | * Contains modifiers. | ||
142 | */ | ||
143 | struct GNUNET_PSYC_Environment; | ||
144 | |||
145 | |||
146 | /** | ||
147 | * Create an environment. | ||
148 | * | ||
149 | * @return A newly allocated environment. | ||
150 | */ | ||
151 | struct GNUNET_PSYC_Environment * | ||
152 | GNUNET_PSYC_env_create (); | ||
153 | |||
154 | |||
155 | /** | ||
156 | * Add a modifier to the environment. | ||
157 | * | ||
158 | * @param env The environment. | ||
159 | * @param oper Operation to perform. | ||
160 | * @param name Name of the variable. | ||
161 | * @param value Value of the variable. | ||
162 | * @param value_size Size of @a value. | ||
163 | */ | ||
164 | void | ||
165 | GNUNET_PSYC_env_add (struct GNUNET_PSYC_Environment *env, | ||
166 | enum GNUNET_PSYC_Operator oper, const char *name, | ||
167 | const void *value, size_t value_size); | ||
168 | |||
169 | |||
170 | /** | ||
171 | * Get the first modifier of the environment. | ||
172 | */ | ||
173 | struct GNUNET_PSYC_Modifier * | ||
174 | GNUNET_PSYC_env_head (const struct GNUNET_PSYC_Environment *env); | ||
175 | |||
176 | |||
177 | |||
178 | /** | ||
179 | * Get the last modifier of the environment. | ||
180 | */ | ||
181 | struct GNUNET_PSYC_Modifier * | ||
182 | GNUNET_PSYC_env_tail (const struct GNUNET_PSYC_Environment *env); | ||
183 | |||
184 | |||
185 | /** | ||
186 | * Remove a modifier from the environment. | ||
187 | */ | ||
188 | void | ||
189 | GNUNET_PSYC_env_remove (struct GNUNET_PSYC_Environment *env, | ||
190 | struct GNUNET_PSYC_Modifier *mod); | ||
191 | |||
192 | |||
193 | /** | ||
194 | * Remove a modifier at the beginning of the environment. | ||
195 | */ | ||
196 | int | ||
197 | GNUNET_PSYC_env_shift (struct GNUNET_PSYC_Environment *env, | ||
198 | enum GNUNET_PSYC_Operator *oper, const char **name, | ||
199 | const void **value, size_t *value_size); | ||
200 | |||
201 | |||
202 | /** | ||
203 | * Iterator for modifiers in the environment. | ||
204 | * | ||
205 | * @param cls Closure. | ||
206 | * @param mod Modifier. | ||
207 | * | ||
208 | * @return #GNUNET_YES to continue iterating, | ||
209 | * #GNUNET_NO to stop. | ||
210 | */ | ||
211 | typedef int | ||
212 | (*GNUNET_PSYC_Iterator) (void *cls, enum GNUNET_PSYC_Operator oper, | ||
213 | const char *name, const char *value, | ||
214 | uint32_t value_size); | ||
215 | |||
216 | |||
217 | /** | ||
218 | * Iterate through all modifiers in the environment. | ||
219 | * | ||
220 | * @param env The environment. | ||
221 | * @param it Iterator. | ||
222 | * @param it_cls Closure for iterator. | ||
223 | */ | ||
224 | void | ||
225 | GNUNET_PSYC_env_iterate (const struct GNUNET_PSYC_Environment *env, | ||
226 | GNUNET_PSYC_Iterator it, void *it_cls); | ||
227 | |||
228 | |||
229 | /** | ||
230 | * Get the number of modifiers in the environment. | ||
231 | * | ||
232 | * @param env The environment. | ||
233 | * | ||
234 | * @return Number of modifiers. | ||
235 | */ | ||
236 | size_t | ||
237 | GNUNET_PSYC_env_get_count (const struct GNUNET_PSYC_Environment *env); | ||
238 | |||
239 | |||
240 | /** | ||
241 | * Destroy an environment. | ||
242 | * | ||
243 | * @param env The environment to destroy. | ||
244 | */ | ||
245 | void | ||
246 | GNUNET_PSYC_env_destroy (struct GNUNET_PSYC_Environment *env); | ||
247 | |||
248 | |||
249 | /** | ||
250 | * Get the type of variable. | ||
251 | * | ||
252 | * @param name Name of the variable. | ||
253 | * | ||
254 | * @return Variable type. | ||
255 | */ | ||
256 | enum GNUNET_PSYC_Type | ||
257 | GNUNET_PSYC_var_get_type (char *name); | ||
258 | |||
259 | |||
260 | /** | ||
261 | * Perform an operation on a variable. | ||
262 | * | ||
263 | * @param name Name of variable. | ||
264 | * @param current_value Current value of variable. | ||
265 | * @param current_value_size Size of @a current_value. | ||
266 | * @param oper Operator. | ||
267 | * @param args Arguments for the operation. | ||
268 | * @param args_size Size of @a args. | ||
269 | * @param return_value Return value. | ||
270 | * @param return_value_size Size of @a return_value. | ||
271 | * | ||
272 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
273 | */ | ||
274 | int | ||
275 | GNUNET_PSYC_operation (char *name, void *current_value, size_t current_value_size, | ||
276 | enum GNUNET_PSYC_Operator oper, void *args, size_t args_size, | ||
277 | void **return_value, size_t *return_value_size); | ||
278 | |||
279 | |||
280 | /** | ||
281 | * Get the variable's value as an integer. | ||
282 | * | ||
283 | * @param size Size of value. | ||
284 | * @param value Raw value of variable. | ||
285 | * @param[out] number Value converted to a 64-bit integer. | ||
286 | * | ||
287 | * @return #GNUNET_OK on success, #GNUNET_SYSERR if an error occurred (e.g. the value is invalid). | ||
288 | */ | ||
289 | int | ||
290 | GNUNET_PSYC_value_to_number (size_t size, const void *value, int64_t *number); | ||
291 | |||
292 | |||
293 | /** | ||
294 | * Get the variable's value as a dictionary. | ||
295 | * | ||
296 | * @param size Size of value. | ||
297 | * @param value Raw value of variable. | ||
298 | * @param[out] dict A newly created hashmap holding the elements of the dictionary. | ||
299 | * | ||
300 | * @return #GNUNET_OK on success, #GNUNET_SYSERR if an error occurred (e.g. the value is invalid). | ||
301 | */ | ||
302 | int | ||
303 | GNUNET_PSYC_value_to_dict (size_t size, const void *value, struct GNUNET_CONTAINER_MultiHashMap **dict); | ||
304 | |||
305 | |||
306 | /** | ||
307 | * Create a PSYC variable value from an integer. | ||
308 | * | ||
309 | * @param number The number to convert. | ||
310 | * @param[out] value_size Size of returned value. | ||
311 | * | ||
312 | * @return A newly allocated value or NULL on error. | ||
313 | */ | ||
314 | void * | ||
315 | GNUNET_PSYC_value_from_number (int64_t number, size_t *value_size); | ||
316 | |||
317 | |||
318 | /** | ||
319 | * Create a PSYC variable value from a dictionary. | ||
320 | * | ||
321 | * @param dict The dict to convert. | ||
322 | * @param[out] value_size Size of returned value. | ||
323 | * | ||
324 | * @return A newly allocated value or NULL on error. | ||
325 | */ | ||
326 | void * | ||
327 | GNUNET_PSYC_value_from_dict (struct GNUNET_CONTAINER_MultiHashMap *dict, size_t *value_size); | ||
328 | |||
329 | |||
330 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
331 | { | ||
332 | #endif | ||
333 | #ifdef __cplusplus | ||
334 | } | ||
335 | #endif | ||
336 | |||
337 | /* ifndef GNUNET_PSYC_ENV_H */ | ||
338 | #endif | ||
339 | |||
340 | /** @} */ /* end of group */ | ||