GNUnet  0.20.0
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 
31 #include "gnunet_util_lib.h"
32 #include <jansson.h>
33 #include <microhttpd.h>
34 
35 /* ****************** Generic parser interface ******************* */
36 
41 
42 
52 typedef enum GNUNET_GenericReturnValue
53 (*GNUNET_JSON_Parser)(void *cls,
54  json_t *root,
55  struct GNUNET_JSON_Specification *spec);
56 
57 
64 typedef void
65 (*GNUNET_JSON_Cleaner) (void *cls,
66  struct GNUNET_JSON_Specification *spec);
67 
68 
73 {
78 
83 
87  void *cls;
88 
93  const char *field;
94 
98  void *ptr;
99 
104  bool *missing;
105 
109  size_t *size_ptr;
110 
114  size_t ptr_size;
115 
120 };
121 
122 
137 GNUNET_JSON_parse (const json_t *root,
138  struct GNUNET_JSON_Specification *spec,
139  const char **error_json_name,
140  unsigned int *error_line);
141 
142 
149 void
151 
152 
153 /* ****************** Canonical parser specifications ******************* */
154 
155 
160 GNUNET_JSON_spec_end (void);
161 
162 
172  bool *missing);
173 
174 
184 GNUNET_JSON_spec_fixed (const char *name,
185  void *obj,
186  size_t size);
187 
188 
196 #define GNUNET_JSON_spec_fixed_auto(name, obj) \
197  GNUNET_JSON_spec_fixed (name, obj, sizeof(*obj))
198 
199 
208 GNUNET_JSON_spec_fixed64 (const char *name,
209  void *obj,
210  size_t size);
211 
212 
219 #define GNUNET_JSON_spec_fixed64_auto(name, obj) \
220  GNUNET_JSON_spec_fixed (name, obj, sizeof(*obj))
221 
222 
232 GNUNET_JSON_spec_varsize (const char *name,
233  void **obj,
234  size_t *size);
235 
236 
244 GNUNET_JSON_spec_string (const char *name,
245  const char **strptr);
246 
247 
256 GNUNET_JSON_spec_json (const char *name,
257  json_t **jsonp);
258 
259 
268  const json_t **jsonp);
269 
270 
279  const json_t **jsonp);
280 
281 
289 GNUNET_JSON_spec_bool (const char *name,
290  bool *b);
291 
292 
300 GNUNET_JSON_spec_uint8 (const char *name,
301  uint8_t *u8);
302 
303 
311 GNUNET_JSON_spec_uint16 (const char *name,
312  uint16_t *u16);
313 
314 
322 GNUNET_JSON_spec_uint32 (const char *name,
323  uint32_t *u32);
324 
325 
333 GNUNET_JSON_spec_uint64 (const char *name,
334  uint64_t *u64);
335 
336 
344 GNUNET_JSON_spec_int64 (const char *name,
345  int64_t *i64);
346 
347 
355 GNUNET_JSON_spec_boolean (const char *name,
356  int *boolean);
357 
358 
359 /* ************ GNUnet-specific parser specifications ******************* */
360 
368 GNUNET_JSON_spec_timestamp (const char *name,
369  struct GNUNET_TIME_Timestamp *t);
370 
371 
380  struct GNUNET_TIME_TimestampNBO *tn);
381 
382 
391  struct GNUNET_TIME_Relative *rt);
392 
393 
402  struct GNUNET_CRYPTO_RsaPublicKey **pk);
403 
404 
413  struct GNUNET_CRYPTO_RsaSignature **sig);
414 
415 
416 /* ****************** Generic generator interface ******************* */
417 
418 
427 json_t *
428 GNUNET_JSON_from_data (const void *data,
429  size_t size);
430 
431 
440 json_t *
441 GNUNET_JSON_from_data64 (const void *data,
442  size_t size);
443 
444 
452 #define GNUNET_JSON_from_data_auto(ptr) \
453  GNUNET_JSON_from_data (ptr, sizeof(*ptr))
454 
455 
463 #define GNUNET_JSON_from_data64_auto(ptr) \
464  GNUNET_JSON_from_data64 (ptr, sizeof(*ptr))
465 
466 
473 json_t *
475 
476 
483 json_t *
485 
486 
493 json_t *
495 
496 
503 json_t *
505 
506 
513 json_t *
515 
516 /* ******************* Helpers for MHD upload handling ******************* */
517 
522 {
527 
532 
537 
542 
547 };
548 
549 
566 GNUNET_JSON_post_parser (size_t buffer_max,
567  struct MHD_Connection *connection,
568  void **con_cls,
569  const char *upload_data,
570  size_t *upload_data_size,
571  json_t **json);
572 
573 
581 void
582 GNUNET_JSON_post_parser_cleanup (void *con_cls);
583 
584 
585 /* ****************** GETOPT JSON helper ******************* */
586 
587 
599  const char *name,
600  const char *argumentHelp,
601  const char *description,
602  json_t **json);
603 
604 
605 /* ****************** JSON PACK helper ******************* */
606 
607 
611 struct GNUNET_JSON_PackSpec;
612 
613 
621 typedef json_t *
622 (*GNUNET_JSON_PackCallback)(const struct GNUNET_JSON_PackSpec *se);
623 
624 
629 {
633  const char *field_name;
634 
638  json_t *object;
639 
647 };
648 
649 
657 json_t *
659 
660 
668 #define GNUNET_JSON_PACK(...) \
669  GNUNET_JSON_pack_ ((struct GNUNET_JSON_PackSpec[]) {__VA_ARGS__, \
670  GNUNET_JSON_pack_end_ ()})
671 
672 
679 GNUNET_JSON_pack_end_ (void);
680 
681 
690 
691 
701 GNUNET_JSON_pack_bool (const char *name,
702  bool b);
703 
704 
714 GNUNET_JSON_pack_string (const char *name,
715  const char *s);
716 
717 
728 GNUNET_JSON_pack_uint64 (const char *name,
729  uint64_t num);
730 
731 
741 GNUNET_JSON_pack_int64 (const char *name,
742  int64_t num);
743 
744 
756  json_t *o);
757 
758 
770  json_t *o);
771 
772 
784  json_t *a);
785 
786 
798  json_t *a);
799 
800 
812  const void *blob,
813  size_t blob_size);
814 
815 
824 #define GNUNET_JSON_pack_data_auto(name,blob) \
825  GNUNET_JSON_pack_data_varsize (name, blob, sizeof (*blob))
826 
827 
841  const void *blob,
842  size_t blob_size);
843 
844 
855 #define GNUNET_JSON_pack_data64_auto(name,blob) \
856  GNUNET_JSON_pack_data64_varsize (name, blob, sizeof (*blob))
857 
858 
869 GNUNET_JSON_pack_timestamp (const char *name,
870  struct GNUNET_TIME_Timestamp at);
871 
872 
884  struct GNUNET_TIME_TimestampNBO at);
885 
886 
896 GNUNET_JSON_pack_time_rel (const char *name,
897  struct GNUNET_TIME_Relative rt);
898 
899 
910  struct GNUNET_TIME_RelativeNBO rt);
911 
912 
923  const struct GNUNET_CRYPTO_RsaPublicKey *pk);
924 
925 
936  const struct GNUNET_CRYPTO_RsaSignature *sig);
937 
938 
939 #endif
940 
941 /* 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.
static struct GNUNET_SCHEDULER_Task * t
Main task.
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:307
struct GNUNET_JSON_Specification GNUNET_JSON_spec_object_const(const char *name, const json_t **jsonp)
JSON object, reference counter not incremented.
Definition: json_helper.c:384
json_t * GNUNET_JSON_from_timestamp(struct GNUNET_TIME_Timestamp stamp)
Convert timestamp to a json string.
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_end_(void)
Do not use directly.
Definition: json_pack.c:70
enum GNUNET_GenericReturnValue(* GNUNET_JSON_Parser)(void *cls, json_t *root, struct GNUNET_JSON_Specification *spec)
Function called to parse JSON argument.
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:229
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:88
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:198
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_timestamp(const char *name, struct GNUNET_TIME_Timestamp at)
Generate packer instruction for a JSON field of type timestamp.
Definition: json_pack.c:277
void GNUNET_JSON_parse_free(struct GNUNET_JSON_Specification *spec)
Frees all elements allocated during a GNUNET_JSON_parse() operation.
Definition: json.c:94
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:243
struct GNUNET_JSON_Specification GNUNET_JSON_spec_json(const char *name, json_t **jsonp)
JSON object or array.
Definition: json_helper.c:340
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:89
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:1122
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:993
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint16(const char *name, uint16_t *u16)
16-bit integer.
Definition: json_helper.c:575
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:153
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:220
json_t * GNUNET_JSON_from_rsa_signature(const struct GNUNET_CRYPTO_RsaSignature *sig)
Convert RSA signature to JSON.
struct GNUNET_JSON_Specification GNUNET_JSON_spec_timestamp_nbo(const char *name, struct GNUNET_TIME_TimestampNBO *tn)
Timestamp in network byte order.
Definition: json_helper.c:839
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:81
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint32(const char *name, uint32_t *u32)
32-bit integer.
Definition: json_helper.c:625
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:277
json_t * GNUNET_JSON_from_rsa_public_key(const struct GNUNET_CRYPTO_RsaPublicKey *pk)
Convert RSA public key to JSON.
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_timestamp_nbo(const char *name, struct GNUNET_TIME_TimestampNBO at)
Generate packer instruction for a JSON field of type timestamp in network byte order.
Definition: json_pack.c:298
struct GNUNET_JSON_Specification GNUNET_JSON_spec_mark_optional(struct GNUNET_JSON_Specification spec, bool *missing)
Set the "optional" flag for a parser specification entry.
Definition: json.c:82
struct GNUNET_JSON_Specification GNUNET_JSON_spec_int64(const char *name, int64_t *i64)
64-bit signed integer.
Definition: json_helper.c:715
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:1078
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:115
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:175
struct GNUNET_JSON_Specification GNUNET_JSON_spec_timestamp(const char *name, struct GNUNET_TIME_Timestamp *t)
Timestamp.
Definition: json_helper.c:794
struct GNUNET_JSON_Specification GNUNET_JSON_spec_array_const(const char *name, const json_t **jsonp)
JSON array, reference counter not incremented.
Definition: json_helper.c:427
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:342
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:141
struct GNUNET_JSON_PackSpec GNUNET_JSON_pack_data64_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:260
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:329
struct GNUNET_JSON_Specification GNUNET_JSON_spec_fixed64(const char *name, void *obj, size_t size)
Variable size object (in network byte order, encoded using base64 encoding).
Definition: json_helper.c:152
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:133
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:320
struct GNUNET_JSON_Specification GNUNET_JSON_spec_bool(const char *name, bool *b)
boolean.
Definition: json_helper.c:475
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:909
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint8(const char *name, uint8_t *u8)
8-bit integer.
Definition: json_helper.c:525
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint64(const char *name, uint64_t *u64)
64-bit integer.
Definition: json_helper.c:670
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:102
json_t * GNUNET_JSON_from_data64(const void *data, size_t size)
Convert binary data to a JSON string with base64 encoding.
json_t * GNUNET_JSON_from_timestamp_nbo(struct GNUNET_TIME_TimestampNBO stamp)
Convert timestamp to a json string.
GNUNET_GenericReturnValue
Named constants for return values.
static unsigned int size
Size of the "table".
Definition: peer.c:68
const char * name
The public information of an RSA key pair.
Definition: crypto_rsa.c:53
an RSA signature
Definition: crypto_rsa.c:65
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.
bool * missing
Pointer to set to true if this argument is indeed missing.
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.
bool is_optional
Set to true if this component is optional.
void * cls
Closure for parser and cleaner.
GNUNET_JSON_Parser parser
Function for how to parse this type of entry.
Time for relative time used by GNUnet, in microseconds and in network byte order.
Time for relative time used by GNUnet, in microseconds.
Time for timestamps used by GNUnet, in seconds and in network byte order.
Rounded time for timestamps used by GNUnet, in seconds.