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 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 
208 GNUNET_JSON_spec_varsize (const char *name,
209  void **obj,
210  size_t *size);
211 
212 
220 GNUNET_JSON_spec_string (const char *name,
221  const char **strptr);
222 
223 
231 GNUNET_JSON_spec_json (const char *name,
232  json_t **jsonp);
233 
234 
242 GNUNET_JSON_spec_bool (const char *name,
243  bool *b);
244 
245 
253 GNUNET_JSON_spec_uint8 (const char *name,
254  uint8_t *u8);
255 
256 
264 GNUNET_JSON_spec_uint16 (const char *name,
265  uint16_t *u16);
266 
267 
275 GNUNET_JSON_spec_uint32 (const char *name,
276  uint32_t *u32);
277 
278 
286 GNUNET_JSON_spec_uint64 (const char *name,
287  uint64_t *u64);
288 
289 
297 GNUNET_JSON_spec_int64 (const char *name,
298  int64_t *i64);
299 
300 
308 GNUNET_JSON_spec_boolean (const char *name,
309  int *boolean);
310 
311 
312 /* ************ GNUnet-specific parser specifications ******************* */
313 
321 GNUNET_JSON_spec_timestamp (const char *name,
322  struct GNUNET_TIME_Timestamp *t);
323 
324 
333  struct GNUNET_TIME_TimestampNBO *tn);
334 
335 
344  struct GNUNET_TIME_Relative *rt);
345 
346 
355  struct GNUNET_CRYPTO_RsaPublicKey **pk);
356 
357 
366  struct GNUNET_CRYPTO_RsaSignature **sig);
367 
368 
369 /* ****************** Generic generator interface ******************* */
370 
371 
380 json_t *
381 GNUNET_JSON_from_data (const void *data, size_t size);
382 
383 
391 #define GNUNET_JSON_from_data_auto(ptr) \
392  GNUNET_JSON_from_data (ptr, sizeof(*ptr))
393 
394 
401 json_t *
403 
404 
411 json_t *
413 
414 
421 json_t *
423 
424 
431 json_t *
433 
434 
441 json_t *
443 
444 /* ******************* Helpers for MHD upload handling ******************* */
445 
450 {
455 
460 
465 
470 
475 };
476 
477 
494 GNUNET_JSON_post_parser (size_t buffer_max,
495  struct MHD_Connection *connection,
496  void **con_cls,
497  const char *upload_data,
498  size_t *upload_data_size,
499  json_t **json);
500 
501 
509 void
510 GNUNET_JSON_post_parser_cleanup (void *con_cls);
511 
512 
513 /* ****************** GETOPT JSON helper ******************* */
514 
515 
527  const char *name,
528  const char *argumentHelp,
529  const char *description,
530  json_t **json);
531 
532 
533 /* ****************** JSON PACK helper ******************* */
534 
535 
539 struct GNUNET_JSON_PackSpec;
540 
541 
549 typedef json_t *
550 (*GNUNET_JSON_PackCallback)(const struct GNUNET_JSON_PackSpec *se);
551 
552 
557 {
561  const char *field_name;
562 
566  json_t *object;
567 
575 };
576 
577 
585 json_t *
587 
588 
596 #define GNUNET_JSON_PACK(...) \
597  GNUNET_JSON_pack_ ((struct GNUNET_JSON_PackSpec[]) {__VA_ARGS__, \
598  GNUNET_JSON_pack_end_ ()})
599 
600 
607 GNUNET_JSON_pack_end_ (void);
608 
609 
618 
619 
629 GNUNET_JSON_pack_bool (const char *name,
630  bool b);
631 
632 
642 GNUNET_JSON_pack_string (const char *name,
643  const char *s);
644 
645 
656 GNUNET_JSON_pack_uint64 (const char *name,
657  uint64_t num);
658 
659 
669 GNUNET_JSON_pack_int64 (const char *name,
670  int64_t num);
671 
672 
684  json_t *o);
685 
686 
698  json_t *o);
699 
700 
712  json_t *a);
713 
714 
726  json_t *a);
727 
728 
740  const void *blob,
741  size_t blob_size);
742 
743 
752 #define GNUNET_JSON_pack_data_auto(name,blob) \
753  GNUNET_JSON_pack_data_varsize (name, blob, sizeof (*blob))
754 
755 
766 GNUNET_JSON_pack_timestamp (const char *name,
767  struct GNUNET_TIME_Timestamp at);
768 
769 
781  struct GNUNET_TIME_TimestampNBO at);
782 
783 
793 GNUNET_JSON_pack_time_rel (const char *name,
794  struct GNUNET_TIME_Relative rt);
795 
796 
807  struct GNUNET_TIME_RelativeNBO rt);
808 
809 
820  const struct GNUNET_CRYPTO_RsaPublicKey *pk);
821 
822 
833  const struct GNUNET_CRYPTO_RsaSignature *sig);
834 
835 
836 #endif
837 
838 /* 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.
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:284
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: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: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:254
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: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: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:1030
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:901
struct GNUNET_JSON_Specification GNUNET_JSON_spec_uint16(const char *name, uint16_t *u16)
16-bit integer.
Definition: json_helper.c:422
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:721
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: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
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:275
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: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:986
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:676
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:319
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_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:306
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:297
struct GNUNET_JSON_Specification GNUNET_JSON_spec_bool(const char *name, bool *b)
boolean.
Definition: json_helper.c:322
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:817
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:96
json_t * GNUNET_JSON_from_timestamp_nbo(struct GNUNET_TIME_TimestampNBO stamp)
Convert timestamp to a json string.
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.