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/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
21 * @file gnunet_json_lib.h
22 * @brief functions to parse JSON objects into GNUnet objects
23 * @author Florian Dold
24 * @author Benedikt Mueller
25 * @author Christian Grothoff
27 #ifndef GNUNET_JSON_LIB_H
28 #define GNUNET_JSON_LIB_H
30 #include "gnunet_util_lib.h"
31 #include "gnunet_gnsrecord_lib.h"
35 /* ****************** Generic parser interface ******************* */
38 * @brief Entry in parser specification for #GNUNET_JSON_parse().
40 struct GNUNET_JSON_Specification;
44 * Function called to parse JSON argument.
47 * @param root JSON to parse
48 * @param spec our specification entry with further details
49 * @return #GNUNET_SYSERR on error,
50 * #GNUNET_OK on success
53 (*GNUNET_JSON_Parser)(void *cls,
55 struct GNUNET_JSON_Specification *spec);
59 * Function called to clean up data from earlier parsing.
62 * @param spec our specification entry with data to clean.
65 (*GNUNET_JSON_Cleaner)(void *cls,
66 struct GNUNET_JSON_Specification *spec);
70 * @brief Entry in parser specification for #GNUNET_JSON_parse().
72 struct GNUNET_JSON_Specification
75 * Function for how to parse this type of entry.
77 GNUNET_JSON_Parser parser;
80 * Function for how to clean up this type of entry.
82 GNUNET_JSON_Cleaner cleaner;
85 * Closure for @e parser and @e cleaner.
90 * Name of the field to parse, use NULL to get the JSON
91 * of the main object instead of the JSON of an individual field.
96 * Pointer, details specific to the @e parser.
101 * Number of bytes available in @e ptr.
106 * Where should we store the final size of @e ptr.
114 * Navigate and parse data in a JSON tree. Tries to parse the @a root
115 * to find all of the values given in the @a spec. If one of the
116 * entries in @a spec cannot be found or parsed, the name of the JSON
117 * field is returned in @a error_json_name, and the offset of the
118 * entry in @a spec is returned in @a error_line.
120 * @param root the JSON node to start the navigation at.
121 * @param spec parse specification array
122 * @param[out] error_json_name which JSON field was problematic
123 * @param[out] which index into @a spec did we encounter an error
124 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
127 GNUNET_JSON_parse (const json_t *root,
128 struct GNUNET_JSON_Specification *spec,
129 const char **error_json_name,
130 unsigned int *error_line);
134 * Frees all elements allocated during a #GNUNET_JSON_parse()
137 * @param spec specification of the parse operation
140 GNUNET_JSON_parse_free (struct GNUNET_JSON_Specification *spec);
144 /* ****************** Canonical parser specifications ******************* */
148 * End of a parser specification.
150 struct GNUNET_JSON_Specification
151 GNUNET_JSON_spec_end (void);
155 * Variable size object (in network byte order, encoded using Crockford
156 * Base32hex encoding).
158 * @param name name of the JSON field
159 * @param[out] obj pointer where to write the data, must have @a size bytes
160 * @param size number of bytes expected in @a obj
162 struct GNUNET_JSON_Specification
163 GNUNET_JSON_spec_fixed (const char *name,
169 * Fixed size object (in network byte order, encoded using Crockford
170 * Base32hex encoding).
172 * @param name name of the JSON field
173 * @param obj pointer where to write the data (type of `*obj` will determine size)
175 #define GNUNET_JSON_spec_fixed_auto(name,obj) GNUNET_JSON_spec_fixed (name, obj, sizeof (*obj))
179 * Variable size object (in network byte order, encoded using
180 * Crockford Base32hex encoding).
182 * @param name name of the JSON field
183 * @param[out] obj pointer where to write the data, will be allocated
184 * @param[out] size where to store the number of bytes allocated for @a obj
186 struct GNUNET_JSON_Specification
187 GNUNET_JSON_spec_varsize (const char *name,
193 * The expected field stores a string.
195 * @param name name of the JSON field
196 * @param strptr where to store a pointer to the field
198 struct GNUNET_JSON_Specification
199 GNUNET_JSON_spec_string (const char *name,
200 const char **strptr);
205 * @param name name of the JSON field
206 * @param[out] jsonp where to store the JSON found under @a name
208 struct GNUNET_JSON_Specification
209 GNUNET_JSON_spec_json (const char *name,
216 * @param name name of the JSON field
217 * @param[out] u8 where to store the integer found under @a name
219 struct GNUNET_JSON_Specification
220 GNUNET_JSON_spec_uint8 (const char *name,
227 * @param name name of the JSON field
228 * @param[out] u16 where to store the integer found under @a name
230 struct GNUNET_JSON_Specification
231 GNUNET_JSON_spec_uint16 (const char *name,
238 * @param name name of the JSON field
239 * @param[out] u32 where to store the integer found under @a name
241 struct GNUNET_JSON_Specification
242 GNUNET_JSON_spec_uint32 (const char *name,
249 * @param name name of the JSON field
250 * @param[out] u64 where to store the integer found under @a name
252 struct GNUNET_JSON_Specification
253 GNUNET_JSON_spec_uint64 (const char *name,
257 * Boolean (true mapped to GNUNET_YES, false mapped to GNUNET_NO).
259 * @param name name of the JSON field
260 * @param[out] boolean where to store the boolean found under @a name
262 struct GNUNET_JSON_Specification
263 GNUNET_JSON_spec_boolean (const char *name,
267 /* ************ GNUnet-specific parser specifications ******************* */
272 * @param name name of the JSON field
273 * @param[out] at where to store the absolute time found under @a name
275 struct GNUNET_JSON_Specification
276 GNUNET_JSON_spec_absolute_time (const char *name,
277 struct GNUNET_TIME_Absolute *at);
281 * Absolute time in network byte order.
283 * @param name name of the JSON field
284 * @param[out] at where to store the absolute time found under @a name
286 struct GNUNET_JSON_Specification
287 GNUNET_JSON_spec_absolute_time_nbo (const char *name,
288 struct GNUNET_TIME_AbsoluteNBO *at);
294 * @param name name of the JSON field
295 * @param[out] rt where to store the relative time found under @a name
297 struct GNUNET_JSON_Specification
298 GNUNET_JSON_spec_relative_time (const char *name,
299 struct GNUNET_TIME_Relative *rt);
303 * Specification for parsing an RSA public key.
305 * @param name name of the JSON field
306 * @param pk where to store the RSA key found under @a name
308 struct GNUNET_JSON_Specification
309 GNUNET_JSON_spec_rsa_public_key (const char *name,
310 struct GNUNET_CRYPTO_RsaPublicKey **pk);
314 * Specification for parsing an RSA signature.
316 * @param name name of the JSON field
317 * @param sig where to store the RSA signature found under @a name
319 struct GNUNET_JSON_Specification
320 GNUNET_JSON_spec_rsa_signature (const char *name,
321 struct GNUNET_CRYPTO_RsaSignature **sig);
326 * JSON Specification for GNS Records.
328 * @param gnsrecord_object struct of GNUNET_GNSRECORD_Data to fill
329 * @return JSON Specification
331 struct GNUNET_JSON_Specification
332 GNUNET_JSON_spec_gnsrecord_data (struct GNUNET_GNSRECORD_Data **gnsrecord_object);
335 /* ****************** Generic generator interface ******************* */
339 * Convert binary data to a JSON string with the base32crockford
342 * @param data binary data
343 * @param size size of @a data in bytes
344 * @return json string that encodes @a data
347 GNUNET_JSON_from_data (const void *data,
352 * Convert binary data to a JSON string with the base32crockford
355 * @param ptr binary data, sizeof (*ptr) must yield correct size
356 * @return json string that encodes @a data
358 #define GNUNET_JSON_from_data_auto(ptr) GNUNET_JSON_from_data(ptr, sizeof (*ptr))
362 * Convert absolute timestamp to a json string.
364 * @param stamp the time stamp
365 * @return a json string with the timestamp in @a stamp
368 GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp);
372 * Convert absolute timestamp to a json string.
374 * @param stamp the time stamp
375 * @return a json string with the timestamp in @a stamp
378 GNUNET_JSON_from_time_abs_nbo (struct GNUNET_TIME_AbsoluteNBO stamp);
382 * Convert relative timestamp to a json string.
384 * @param stamp the time stamp
385 * @return a json string with the timestamp in @a stamp
388 GNUNET_JSON_from_time_rel (struct GNUNET_TIME_Relative stamp);
392 * Convert RSA public key to JSON.
394 * @param pk public key to convert
395 * @return corresponding JSON encoding
398 GNUNET_JSON_from_rsa_public_key (const struct GNUNET_CRYPTO_RsaPublicKey *pk);
402 * Convert RSA signature to JSON.
404 * @param sig signature to convert
405 * @return corresponding JSON encoding
408 GNUNET_JSON_from_rsa_signature (const struct GNUNET_CRYPTO_RsaSignature *sig);
411 * Convert Gns record to JSON.
413 * @param rname name of record
414 * @param rd record data
415 * @return corresponding JSON encoding
418 GNUNET_JSON_from_gns_record (const char* rname,
419 const struct GNUNET_GNSRECORD_Data *rd);
421 /* ******************* Helpers for MHD upload handling ******************* */
424 * Return codes from #GNUNET_JSON_post_parser().
426 enum GNUNET_JSON_PostResult {
428 * Parsing successful, JSON result is in `*json`.
430 GNUNET_JSON_PR_SUCCESS,
433 * Parsing continues, call again soon!
435 GNUNET_JSON_PR_CONTINUE,
438 * Sorry, memory allocation (malloc()) failed.
440 GNUNET_JSON_PR_OUT_OF_MEMORY,
443 * Request size exceeded `buffer_max` argument.
445 GNUNET_JSON_PR_REQUEST_TOO_LARGE,
448 * JSON parsing failed. This was not a JSON upload.
450 GNUNET_JSON_PR_JSON_INVALID
455 * Process a POST request containing a JSON object. This function
456 * realizes an MHD POST processor that will (incrementally) process
457 * JSON data uploaded to the HTTP server. It will store the required
458 * state in the @a con_cls, which must be cleaned up using
459 * #GNUNET_JSON_post_parser_callback().
461 * @param buffer_max maximum allowed size for the buffer
462 * @param con_cls the closure (will point to a `struct Buffer *`)
463 * @param upload_data the POST data
464 * @param upload_data_size number of bytes in @a upload_data
465 * @param json the JSON object for a completed request
466 * @return result code indicating the status of the operation
468 enum GNUNET_JSON_PostResult
469 GNUNET_JSON_post_parser (size_t buffer_max,
471 const char *upload_data,
472 size_t *upload_data_size,
477 * Function called whenever we are done with a request
478 * to clean up our state.
480 * @param con_cls value as it was left by
481 * #GNUNET_JSON_post_parser(), to be cleaned up
484 GNUNET_JSON_post_parser_cleanup (void *con_cls);
487 /* ****************** GETOPT JSON helper ******************* */
491 * Allow user to specify a JSON input value.
493 * @param shortName short name of the option
494 * @param name long name of the option
495 * @param argumentHelp help text for the option argument
496 * @param description long help text for the option
497 * @param[out] val set to the JSON specified at the command line
499 struct GNUNET_GETOPT_CommandLineOption
500 GNUNET_JSON_getopt (char shortName,
502 const char *argumentHelp,
503 const char *description,
508 /* end of gnunet_json_lib.h */