GNUnet  0.19.2
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 
255 GNUNET_JSON_spec_json (const char *name,
256  json_t **jsonp);
257 
258 
266 GNUNET_JSON_spec_bool (const char *name,
267  bool *b);
268 
269 
277 GNUNET_JSON_spec_uint8 (const char *name,
278  uint8_t *u8);
279 
280 
288 GNUNET_JSON_spec_uint16 (const char *name,
289  uint16_t *u16);
290 
291 
299 GNUNET_JSON_spec_uint32 (const char *name,
300  uint32_t *u32);
301 
302 
310 GNUNET_JSON_spec_uint64 (const char *name,
311  uint64_t *u64);
312 
313 
321 GNUNET_JSON_spec_int64 (const char *name,
322  int64_t *i64);
323 
324 
332 GNUNET_JSON_spec_boolean (const char *name,
333  int *boolean);
334 
335 
336 /* ************ GNUnet-specific parser specifications ******************* */
337 
345 GNUNET_JSON_spec_timestamp (const char *name,
346  struct GNUNET_TIME_Timestamp *t);
347 
348 
357  struct GNUNET_TIME_TimestampNBO *tn);
358 
359 
368  struct GNUNET_TIME_Relative *rt);
369 
370 
379  struct GNUNET_CRYPTO_RsaPublicKey **pk);
380 
381 
390  struct GNUNET_CRYPTO_RsaSignature **sig);
391 
392 
393 /* ****************** Generic generator interface ******************* */
394 
395 
404 json_t *
405 GNUNET_JSON_from_data (const void *data,
406  size_t size);
407 
408 
417 json_t *
418 GNUNET_JSON_from_data64 (const void *data,
419  size_t size);
420 
421 
429 #define GNUNET_JSON_from_data_auto(ptr) \
430  GNUNET_JSON_from_data (ptr, sizeof(*ptr))
431 
432 
440 #define GNUNET_JSON_from_data64_auto(ptr) \
441  GNUNET_JSON_from_data64 (ptr, sizeof(*ptr))
442 
443 
450 json_t *
452 
453 
460 json_t *
462 
463 
470 json_t *
472 
473 
480 json_t *
482 
483 
490 json_t *
492 
493 /* ******************* Helpers for MHD upload handling ******************* */
494 
499 {
504 
509 
514 
519 
524 };
525 
526 
543 GNUNET_JSON_post_parser (size_t buffer_max,
544  struct MHD_Connection *connection,
545  void **con_cls,
546  const char *upload_data,
547  size_t *upload_data_size,
548  json_t **json);
549 
550 
558 void
559 GNUNET_JSON_post_parser_cleanup (void *con_cls);
560 
561 
562 /* ****************** GETOPT JSON helper ******************* */
563 
564 
576  const char *name,
577  const char *argumentHelp,
578  const char *description,
579  json_t **json);
580 
581 
582 /* ****************** JSON PACK helper ******************* */
583 
584 
588 struct GNUNET_JSON_PackSpec;
589 
590 
598 typedef json_t *
599 (*GNUNET_JSON_PackCallback)(const struct GNUNET_JSON_PackSpec *se);
600 
601 
606 {
610  const char *field_name;
611 
615  json_t *object;
616 
624 };
625 
626 
634 json_t *
636 
637 
645 #define GNUNET_JSON_PACK(...) \
646  GNUNET_JSON_pack_ ((struct GNUNET_JSON_PackSpec[]) {__VA_ARGS__, \
647  GNUNET_JSON_pack_end_ ()})
648 
649 
656 GNUNET_JSON_pack_end_ (void);
657 
658 
667 
668 
678 GNUNET_JSON_pack_bool (const char *name,
679  bool b);
680 
681 
691 GNUNET_JSON_pack_string (const char *name,
692  const char *s);
693 
694 
705 GNUNET_JSON_pack_uint64 (const char *name,
706  uint64_t num);
707 
708 
718 GNUNET_JSON_pack_int64 (const char *name,
719  int64_t num);
720 
721 
733  json_t *o);
734 
735 
747  json_t *o);
748 
749 
761  json_t *a);
762 
763 
775  json_t *a);
776 
777 
789  const void *blob,
790  size_t blob_size);
791 
792 
801 #define GNUNET_JSON_pack_data_auto(name,blob) \
802  GNUNET_JSON_pack_data_varsize (name, blob, sizeof (*blob))
803 
804 
818  const void *blob,
819  size_t blob_size);
820 
821 
832 #define GNUNET_JSON_pack_data64_auto(name,blob) \
833  GNUNET_JSON_pack_data64_varsize (name, blob, sizeof (*blob))
834 
835 
846 GNUNET_JSON_pack_timestamp (const char *name,
847  struct GNUNET_TIME_Timestamp at);
848 
849 
861  struct GNUNET_TIME_TimestampNBO at);
862 
863 
873 GNUNET_JSON_pack_time_rel (const char *name,
874  struct GNUNET_TIME_Relative rt);
875 
876 
887  struct GNUNET_TIME_RelativeNBO rt);
888 
889 
900  const struct GNUNET_CRYPTO_RsaPublicKey *pk);
901 
902 
913  const struct GNUNET_CRYPTO_RsaSignature *sig);
914 
915 
916 #endif
917 
918 /* 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.
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.