diff options
Diffstat (limited to 'src/include/gnunet_json_lib.h')
-rw-r--r-- | src/include/gnunet_json_lib.h | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/src/include/gnunet_json_lib.h b/src/include/gnunet_json_lib.h new file mode 100644 index 000000000..e39938858 --- /dev/null +++ b/src/include/gnunet_json_lib.h | |||
@@ -0,0 +1,354 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | Copyright (C) 2014, 2015, 2016 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software; you can redistribute it and/or modify it under the | ||
6 | terms of the GNU General Public License as published by the Free Software | ||
7 | Foundation; either version 3, or (at your option) any later version. | ||
8 | |||
9 | GNUnet is distributed in the hope that it will be useful, but WITHOUT ANY | ||
10 | WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR | ||
11 | A PARTICULAR PURPOSE. See the GNU General Public License for more details. | ||
12 | |||
13 | You should have received a copy of the GNU General Public License along with | ||
14 | GNUnet; see the file COPYING. If not, If not, see <http://www.gnu.org/licenses/> | ||
15 | */ | ||
16 | /** | ||
17 | * @file gnunet_json_lib.h | ||
18 | * @brief functions to parse JSON objects into GNUnet objects | ||
19 | * @author Florian Dold | ||
20 | * @author Benedikt Mueller | ||
21 | * @author Christian Grothoff | ||
22 | */ | ||
23 | #include "platform.h" | ||
24 | #include <gnunet/gnunet_util_lib.h> | ||
25 | #include <jansson.h> | ||
26 | |||
27 | |||
28 | /* ****************** Generic parser interface ******************* */ | ||
29 | |||
30 | /** | ||
31 | * @brief Entry in parser specification for #GNUNET_JSON_parse(). | ||
32 | */ | ||
33 | struct GNUNET_JSON_Specification; | ||
34 | |||
35 | |||
36 | /** | ||
37 | * Function called to parse JSON argument. | ||
38 | * | ||
39 | * @param cls closure | ||
40 | * @param root JSON to parse | ||
41 | * @param spec our specification entry with further details | ||
42 | * @return #GNUNET_SYSERR on error, | ||
43 | * #GNUNET_OK on success | ||
44 | */ | ||
45 | typedef int | ||
46 | (*GNUNET_JSON_Parser)(void *cls, | ||
47 | json_t *root, | ||
48 | struct GNUNET_JSON_Specification *spec); | ||
49 | |||
50 | |||
51 | /** | ||
52 | * Function called to clean up data from earlier parsing. | ||
53 | * | ||
54 | * @param cls closure | ||
55 | * @param spec our specification entry with data to clean. | ||
56 | */ | ||
57 | typedef void | ||
58 | (*GNUNET_JSON_Cleaner)(void *cls, | ||
59 | struct GNUNET_JSON_Specification *spec); | ||
60 | |||
61 | |||
62 | /** | ||
63 | * @brief Entry in parser specification for #GNUNET_JSON_parse(). | ||
64 | */ | ||
65 | struct GNUNET_JSON_Specification | ||
66 | { | ||
67 | /** | ||
68 | * Function for how to parse this type of entry. | ||
69 | */ | ||
70 | GNUNET_JSON_Parser parser; | ||
71 | |||
72 | /** | ||
73 | * Function for how to clean up this type of entry. | ||
74 | */ | ||
75 | GNUNET_JSON_Cleaner cleaner; | ||
76 | |||
77 | /** | ||
78 | * Closure for @e parser and @e cleaner. | ||
79 | */ | ||
80 | void *cls; | ||
81 | |||
82 | /** | ||
83 | * Name of the field to parse, use NULL to get the JSON | ||
84 | * of the main object instead of the JSON of an individual field. | ||
85 | */ | ||
86 | const char *field; | ||
87 | |||
88 | /** | ||
89 | * Pointer, details specific to the @e parser. | ||
90 | */ | ||
91 | void *ptr; | ||
92 | |||
93 | /** | ||
94 | * Number of bytes available in @e ptr. | ||
95 | */ | ||
96 | size_t ptr_size; | ||
97 | |||
98 | /** | ||
99 | * Where should we store the final size of @e ptr. | ||
100 | */ | ||
101 | size_t *size_ptr; | ||
102 | |||
103 | }; | ||
104 | |||
105 | |||
106 | /** | ||
107 | * Navigate and parse data in a JSON tree. Tries to parse the @a root | ||
108 | * to find all of the values given in the @a spec. If one of the | ||
109 | * entries in @a spec cannot be found or parsed, the name of the JSON | ||
110 | * field is returned in @a error_json_name, and the offset of the | ||
111 | * entry in @a spec is returned in @a error_line. | ||
112 | * | ||
113 | * @param root the JSON node to start the navigation at. | ||
114 | * @param spec parse specification array | ||
115 | * @param[out] error_json_name which JSON field was problematic | ||
116 | * @param[out] which index into @a spec did we encounter an error | ||
117 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error | ||
118 | */ | ||
119 | int | ||
120 | GNUNET_JSON_parse (const json_t *root, | ||
121 | struct GNUNET_JSON_Specification *spec, | ||
122 | const char **error_json_name, | ||
123 | unsigned int *error_line); | ||
124 | |||
125 | |||
126 | /** | ||
127 | * Frees all elements allocated during a #GNUNET_JSON_parse() | ||
128 | * operation. | ||
129 | * | ||
130 | * @param spec specification of the parse operation | ||
131 | */ | ||
132 | void | ||
133 | GNUNET_JSON_parse_free (struct GNUNET_JSON_Specification *spec); | ||
134 | |||
135 | |||
136 | |||
137 | /* ****************** Canonical parser specifications ******************* */ | ||
138 | |||
139 | |||
140 | /** | ||
141 | * End of a parser specification. | ||
142 | */ | ||
143 | struct GNUNET_JSON_Specification | ||
144 | GNUNET_JSON_spec_end (void); | ||
145 | |||
146 | |||
147 | /** | ||
148 | * Variable size object (in network byte order, encoded using Crockford | ||
149 | * Base32hex encoding). | ||
150 | * | ||
151 | * @param name name of the JSON field | ||
152 | * @param[out] obj pointer where to write the data, must have @a size bytes | ||
153 | * @param size number of bytes expected in @a obj | ||
154 | */ | ||
155 | struct GNUNET_JSON_Specification | ||
156 | GNUNET_JSON_spec_fixed (const char *name, | ||
157 | void *obj, | ||
158 | size_t size); | ||
159 | |||
160 | |||
161 | /** | ||
162 | * Fixed size object (in network byte order, encoded using Crockford | ||
163 | * Base32hex encoding). | ||
164 | * | ||
165 | * @param name name of the JSON field | ||
166 | * @param obj pointer where to write the data (type of `*obj` will determine size) | ||
167 | */ | ||
168 | #define GNUNET_JSON_spec_fixed_auto(name,obj) GNUNET_JSON_spec_fixed (name, obj, sizeof (*obj)) | ||
169 | |||
170 | |||
171 | /** | ||
172 | * Variable size object (in network byte order, encoded using | ||
173 | * Crockford Base32hex encoding). | ||
174 | * | ||
175 | * @param name name of the JSON field | ||
176 | * @param[out] obj pointer where to write the data, will be allocated | ||
177 | * @param[out] size where to store the number of bytes allocated for @a obj | ||
178 | */ | ||
179 | struct GNUNET_JSON_Specification | ||
180 | GNUNET_JSON_spec_varsize (const char *name, | ||
181 | void **obj, | ||
182 | size_t *size); | ||
183 | |||
184 | |||
185 | /** | ||
186 | * The expected field stores a string. | ||
187 | * | ||
188 | * @param name name of the JSON field | ||
189 | * @param strptr where to store a pointer to the field | ||
190 | */ | ||
191 | struct GNUNET_JSON_Specification | ||
192 | GNUNET_JSON_spec_string (const char *name, | ||
193 | const char **strptr); | ||
194 | |||
195 | /** | ||
196 | * JSON object. | ||
197 | * | ||
198 | * @param name name of the JSON field | ||
199 | * @param[out] jsonp where to store the JSON found under @a name | ||
200 | */ | ||
201 | struct GNUNET_JSON_Specification | ||
202 | GNUNET_JSON_spec_json (const char *name, | ||
203 | json_t **jsonp); | ||
204 | |||
205 | |||
206 | /** | ||
207 | * 8-bit integer. | ||
208 | * | ||
209 | * @param name name of the JSON field | ||
210 | * @param[out] u8 where to store the integer found under @a name | ||
211 | */ | ||
212 | struct GNUNET_JSON_Specification | ||
213 | GNUNET_JSON_spec_uint8 (const char *name, | ||
214 | uint8_t *u8); | ||
215 | |||
216 | |||
217 | /** | ||
218 | * 16-bit integer. | ||
219 | * | ||
220 | * @param name name of the JSON field | ||
221 | * @param[out] u16 where to store the integer found under @a name | ||
222 | */ | ||
223 | struct GNUNET_JSON_Specification | ||
224 | GNUNET_JSON_spec_uint16 (const char *name, | ||
225 | uint16_t *u16); | ||
226 | |||
227 | |||
228 | /** | ||
229 | * 32-bit integer. | ||
230 | * | ||
231 | * @param name name of the JSON field | ||
232 | * @param[out] u32 where to store the integer found under @a name | ||
233 | */ | ||
234 | struct GNUNET_JSON_Specification | ||
235 | GNUNET_JSON_spec_uint32 (const char *name, | ||
236 | uint32_t *u32); | ||
237 | |||
238 | |||
239 | /** | ||
240 | * 64-bit integer. | ||
241 | * | ||
242 | * @param name name of the JSON field | ||
243 | * @param[out] u64 where to store the integer found under @a name | ||
244 | */ | ||
245 | struct GNUNET_JSON_Specification | ||
246 | GNUNET_JSON_spec_uint64 (const char *name, | ||
247 | uint64_t *u64); | ||
248 | |||
249 | |||
250 | /* ************ GNUnet-specific parser specifications ******************* */ | ||
251 | |||
252 | /** | ||
253 | * Absolute time. | ||
254 | * | ||
255 | * @param name name of the JSON field | ||
256 | * @param[out] at where to store the absolute time found under @a name | ||
257 | */ | ||
258 | struct GNUNET_JSON_Specification | ||
259 | GNUNET_JSON_spec_absolute_time (const char *name, | ||
260 | struct GNUNET_TIME_Absolute *at); | ||
261 | |||
262 | |||
263 | /** | ||
264 | * Relative time. | ||
265 | * | ||
266 | * @param name name of the JSON field | ||
267 | * @param[out] rt where to store the relative time found under @a name | ||
268 | */ | ||
269 | struct GNUNET_JSON_Specification | ||
270 | GNUNET_JSON_spec_relative_time (const char *name, | ||
271 | struct GNUNET_TIME_Relative *rt); | ||
272 | |||
273 | |||
274 | /** | ||
275 | * Specification for parsing an RSA public key. | ||
276 | * | ||
277 | * @param name name of the JSON field | ||
278 | * @param pk where to store the RSA key found under @a name | ||
279 | */ | ||
280 | struct GNUNET_JSON_Specification | ||
281 | GNUNET_JSON_spec_rsa_public_key (const char *name, | ||
282 | struct GNUNET_CRYPTO_rsa_PublicKey **pk); | ||
283 | |||
284 | |||
285 | /** | ||
286 | * Specification for parsing an RSA signature. | ||
287 | * | ||
288 | * @param name name of the JSON field | ||
289 | * @param sig where to store the RSA signature found under @a name | ||
290 | */ | ||
291 | struct GNUNET_JSON_Specification | ||
292 | GNUNET_JSON_spec_rsa_signature (const char *name, | ||
293 | struct GNUNET_CRYPTO_rsa_Signature **sig); | ||
294 | |||
295 | |||
296 | /* ****************** Generic generator interface ******************* */ | ||
297 | |||
298 | |||
299 | /** | ||
300 | * Convert binary data to a JSON string with the base32crockford | ||
301 | * encoding. | ||
302 | * | ||
303 | * @param data binary data | ||
304 | * @param size size of @a data in bytes | ||
305 | * @return json string that encodes @a data | ||
306 | */ | ||
307 | json_t * | ||
308 | GNUNET_JSON_from_data (const void *data, | ||
309 | size_t size); | ||
310 | |||
311 | |||
312 | /** | ||
313 | * Convert absolute timestamp to a json string. | ||
314 | * | ||
315 | * @param stamp the time stamp | ||
316 | * @return a json string with the timestamp in @a stamp | ||
317 | */ | ||
318 | json_t * | ||
319 | GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp); | ||
320 | |||
321 | |||
322 | /** | ||
323 | * Convert relative timestamp to a json string. | ||
324 | * | ||
325 | * @param stamp the time stamp | ||
326 | * @return a json string with the timestamp in @a stamp | ||
327 | */ | ||
328 | json_t * | ||
329 | GNUNET_JSON_from_time_rel (struct GNUNET_TIME_Relative stamp); | ||
330 | |||
331 | |||
332 | /** | ||
333 | * Convert RSA public key to JSON. | ||
334 | * | ||
335 | * @param pk public key to convert | ||
336 | * @return corresponding JSON encoding | ||
337 | */ | ||
338 | json_t * | ||
339 | GNUNET_JSON_from_rsa_public_key (const struct GNUNET_CRYPTO_rsa_PublicKey *pk); | ||
340 | |||
341 | |||
342 | /** | ||
343 | * Convert RSA signature to JSON. | ||
344 | * | ||
345 | * @param sig signature to convert | ||
346 | * @return corresponding JSON encoding | ||
347 | */ | ||
348 | json_t * | ||
349 | GNUNET_JSON_from_rsa_signature (const struct GNUNET_CRYPTO_rsa_Signature *sig); | ||
350 | |||
351 | |||
352 | |||
353 | |||
354 | /* end of gnunet_json_lib.h */ | ||