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 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.
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.
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/>
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
23 #ifndef GNUNET_JSON_LIB_H
24 #define GNUNET_JSON_LIB_H
26 #include "gnunet_util_lib.h"
30 /* ****************** Generic parser interface ******************* */
33 * @brief Entry in parser specification for #GNUNET_JSON_parse().
35 struct GNUNET_JSON_Specification;
39 * Function called to parse JSON argument.
42 * @param root JSON to parse
43 * @param spec our specification entry with further details
44 * @return #GNUNET_SYSERR on error,
45 * #GNUNET_OK on success
48 (*GNUNET_JSON_Parser)(void *cls,
50 struct GNUNET_JSON_Specification *spec);
54 * Function called to clean up data from earlier parsing.
57 * @param spec our specification entry with data to clean.
60 (*GNUNET_JSON_Cleaner)(void *cls,
61 struct GNUNET_JSON_Specification *spec);
65 * @brief Entry in parser specification for #GNUNET_JSON_parse().
67 struct GNUNET_JSON_Specification
70 * Function for how to parse this type of entry.
72 GNUNET_JSON_Parser parser;
75 * Function for how to clean up this type of entry.
77 GNUNET_JSON_Cleaner cleaner;
80 * Closure for @e parser and @e cleaner.
85 * Name of the field to parse, use NULL to get the JSON
86 * of the main object instead of the JSON of an individual field.
91 * Pointer, details specific to the @e parser.
96 * Number of bytes available in @e ptr.
101 * Where should we store the final size of @e ptr.
109 * Navigate and parse data in a JSON tree. Tries to parse the @a root
110 * to find all of the values given in the @a spec. If one of the
111 * entries in @a spec cannot be found or parsed, the name of the JSON
112 * field is returned in @a error_json_name, and the offset of the
113 * entry in @a spec is returned in @a error_line.
115 * @param root the JSON node to start the navigation at.
116 * @param spec parse specification array
117 * @param[out] error_json_name which JSON field was problematic
118 * @param[out] which index into @a spec did we encounter an error
119 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
122 GNUNET_JSON_parse (const json_t *root,
123 struct GNUNET_JSON_Specification *spec,
124 const char **error_json_name,
125 unsigned int *error_line);
129 * Frees all elements allocated during a #GNUNET_JSON_parse()
132 * @param spec specification of the parse operation
135 GNUNET_JSON_parse_free (struct GNUNET_JSON_Specification *spec);
139 /* ****************** Canonical parser specifications ******************* */
143 * End of a parser specification.
145 struct GNUNET_JSON_Specification
146 GNUNET_JSON_spec_end (void);
150 * Variable size object (in network byte order, encoded using Crockford
151 * Base32hex encoding).
153 * @param name name of the JSON field
154 * @param[out] obj pointer where to write the data, must have @a size bytes
155 * @param size number of bytes expected in @a obj
157 struct GNUNET_JSON_Specification
158 GNUNET_JSON_spec_fixed (const char *name,
164 * Fixed size object (in network byte order, encoded using Crockford
165 * Base32hex encoding).
167 * @param name name of the JSON field
168 * @param obj pointer where to write the data (type of `*obj` will determine size)
170 #define GNUNET_JSON_spec_fixed_auto(name,obj) GNUNET_JSON_spec_fixed (name, obj, sizeof (*obj))
174 * Variable size object (in network byte order, encoded using
175 * Crockford Base32hex encoding).
177 * @param name name of the JSON field
178 * @param[out] obj pointer where to write the data, will be allocated
179 * @param[out] size where to store the number of bytes allocated for @a obj
181 struct GNUNET_JSON_Specification
182 GNUNET_JSON_spec_varsize (const char *name,
188 * The expected field stores a string.
190 * @param name name of the JSON field
191 * @param strptr where to store a pointer to the field
193 struct GNUNET_JSON_Specification
194 GNUNET_JSON_spec_string (const char *name,
195 const char **strptr);
200 * @param name name of the JSON field
201 * @param[out] jsonp where to store the JSON found under @a name
203 struct GNUNET_JSON_Specification
204 GNUNET_JSON_spec_json (const char *name,
211 * @param name name of the JSON field
212 * @param[out] u8 where to store the integer found under @a name
214 struct GNUNET_JSON_Specification
215 GNUNET_JSON_spec_uint8 (const char *name,
222 * @param name name of the JSON field
223 * @param[out] u16 where to store the integer found under @a name
225 struct GNUNET_JSON_Specification
226 GNUNET_JSON_spec_uint16 (const char *name,
233 * @param name name of the JSON field
234 * @param[out] u32 where to store the integer found under @a name
236 struct GNUNET_JSON_Specification
237 GNUNET_JSON_spec_uint32 (const char *name,
244 * @param name name of the JSON field
245 * @param[out] u64 where to store the integer found under @a name
247 struct GNUNET_JSON_Specification
248 GNUNET_JSON_spec_uint64 (const char *name,
252 /* ************ GNUnet-specific parser specifications ******************* */
257 * @param name name of the JSON field
258 * @param[out] at where to store the absolute time found under @a name
260 struct GNUNET_JSON_Specification
261 GNUNET_JSON_spec_absolute_time (const char *name,
262 struct GNUNET_TIME_Absolute *at);
268 * @param name name of the JSON field
269 * @param[out] rt where to store the relative time found under @a name
271 struct GNUNET_JSON_Specification
272 GNUNET_JSON_spec_relative_time (const char *name,
273 struct GNUNET_TIME_Relative *rt);
277 * Specification for parsing an RSA public key.
279 * @param name name of the JSON field
280 * @param pk where to store the RSA key found under @a name
282 struct GNUNET_JSON_Specification
283 GNUNET_JSON_spec_rsa_public_key (const char *name,
284 struct GNUNET_CRYPTO_RsaPublicKey **pk);
288 * Specification for parsing an RSA signature.
290 * @param name name of the JSON field
291 * @param sig where to store the RSA signature found under @a name
293 struct GNUNET_JSON_Specification
294 GNUNET_JSON_spec_rsa_signature (const char *name,
295 struct GNUNET_CRYPTO_RsaSignature **sig);
298 /* ****************** Generic generator interface ******************* */
302 * Convert binary data to a JSON string with the base32crockford
305 * @param data binary data
306 * @param size size of @a data in bytes
307 * @return json string that encodes @a data
310 GNUNET_JSON_from_data (const void *data,
315 * Convert binary data to a JSON string with the base32crockford
318 * @param ptr binary data, sizeof (*ptr) must yield correct size
319 * @return json string that encodes @a data
321 #define GNUNET_JSON_from_data_auto(ptr) GNUNET_JSON_from_data(ptr, sizeof (*ptr))
325 * Convert absolute timestamp to a json string.
327 * @param stamp the time stamp
328 * @return a json string with the timestamp in @a stamp
331 GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp);
335 * Convert relative timestamp to a json string.
337 * @param stamp the time stamp
338 * @return a json string with the timestamp in @a stamp
341 GNUNET_JSON_from_time_rel (struct GNUNET_TIME_Relative stamp);
345 * Convert RSA public key to JSON.
347 * @param pk public key to convert
348 * @return corresponding JSON encoding
351 GNUNET_JSON_from_rsa_public_key (const struct GNUNET_CRYPTO_RsaPublicKey *pk);
355 * Convert RSA signature to JSON.
357 * @param sig signature to convert
358 * @return corresponding JSON encoding
361 GNUNET_JSON_from_rsa_signature (const struct GNUNET_CRYPTO_RsaSignature *sig);
364 /* ******************* Helpers for MHD upload handling ******************* */
367 * Return codes from #GNUNET_JSON_post_parser().
369 enum GNUNET_JSON_PostResult {
371 * Parsing successful, JSON result is in `*json`.
373 GNUNET_JSON_PR_SUCCESS,
376 * Parsing continues, call again soon!
378 GNUNET_JSON_PR_CONTINUE,
381 * Sorry, memory allocation (malloc()) failed.
383 GNUNET_JSON_PR_OUT_OF_MEMORY,
386 * Request size exceeded `buffer_max` argument.
388 GNUNET_JSON_PR_REQUEST_TOO_LARGE,
391 * JSON parsing failed. This was not a JSON upload.
393 GNUNET_JSON_PR_JSON_INVALID
398 * Process a POST request containing a JSON object. This function
399 * realizes an MHD POST processor that will (incrementally) process
400 * JSON data uploaded to the HTTP server. It will store the required
401 * state in the @a con_cls, which must be cleaned up using
402 * #GNUNET_JSON_post_parser_callback().
404 * @param buffer_max maximum allowed size for the buffer
405 * @param con_cls the closure (will point to a `struct Buffer *`)
406 * @param upload_data the POST data
407 * @param upload_data_size number of bytes in @a upload_data
408 * @param json the JSON object for a completed request
409 * @return result code indicating the status of the operation
411 enum GNUNET_JSON_PostResult
412 GNUNET_JSON_post_parser (size_t buffer_max,
414 const char *upload_data,
415 size_t *upload_data_size,
420 * Function called whenever we are done with a request
421 * to clean up our state.
423 * @param con_cls value as it was left by
424 * #GNUNET_JSON_post_parser(), to be cleaned up
427 GNUNET_JSON_post_parser_cleanup (void *con_cls);
432 /* end of gnunet_json_lib.h */