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_rsa_PublicKey **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_rsa_Signature **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 absolute timestamp to a json string.
317 * @param stamp the time stamp
318 * @return a json string with the timestamp in @a stamp
321 GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp);
325 * Convert relative 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_rel (struct GNUNET_TIME_Relative stamp);
335 * Convert RSA public key to JSON.
337 * @param pk public key to convert
338 * @return corresponding JSON encoding
341 GNUNET_JSON_from_rsa_public_key (const struct GNUNET_CRYPTO_rsa_PublicKey *pk);
345 * Convert RSA signature to JSON.
347 * @param sig signature to convert
348 * @return corresponding JSON encoding
351 GNUNET_JSON_from_rsa_signature (const struct GNUNET_CRYPTO_rsa_Signature *sig);
356 /* end of gnunet_json_lib.h */