2 This file is part of GNUnet
3 Copyright (C) 2014, 2015, 2016 GNUnet e.V.
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.
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.
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/>.
19 * @file gnunet_json_lib.h
20 * @brief functions to parse JSON objects into GNUnet objects
21 * @author Florian Dold
22 * @author Benedikt Mueller
23 * @author Christian Grothoff
25 #ifndef GNUNET_JSON_LIB_H
26 #define GNUNET_JSON_LIB_H
28 #include "gnunet_util_lib.h"
32 /* ****************** Generic parser interface ******************* */
35 * @brief Entry in parser specification for #GNUNET_JSON_parse().
37 struct GNUNET_JSON_Specification;
41 * Function called to parse JSON argument.
44 * @param root JSON to parse
45 * @param spec our specification entry with further details
46 * @return #GNUNET_SYSERR on error,
47 * #GNUNET_OK on success
50 (*GNUNET_JSON_Parser)(void *cls,
52 struct GNUNET_JSON_Specification *spec);
56 * Function called to clean up data from earlier parsing.
59 * @param spec our specification entry with data to clean.
62 (*GNUNET_JSON_Cleaner)(void *cls,
63 struct GNUNET_JSON_Specification *spec);
67 * @brief Entry in parser specification for #GNUNET_JSON_parse().
69 struct GNUNET_JSON_Specification
72 * Function for how to parse this type of entry.
74 GNUNET_JSON_Parser parser;
77 * Function for how to clean up this type of entry.
79 GNUNET_JSON_Cleaner cleaner;
82 * Closure for @e parser and @e cleaner.
87 * Name of the field to parse, use NULL to get the JSON
88 * of the main object instead of the JSON of an individual field.
93 * Pointer, details specific to the @e parser.
98 * Number of bytes available in @e ptr.
103 * Where should we store the final size of @e ptr.
111 * Navigate and parse data in a JSON tree. Tries to parse the @a root
112 * to find all of the values given in the @a spec. If one of the
113 * entries in @a spec cannot be found or parsed, the name of the JSON
114 * field is returned in @a error_json_name, and the offset of the
115 * entry in @a spec is returned in @a error_line.
117 * @param root the JSON node to start the navigation at.
118 * @param spec parse specification array
119 * @param[out] error_json_name which JSON field was problematic
120 * @param[out] which index into @a spec did we encounter an error
121 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
124 GNUNET_JSON_parse (const json_t *root,
125 struct GNUNET_JSON_Specification *spec,
126 const char **error_json_name,
127 unsigned int *error_line);
131 * Frees all elements allocated during a #GNUNET_JSON_parse()
134 * @param spec specification of the parse operation
137 GNUNET_JSON_parse_free (struct GNUNET_JSON_Specification *spec);
141 /* ****************** Canonical parser specifications ******************* */
145 * End of a parser specification.
147 struct GNUNET_JSON_Specification
148 GNUNET_JSON_spec_end (void);
152 * Variable size object (in network byte order, encoded using Crockford
153 * Base32hex encoding).
155 * @param name name of the JSON field
156 * @param[out] obj pointer where to write the data, must have @a size bytes
157 * @param size number of bytes expected in @a obj
159 struct GNUNET_JSON_Specification
160 GNUNET_JSON_spec_fixed (const char *name,
166 * Fixed size object (in network byte order, encoded using Crockford
167 * Base32hex encoding).
169 * @param name name of the JSON field
170 * @param obj pointer where to write the data (type of `*obj` will determine size)
172 #define GNUNET_JSON_spec_fixed_auto(name,obj) GNUNET_JSON_spec_fixed (name, obj, sizeof (*obj))
176 * Variable size object (in network byte order, encoded using
177 * Crockford Base32hex encoding).
179 * @param name name of the JSON field
180 * @param[out] obj pointer where to write the data, will be allocated
181 * @param[out] size where to store the number of bytes allocated for @a obj
183 struct GNUNET_JSON_Specification
184 GNUNET_JSON_spec_varsize (const char *name,
190 * The expected field stores a string.
192 * @param name name of the JSON field
193 * @param strptr where to store a pointer to the field
195 struct GNUNET_JSON_Specification
196 GNUNET_JSON_spec_string (const char *name,
197 const char **strptr);
202 * @param name name of the JSON field
203 * @param[out] jsonp where to store the JSON found under @a name
205 struct GNUNET_JSON_Specification
206 GNUNET_JSON_spec_json (const char *name,
213 * @param name name of the JSON field
214 * @param[out] u8 where to store the integer found under @a name
216 struct GNUNET_JSON_Specification
217 GNUNET_JSON_spec_uint8 (const char *name,
224 * @param name name of the JSON field
225 * @param[out] u16 where to store the integer found under @a name
227 struct GNUNET_JSON_Specification
228 GNUNET_JSON_spec_uint16 (const char *name,
235 * @param name name of the JSON field
236 * @param[out] u32 where to store the integer found under @a name
238 struct GNUNET_JSON_Specification
239 GNUNET_JSON_spec_uint32 (const char *name,
246 * @param name name of the JSON field
247 * @param[out] u64 where to store the integer found under @a name
249 struct GNUNET_JSON_Specification
250 GNUNET_JSON_spec_uint64 (const char *name,
254 * Boolean (true mapped to GNUNET_YES, false mapped to GNUNET_NO).
256 * @param name name of the JSON field
257 * @param[out] boolean where to store the boolean found under @a name
259 struct GNUNET_JSON_Specification
260 GNUNET_JSON_spec_boolean (const char *name,
264 /* ************ GNUnet-specific parser specifications ******************* */
269 * @param name name of the JSON field
270 * @param[out] at where to store the absolute time found under @a name
272 struct GNUNET_JSON_Specification
273 GNUNET_JSON_spec_absolute_time (const char *name,
274 struct GNUNET_TIME_Absolute *at);
278 * Absolute time in network byte order.
280 * @param name name of the JSON field
281 * @param[out] at where to store the absolute time found under @a name
283 struct GNUNET_JSON_Specification
284 GNUNET_JSON_spec_absolute_time_nbo (const char *name,
285 struct GNUNET_TIME_AbsoluteNBO *at);
291 * @param name name of the JSON field
292 * @param[out] rt where to store the relative time found under @a name
294 struct GNUNET_JSON_Specification
295 GNUNET_JSON_spec_relative_time (const char *name,
296 struct GNUNET_TIME_Relative *rt);
300 * Specification for parsing an RSA public key.
302 * @param name name of the JSON field
303 * @param pk where to store the RSA key found under @a name
305 struct GNUNET_JSON_Specification
306 GNUNET_JSON_spec_rsa_public_key (const char *name,
307 struct GNUNET_CRYPTO_RsaPublicKey **pk);
311 * Specification for parsing an RSA signature.
313 * @param name name of the JSON field
314 * @param sig where to store the RSA signature found under @a name
316 struct GNUNET_JSON_Specification
317 GNUNET_JSON_spec_rsa_signature (const char *name,
318 struct GNUNET_CRYPTO_RsaSignature **sig);
321 /* ****************** Generic generator interface ******************* */
325 * Convert binary data to a JSON string with the base32crockford
328 * @param data binary data
329 * @param size size of @a data in bytes
330 * @return json string that encodes @a data
333 GNUNET_JSON_from_data (const void *data,
338 * Convert binary data to a JSON string with the base32crockford
341 * @param ptr binary data, sizeof (*ptr) must yield correct size
342 * @return json string that encodes @a data
344 #define GNUNET_JSON_from_data_auto(ptr) GNUNET_JSON_from_data(ptr, sizeof (*ptr))
348 * Convert absolute timestamp to a json string.
350 * @param stamp the time stamp
351 * @return a json string with the timestamp in @a stamp
354 GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp);
358 * Convert absolute timestamp to a json string.
360 * @param stamp the time stamp
361 * @return a json string with the timestamp in @a stamp
364 GNUNET_JSON_from_time_abs_nbo (struct GNUNET_TIME_AbsoluteNBO stamp);
368 * Convert relative timestamp to a json string.
370 * @param stamp the time stamp
371 * @return a json string with the timestamp in @a stamp
374 GNUNET_JSON_from_time_rel (struct GNUNET_TIME_Relative stamp);
378 * Convert RSA public key to JSON.
380 * @param pk public key to convert
381 * @return corresponding JSON encoding
384 GNUNET_JSON_from_rsa_public_key (const struct GNUNET_CRYPTO_RsaPublicKey *pk);
388 * Convert RSA signature to JSON.
390 * @param sig signature to convert
391 * @return corresponding JSON encoding
394 GNUNET_JSON_from_rsa_signature (const struct GNUNET_CRYPTO_RsaSignature *sig);
397 /* ******************* Helpers for MHD upload handling ******************* */
400 * Return codes from #GNUNET_JSON_post_parser().
402 enum GNUNET_JSON_PostResult {
404 * Parsing successful, JSON result is in `*json`.
406 GNUNET_JSON_PR_SUCCESS,
409 * Parsing continues, call again soon!
411 GNUNET_JSON_PR_CONTINUE,
414 * Sorry, memory allocation (malloc()) failed.
416 GNUNET_JSON_PR_OUT_OF_MEMORY,
419 * Request size exceeded `buffer_max` argument.
421 GNUNET_JSON_PR_REQUEST_TOO_LARGE,
424 * JSON parsing failed. This was not a JSON upload.
426 GNUNET_JSON_PR_JSON_INVALID
431 * Process a POST request containing a JSON object. This function
432 * realizes an MHD POST processor that will (incrementally) process
433 * JSON data uploaded to the HTTP server. It will store the required
434 * state in the @a con_cls, which must be cleaned up using
435 * #GNUNET_JSON_post_parser_callback().
437 * @param buffer_max maximum allowed size for the buffer
438 * @param con_cls the closure (will point to a `struct Buffer *`)
439 * @param upload_data the POST data
440 * @param upload_data_size number of bytes in @a upload_data
441 * @param json the JSON object for a completed request
442 * @return result code indicating the status of the operation
444 enum GNUNET_JSON_PostResult
445 GNUNET_JSON_post_parser (size_t buffer_max,
447 const char *upload_data,
448 size_t *upload_data_size,
453 * Function called whenever we are done with a request
454 * to clean up our state.
456 * @param con_cls value as it was left by
457 * #GNUNET_JSON_post_parser(), to be cleaned up
460 GNUNET_JSON_post_parser_cleanup (void *con_cls);
463 /* ****************** GETOPT JSON helper ******************* */
467 * Allow user to specify a JSON input value.
469 * @param shortName short name of the option
470 * @param name long name of the option
471 * @param argumentHelp help text for the option argument
472 * @param description long help text for the option
473 * @param[out] val set to the JSON specified at the command line
475 struct GNUNET_GETOPT_CommandLineOption
476 GNUNET_JSON_getopt (char shortName,
478 const char *argumentHelp,
479 const char *description,
485 /* end of gnunet_json_lib.h */