GNUnet  0.11.x
gnunet_json_lib.h
Go to the documentation of this file.
1 /*
2  This file is part of GNUnet
3  Copyright (C) 2014, 2015, 2016, 2020 GNUnet e.V.
4 
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.
9 
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.
14 
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/>.
17 
18  SPDX-License-Identifier: AGPL3.0-or-later
19  */
27 #ifndef GNUNET_JSON_LIB_H
28 #define GNUNET_JSON_LIB_H
29 
30 #include "gnunet_util_lib.h"
31 #include <jansson.h>
32 #include <microhttpd.h>
33 
34 /* ****************** Generic parser interface ******************* */
35 
40 
41 
51 typedef int
52 (*GNUNET_JSON_Parser) (void *cls,
53  json_t *root,
54  struct GNUNET_JSON_Specification *spec);
55 
56 
63 typedef void
64 (*GNUNET_JSON_Cleaner) (void *cls,
65  struct GNUNET_JSON_Specification *spec);
66 
67 
72 {
77 
82 
86  void *cls;
87 
92  const char *field;
93 
97  void *ptr;
98 
102  size_t ptr_size;
103 
107  size_t *size_ptr;
108 
113 };
114 
115 
130 GNUNET_JSON_parse (const json_t *root,
131  struct GNUNET_JSON_Specification *spec,
132  const char **error_json_name,
133  unsigned int *error_line);
134 
135 
142 void
144 
145 
146 /* ****************** Canonical parser specifications ******************* */
147 
148 
153 GNUNET_JSON_spec_end (void);
154 
155 
164 
165 
175 GNUNET_JSON_spec_fixed (const char *name,
176  void *obj,
177  size_t size);
178 
179 
187 #define GNUNET_JSON_spec_fixed_auto(name, obj) \
188  GNUNET_JSON_spec_fixed (name, obj, sizeof(*obj))
189 
190 
200 GNUNET_JSON_spec_varsize (const char *name,
201  void **obj,
202  size_t *size);
203 
204 
212 GNUNET_JSON_spec_string (const char *name,
213  const char **strptr);
214 
215 
223 GNUNET_JSON_spec_json (const char *name,
224  json_t **jsonp);
225 
226 
234 GNUNET_JSON_spec_bool (const char *name,
235  bool *b);
236 
237 
245 GNUNET_JSON_spec_uint8 (const char *name,
246  uint8_t *u8);
247 
248 
256 GNUNET_JSON_spec_uint16 (const char *name,
257  uint16_t *u16);
258 
259 
267 GNUNET_JSON_spec_uint32 (const char *name,
268  uint32_t *u32);
269 
270 
278 GNUNET_JSON_spec_uint64 (const char *name,
279  uint64_t *u64);
280 
281 
289 GNUNET_JSON_spec_int64 (const char *name,
290  int64_t *i64);
291 
292 
300 GNUNET_JSON_spec_boolean (const char *name,
301  int *boolean);
302 
303 
304 /* ************ GNUnet-specific parser specifications ******************* */
305 
314  struct GNUNET_TIME_Absolute *at);
315 
316 
325  struct GNUNET_TIME_AbsoluteNBO *at);
326 
327 
336  struct GNUNET_TIME_Relative *rt);
337 
338 
347  struct GNUNET_CRYPTO_RsaPublicKey **pk);
348 
349 
358  struct GNUNET_CRYPTO_RsaSignature **sig);
359 
360 
361 /* ****************** Generic generator interface ******************* */
362 
363 
372 json_t *
373 GNUNET_JSON_from_data (const void *data, size_t size);
374 
375 
383 #define GNUNET_JSON_from_data_auto(ptr) \
384  GNUNET_JSON_from_data (ptr, sizeof(*ptr))
385 
386 
393 json_t *
395 
396 
403 json_t *
405 
406 
413 json_t *
415 
416 
423 json_t *
425 
426 
433 json_t *
435 
436 /* ******************* Helpers for MHD upload handling ******************* */
437 
442 {
447 
452 
457 
462 
467 };
468 
469 
486 GNUNET_JSON_post_parser (size_t buffer_max,
487  struct MHD_Connection *connection,
488  void **con_cls,
489  const char *upload_data,
490  size_t *upload_data_size,
491  json_t **json);
492 
493 
501 void
502 GNUNET_JSON_post_parser_cleanup (void *con_cls);
503 
504 
505 /* ****************** GETOPT JSON helper ******************* */
506 
507 
519  const char *name,
520  const char *argumentHelp,
521  const char *description,
522  json_t **json);
523 
524 
525 /* ****************** JSON PACK helper ******************* */
526 
527 
531 struct GNUNET_JSON_PackSpec;
532 
533 
541 typedef json_t *
542 (*GNUNET_JSON_PackCallback)(const struct GNUNET_JSON_PackSpec *se);
543 
544 
549 {
553  const char *field_name;
554 
558  json_t *object;
559 
567 };
568 
569 
577 json_t *
579 
580 
588 #define GNUNET_JSON_PACK(...) \
589  GNUNET_JSON_pack_ ((struct GNUNET_JSON_PackSpec[]) {__VA_ARGS__, \
590  GNUNET_JSON_pack_end_ ()})
591 
592 
599 GNUNET_JSON_pack_end_ (void);
600 
601 
610 
611 
621 GNUNET_JSON_pack_bool (const char *name,
622  bool b);
623 
624 
634 GNUNET_JSON_pack_string (const char *name,
635  const char *s);
636 
637 
648 GNUNET_JSON_pack_uint64 (const char *name,
649  uint64_t num);
650 
651 
661 GNUNET_JSON_pack_int64 (const char *name,
662  int64_t num);
663 
664 
676  json_t *o);
677 
678 
690  json_t *o);
691 
692 
704  json_t *a);
705 
706 
718  json_t *a);
719 
720 
732  const void *blob,
733  size_t blob_size);
734 
735 
744 #define GNUNET_JSON_pack_data_auto(name,blob) \
745  GNUNET_JSON_pack_data_varsize (name, blob, sizeof (*blob))
746 
747 
758 GNUNET_JSON_pack_time_abs (const char *name,
759  struct GNUNET_TIME_Absolute at);
760 
761 
773  struct GNUNET_TIME_AbsoluteNBO at);
774 
775 
785 GNUNET_JSON_pack_time_rel (const char *name,
786  struct GNUNET_TIME_Relative rt);
787 
788 
799  struct GNUNET_TIME_RelativeNBO rt);
800 
801 
812  const struct GNUNET_CRYPTO_RsaPublicKey *pk);
813 
814 
825  const struct GNUNET_CRYPTO_RsaSignature *sig);
826 
827 
828 #endif
829 
830 /* end of gnunet_json_lib.h */
uint32_t data
The data value.
struct GNUNET_IDENTITY_PrivateKey pk
Private key from command line option, or NULL.
GNUNET_GenericReturnValue
Named constants for return values.
Definition: gnunet_common.h:92
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_time_rel(const char *name, struct GNUNET_TIME_Relative rt)
Generate packer instruction for a JSON field of type relative time.
Definition: json_pack.c:278
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_end_(void)
Do not use directly.
Definition: json_pack.c:58
struct GNUNET_JSON_Specification GNUNET_JSON_spec_varsize(const char *name, void **obj, size_t *size)
Variable size object (in network byte order, encoded using Crockford Base32hex encoding).
Definition: json_helper.c:162
struct GNUNET_JSON_Specification GNUNET_JSON_spec_fixed(const char *name, void *obj, size_t size)
Variable size object (in network byte order, encoded using Crockford Base32hex encoding).
Definition: json_helper.c:85
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_array_steal(const char *name, json_t *a)
Generate packer instruction for a JSON field of type JSON array where the reference is taken over by ...
Definition: json_pack.c:186
void GNUNET_JSON_parse_free(struct GNUNET_JSON_Specification *spec)
Frees all elements allocated during a GNUNET_JSON_parse() operation.
Definition: json.c:86
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_data_varsize(const char *name, const void *blob, size_t blob_size)
Generate packer instruction for a JSON field of type variable size binary blob.
Definition: json_pack.c:231
struct GNUNET_JSON_Specification GNUNET_JSON_spec_json(const char *name, json_t **jsonp)
JSON object.
Definition: json_helper.c:273
json_t * GNUNET_JSON_from_time_rel(struct GNUNET_TIME_Relative stamp)
Convert relative timestamp to a json string.
void(* GNUNET_JSON_Cleaner)(void *cls, struct GNUNET_JSON_Specification *spec)
Function called to clean up data from earlier parsing.
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_bool(const char *name, bool b)
Generate packer instruction for a JSON field of type bool.
Definition: json_pack.c:77
struct GNUNET_JSON_Specification GNUNET_JSON_spec_boolean(const char *name, int *boolean)
Boolean (true mapped to GNUNET_YES, false mapped to GNUNET_NO).
Definition: json_helper.c:976
struct GNUNET_JSON_Specification GNUNET_JSON_spec_rsa_public_key(const char *name, struct GNUNET_CRYPTO_RsaPublicKey **pk)
Specification for parsing an RSA public key.
Definition: json_helper.c:844
struct GNUNET_JSON_Specification GNUNET_JSON_spec_absolute_time_nbo(const char *name, struct GNUNET_TIME_AbsoluteNBO *at)
Absolute time in network byte order.
Definition: json_helper.c:686
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint16(const char *name, uint16_t *u16)
16-bit integer.
Definition: json_helper.c:422
json_t * GNUNET_JSON_from_time_abs(struct GNUNET_TIME_Absolute stamp)
Convert absolute timestamp to a json string.
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_object_steal(const char *name, json_t *o)
Generate packer instruction for a JSON field of type JSON object where the reference is taken over by...
Definition: json_pack.c:141
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_array_incref(const char *name, json_t *a)
Generate packer instruction for a JSON field of type JSON array where the reference counter is increm...
Definition: json_pack.c:208
json_t * GNUNET_JSON_from_rsa_signature(const struct GNUNET_CRYPTO_RsaSignature *sig)
Convert RSA signature to JSON.
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_allow_null(struct GNUNET_JSON_PackSpec in)
Modify packer instruction to allow NULL as a value.
Definition: json_pack.c:69
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_time_abs(const char *name, struct GNUNET_TIME_Absolute at)
Generate packer instruction for a JSON field of type absolute time.
Definition: json_pack.c:248
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint32(const char *name, uint32_t *u32)
32-bit integer.
Definition: json_helper.c:472
GNUNET_JSON_PostResult
Return codes from GNUNET_JSON_post_parser().
@ GNUNET_JSON_PR_CONTINUE
Parsing continues, call again soon!
@ GNUNET_JSON_PR_OUT_OF_MEMORY
Sorry, memory allocation (malloc()) failed.
@ GNUNET_JSON_PR_JSON_INVALID
JSON parsing failed.
@ GNUNET_JSON_PR_REQUEST_TOO_LARGE
Request size exceeded buffer_max argument.
@ GNUNET_JSON_PR_SUCCESS
Parsing successful, JSON result is in *json.
struct GNUNET_JSON_Specification GNUNET_JSON_spec_string(const char *name, const char **strptr)
The expected field stores a string.
Definition: json_helper.c:210
struct GNUNET_JSON_Specification GNUNET_JSON_spec_mark_optional(struct GNUNET_JSON_Specification spec)
Set the "optional" flag for a parser specification entry.
Definition: json.c:76
json_t * GNUNET_JSON_from_rsa_public_key(const struct GNUNET_CRYPTO_RsaPublicKey *pk)
Convert RSA public key to JSON.
struct GNUNET_JSON_Specification GNUNET_JSON_spec_int64(const char *name, int64_t *i64)
64-bit signed integer.
Definition: json_helper.c:562
struct GNUNET_JSON_Specification GNUNET_JSON_spec_rsa_signature(const char *name, struct GNUNET_CRYPTO_RsaSignature **sig)
Specification for parsing an RSA signature.
Definition: json_helper.c:932
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_uint64(const char *name, uint64_t num)
Generate packer instruction for a JSON field of type unsigned integer.
Definition: json_pack.c:103
enum GNUNET_JSON_PostResult GNUNET_JSON_post_parser(size_t buffer_max, struct MHD_Connection *connection, void **con_cls, const char *upload_data, size_t *upload_data_size, json_t **json)
Process a POST request containing a JSON object.
Definition: json_mhd.c:265
json_t * GNUNET_JSON_from_data(const void *data, size_t size)
Convert binary data to a JSON string with the base32crockford encoding.
json_t * GNUNET_JSON_pack_(struct GNUNET_JSON_PackSpec spec[])
Pack a JSON object from a spec.
Definition: json_pack.c:30
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_object_incref(const char *name, json_t *o)
Generate packer instruction for a JSON field of type JSON object where the reference counter is incre...
Definition: json_pack.c:163
json_t * GNUNET_JSON_from_time_abs_nbo(struct GNUNET_TIME_AbsoluteNBO stamp)
Convert absolute timestamp to a json string.
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_rsa_signature(const char *name, const struct GNUNET_CRYPTO_RsaSignature *sig)
Generate packer instruction for a JSON field of type RSA signature.
Definition: json_pack.c:313
struct GNUNET_GETOPT_CommandLineOption GNUNET_JSON_getopt(char shortName, const char *name, const char *argumentHelp, const char *description, json_t **json)
Allow user to specify a JSON input value.
Definition: json.c:131
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_rsa_public_key(const char *name, const struct GNUNET_CRYPTO_RsaPublicKey *pk)
Generate packer instruction for a JSON field of type RSA public key.
Definition: json_pack.c:300
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_int64(const char *name, int64_t num)
Generate packer instruction for a JSON field of type signed integer.
Definition: json_pack.c:121
int(* GNUNET_JSON_Parser)(void *cls, json_t *root, struct GNUNET_JSON_Specification *spec)
Function called to parse JSON argument.
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_time_rel_nbo(const char *name, struct GNUNET_TIME_RelativeNBO rt)
Generate packer instruction for a JSON field of type relative time in network byte order.
Definition: json_pack.c:291
struct GNUNET_JSON_Specification GNUNET_JSON_spec_bool(const char *name, bool *b)
boolean.
Definition: json_helper.c:322
struct GNUNET_JSON_Specification GNUNET_JSON_spec_absolute_time(const char *name, struct GNUNET_TIME_Absolute *at)
Absolute time.
Definition: json_helper.c:638
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_time_abs_nbo(const char *name, struct GNUNET_TIME_AbsoluteNBO at)
Generate packer instruction for a JSON field of type absolute time in network byte order.
Definition: json_pack.c:269
void GNUNET_JSON_post_parser_cleanup(void *con_cls)
Function called whenever we are done with a request to clean up our state.
Definition: json_mhd.c:367
struct GNUNET_JSON_Specification GNUNET_JSON_spec_relative_time(const char *name, struct GNUNET_TIME_Relative *rt)
Relative time.
Definition: json_helper.c:757
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint8(const char *name, uint8_t *u8)
8-bit integer.
Definition: json_helper.c:372
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint64(const char *name, uint64_t *u64)
64-bit integer.
Definition: json_helper.c:517
enum GNUNET_GenericReturnValue GNUNET_JSON_parse(const json_t *root, struct GNUNET_JSON_Specification *spec, const char **error_json_name, unsigned int *error_line)
Navigate and parse data in a JSON tree.
Definition: json.c:32
struct GNUNET_JSON_Specification GNUNET_JSON_spec_end(void)
End of a parser specification.
Definition: json_helper.c:32
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_string(const char *name, const char *s)
Generate packer instruction for a JSON field of type string.
Definition: json_pack.c:90
static unsigned int size
Size of the "table".
Definition: peer.c:67
const char * name
The public information of an RSA key pair.
Definition: crypto_rsa.c:52
an RSA signature
Definition: crypto_rsa.c:64
Definition of a command line option.
const char * description
Help text for the option (description)
const char * argumentHelp
Name of the argument for the user in help text.
const char shortName
Short name of the option.
Element in the array to give to the packer.
bool allow_null
True if a NULL (or 0) argument is allowed.
json_t * object
Object to pack.
const char * field_name
Name of the field to pack.
Entry in parser specification for GNUNET_JSON_parse().
GNUNET_JSON_Cleaner cleaner
Function for how to clean up this type of entry.
void * ptr
Pointer, details specific to the parser.
const char * field
Name of the field to parse, use NULL to get the JSON of the main object instead of the JSON of an ind...
size_t ptr_size
Number of bytes available in ptr.
size_t * size_ptr
Where should we store the final size of ptr.
void * cls
Closure for parser and cleaner.
GNUNET_JSON_Parser parser
Function for how to parse this type of entry.
int is_optional
Set to GNUNET_YES if this component is optional.
Time for absolute time used by GNUnet, in microseconds and in network byte order.
Time for absolute times used by GNUnet, in microseconds.
Time for relative time used by GNUnet, in microseconds and in network byte order.
Time for relative time used by GNUnet, in microseconds.