GNUnet  0.17.6
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 enum GNUNET_GenericReturnValue
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 
103  bool *missing;
104 
108  size_t *size_ptr;
109 
113  size_t ptr_size;
114 
119 };
120 
121 
136 GNUNET_JSON_parse (const json_t *root,
137  struct GNUNET_JSON_Specification *spec,
138  const char **error_json_name,
139  unsigned int *error_line);
140 
141 
148 void
150 
151 
152 /* ****************** Canonical parser specifications ******************* */
153 
154 
159 GNUNET_JSON_spec_end (void);
160 
161 
171  bool *missing);
172 
173 
183 GNUNET_JSON_spec_fixed (const char *name,
184  void *obj,
185  size_t size);
186 
187 
195 #define GNUNET_JSON_spec_fixed_auto(name, obj) \
196  GNUNET_JSON_spec_fixed (name, obj, sizeof(*obj))
197 
198 
207 GNUNET_JSON_spec_fixed64 (const char *name,
208  void *obj,
209  size_t size);
210 
211 
218 #define GNUNET_JSON_spec_fixed64_auto(name, obj) \
219  GNUNET_JSON_spec_fixed (name, obj, sizeof(*obj))
220 
221 
231 GNUNET_JSON_spec_varsize (const char *name,
232  void **obj,
233  size_t *size);
234 
235 
243 GNUNET_JSON_spec_string (const char *name,
244  const char **strptr);
245 
246 
254 GNUNET_JSON_spec_json (const char *name,
255  json_t **jsonp);
256 
257 
265 GNUNET_JSON_spec_bool (const char *name,
266  bool *b);
267 
268 
276 GNUNET_JSON_spec_uint8 (const char *name,
277  uint8_t *u8);
278 
279 
287 GNUNET_JSON_spec_uint16 (const char *name,
288  uint16_t *u16);
289 
290 
298 GNUNET_JSON_spec_uint32 (const char *name,
299  uint32_t *u32);
300 
301 
309 GNUNET_JSON_spec_uint64 (const char *name,
310  uint64_t *u64);
311 
312 
320 GNUNET_JSON_spec_int64 (const char *name,
321  int64_t *i64);
322 
323 
331 GNUNET_JSON_spec_boolean (const char *name,
332  int *boolean);
333 
334 
335 /* ************ GNUnet-specific parser specifications ******************* */
336 
344 GNUNET_JSON_spec_timestamp (const char *name,
345  struct GNUNET_TIME_Timestamp *t);
346 
347 
356  struct GNUNET_TIME_TimestampNBO *tn);
357 
358 
367  struct GNUNET_TIME_Relative *rt);
368 
369 
378  struct GNUNET_CRYPTO_RsaPublicKey **pk);
379 
380 
389  struct GNUNET_CRYPTO_RsaSignature **sig);
390 
391 
392 /* ****************** Generic generator interface ******************* */
393 
394 
403 json_t *
404 GNUNET_JSON_from_data (const void *data,
405  size_t size);
406 
407 
416 json_t *
417 GNUNET_JSON_from_data64 (const void *data,
418  size_t size);
419 
420 
428 #define GNUNET_JSON_from_data_auto(ptr) \
429  GNUNET_JSON_from_data (ptr, sizeof(*ptr))
430 
431 
439 #define GNUNET_JSON_from_data64_auto(ptr) \
440  GNUNET_JSON_from_data64 (ptr, sizeof(*ptr))
441 
442 
449 json_t *
451 
452 
459 json_t *
461 
462 
469 json_t *
471 
472 
479 json_t *
481 
482 
489 json_t *
491 
492 /* ******************* Helpers for MHD upload handling ******************* */
493 
498 {
503 
508 
513 
518 
523 };
524 
525 
542 GNUNET_JSON_post_parser (size_t buffer_max,
543  struct MHD_Connection *connection,
544  void **con_cls,
545  const char *upload_data,
546  size_t *upload_data_size,
547  json_t **json);
548 
549 
557 void
558 GNUNET_JSON_post_parser_cleanup (void *con_cls);
559 
560 
561 /* ****************** GETOPT JSON helper ******************* */
562 
563 
575  const char *name,
576  const char *argumentHelp,
577  const char *description,
578  json_t **json);
579 
580 
581 /* ****************** JSON PACK helper ******************* */
582 
583 
587 struct GNUNET_JSON_PackSpec;
588 
589 
597 typedef json_t *
598 (*GNUNET_JSON_PackCallback)(const struct GNUNET_JSON_PackSpec *se);
599 
600 
605 {
609  const char *field_name;
610 
614  json_t *object;
615 
623 };
624 
625 
633 json_t *
635 
636 
644 #define GNUNET_JSON_PACK(...) \
645  GNUNET_JSON_pack_ ((struct GNUNET_JSON_PackSpec[]) {__VA_ARGS__, \
646  GNUNET_JSON_pack_end_ ()})
647 
648 
655 GNUNET_JSON_pack_end_ (void);
656 
657 
666 
667 
677 GNUNET_JSON_pack_bool (const char *name,
678  bool b);
679 
680 
690 GNUNET_JSON_pack_string (const char *name,
691  const char *s);
692 
693 
704 GNUNET_JSON_pack_uint64 (const char *name,
705  uint64_t num);
706 
707 
717 GNUNET_JSON_pack_int64 (const char *name,
718  int64_t num);
719 
720 
732  json_t *o);
733 
734 
746  json_t *o);
747 
748 
760  json_t *a);
761 
762 
774  json_t *a);
775 
776 
788  const void *blob,
789  size_t blob_size);
790 
791 
800 #define GNUNET_JSON_pack_data_auto(name,blob) \
801  GNUNET_JSON_pack_data_varsize (name, blob, sizeof (*blob))
802 
803 
817  const void *blob,
818  size_t blob_size);
819 
820 
831 #define GNUNET_JSON_pack_data64_auto(name,blob) \
832  GNUNET_JSON_pack_data64_varsize (name, blob, sizeof (*blob))
833 
834 
845 GNUNET_JSON_pack_timestamp (const char *name,
846  struct GNUNET_TIME_Timestamp at);
847 
848 
860  struct GNUNET_TIME_TimestampNBO at);
861 
862 
872 GNUNET_JSON_pack_time_rel (const char *name,
873  struct GNUNET_TIME_Relative rt);
874 
875 
886  struct GNUNET_TIME_RelativeNBO rt);
887 
888 
899  const struct GNUNET_CRYPTO_RsaPublicKey *pk);
900 
901 
912  const struct GNUNET_CRYPTO_RsaSignature *sig);
913 
914 
915 #endif
916 
917 /* 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:301
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:64
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:192
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:271
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:237
struct GNUNET_JSON_Specification GNUNET_JSON_spec_json(const char *name, json_t **jsonp)
JSON object.
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:83
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:1036
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:907
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint16(const char *name, uint16_t *u16)
16-bit integer.
Definition: json_helper.c:489
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:147
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:214
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:753
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:75
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint32(const char *name, uint32_t *u32)
32-bit integer.
Definition: json_helper.c:539
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:292
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:629
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:992
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:109
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:169
struct GNUNET_JSON_Specification GNUNET_JSON_spec_timestamp(const char *name, struct GNUNET_TIME_Timestamp *t)
Timestamp.
Definition: json_helper.c:708
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:336
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:254
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:323
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:127
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:314
struct GNUNET_JSON_Specification GNUNET_JSON_spec_bool(const char *name, bool *b)
boolean.
Definition: json_helper.c:389
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:823
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint8(const char *name, uint8_t *u8)
8-bit integer.
Definition: json_helper.c:439
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint64(const char *name, uint64_t *u64)
64-bit integer.
Definition: json_helper.c:584
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:96
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.
Definition: gnunet_common.h:96
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.
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.