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
24 #include <gnunet/gnunet_util_lib.h>
28 /* ****************** Generic parser interface ******************* */
31 * @brief Entry in parser specification for #GNUNET_JSON_parse().
33 struct GNUNET_JSON_Specification;
37 * Function called to parse JSON argument.
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
46 (*GNUNET_JSON_Parser)(void *cls,
48 struct GNUNET_JSON_Specification *spec);
52 * Function called to clean up data from earlier parsing.
55 * @param spec our specification entry with data to clean.
58 (*GNUNET_JSON_Cleaner)(void *cls,
59 struct GNUNET_JSON_Specification *spec);
63 * @brief Entry in parser specification for #GNUNET_JSON_parse().
65 struct GNUNET_JSON_Specification
68 * Function for how to parse this type of entry.
70 GNUNET_JSON_Parser parser;
73 * Function for how to clean up this type of entry.
75 GNUNET_JSON_Cleaner cleaner;
78 * Closure for @e parser and @e cleaner.
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.
89 * Pointer, details specific to the @e parser.
94 * Number of bytes available in @e ptr.
99 * Where should we store the final size of @e ptr.
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.
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
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);
127 * Frees all elements allocated during a #GNUNET_JSON_parse()
130 * @param spec specification of the parse operation
133 GNUNET_JSON_parse_free (struct GNUNET_JSON_Specification *spec);
137 /* ****************** Canonical parser specifications ******************* */
141 * End of a parser specification.
143 struct GNUNET_JSON_Specification
144 GNUNET_JSON_spec_end (void);
148 * Variable size object (in network byte order, encoded using Crockford
149 * Base32hex encoding).
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
155 struct GNUNET_JSON_Specification
156 GNUNET_JSON_spec_fixed (const char *name,
162 * Fixed size object (in network byte order, encoded using Crockford
163 * Base32hex encoding).
165 * @param name name of the JSON field
166 * @param obj pointer where to write the data (type of `*obj` will determine size)
168 #define GNUNET_JSON_spec_fixed_auto(name,obj) GNUNET_JSON_spec_fixed (name, obj, sizeof (*obj))
172 * Variable size object (in network byte order, encoded using
173 * Crockford Base32hex encoding).
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
179 struct GNUNET_JSON_Specification
180 GNUNET_JSON_spec_varsize (const char *name,
186 * The expected field stores a string.
188 * @param name name of the JSON field
189 * @param strptr where to store a pointer to the field
191 struct GNUNET_JSON_Specification
192 GNUNET_JSON_spec_string (const char *name,
193 const char **strptr);
198 * @param name name of the JSON field
199 * @param[out] jsonp where to store the JSON found under @a name
201 struct GNUNET_JSON_Specification
202 GNUNET_JSON_spec_json (const char *name,
209 * @param name name of the JSON field
210 * @param[out] u8 where to store the integer found under @a name
212 struct GNUNET_JSON_Specification
213 GNUNET_JSON_spec_uint8 (const char *name,
220 * @param name name of the JSON field
221 * @param[out] u16 where to store the integer found under @a name
223 struct GNUNET_JSON_Specification
224 GNUNET_JSON_spec_uint16 (const char *name,
231 * @param name name of the JSON field
232 * @param[out] u32 where to store the integer found under @a name
234 struct GNUNET_JSON_Specification
235 GNUNET_JSON_spec_uint32 (const char *name,
242 * @param name name of the JSON field
243 * @param[out] u64 where to store the integer found under @a name
245 struct GNUNET_JSON_Specification
246 GNUNET_JSON_spec_uint64 (const char *name,
250 /* ************ GNUnet-specific parser specifications ******************* */
255 * @param name name of the JSON field
256 * @param[out] at where to store the absolute time found under @a name
258 struct GNUNET_JSON_Specification
259 GNUNET_JSON_spec_absolute_time (const char *name,
260 struct GNUNET_TIME_Absolute *at);
266 * @param name name of the JSON field
267 * @param[out] rt where to store the relative time found under @a name
269 struct GNUNET_JSON_Specification
270 GNUNET_JSON_spec_relative_time (const char *name,
271 struct GNUNET_TIME_Relative *rt);
275 * Specification for parsing an RSA public key.
277 * @param name name of the JSON field
278 * @param pk where to store the RSA key found under @a name
280 struct GNUNET_JSON_Specification
281 GNUNET_JSON_spec_rsa_public_key (const char *name,
282 struct GNUNET_CRYPTO_rsa_PublicKey **pk);
286 * Specification for parsing an RSA signature.
288 * @param name name of the JSON field
289 * @param sig where to store the RSA signature found under @a name
291 struct GNUNET_JSON_Specification
292 GNUNET_JSON_spec_rsa_signature (const char *name,
293 struct GNUNET_CRYPTO_rsa_Signature **sig);
296 /* ****************** Generic generator interface ******************* */
300 * Convert binary data to a JSON string with the base32crockford
303 * @param data binary data
304 * @param size size of @a data in bytes
305 * @return json string that encodes @a data
308 GNUNET_JSON_from_data (const void *data,
313 * Convert absolute timestamp to a json string.
315 * @param stamp the time stamp
316 * @return a json string with the timestamp in @a stamp
319 GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp);
323 * Convert relative timestamp to a json string.
325 * @param stamp the time stamp
326 * @return a json string with the timestamp in @a stamp
329 GNUNET_JSON_from_time_rel (struct GNUNET_TIME_Relative stamp);
333 * Convert RSA public key to JSON.
335 * @param pk public key to convert
336 * @return corresponding JSON encoding
339 GNUNET_JSON_from_rsa_public_key (const struct GNUNET_CRYPTO_rsa_PublicKey *pk);
343 * Convert RSA signature to JSON.
345 * @param sig signature to convert
346 * @return corresponding JSON encoding
349 GNUNET_JSON_from_rsa_signature (const struct GNUNET_CRYPTO_rsa_Signature *sig);
354 /* end of gnunet_json_lib.h */