gnunet_json_lib.h

Go to the documentation of this file.

/*
   This file is part of GNUnet
   Copyright (C) 2014, 2015, 2016, 2020 GNUnet e.V.
 
   GNUnet is free software: you can redistribute it and/or modify it
   under the terms of the GNU Affero General Public License as published
   by the Free Software Foundation, either version 3 of the License,
   or (at your option) any later version.
 
   GNUnet is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
     SPDX-License-Identifier: AGPL3.0-or-later
 */
#ifndef GNUNET_JSON_LIB_H
#define GNUNET_JSON_LIB_H
 
#include "gnunet_util_lib.h"
#include <jansson.h>
#include <microhttpd.h>
 
/* ****************** Generic parser interface ******************* */
 
struct GNUNET_JSON_Specification;
 
 
typedef enum GNUNET_GenericReturnValue
(*GNUNET_JSON_Parser)(void *cls,
                      json_t *root,
                      struct GNUNET_JSON_Specification *spec);
 
 
typedef void
(*GNUNET_JSON_Cleaner) (void *cls,
                        struct GNUNET_JSON_Specification *spec);
 
 
struct GNUNET_JSON_Specification
{
  GNUNET_JSON_Parser parser;
 
  GNUNET_JSON_Cleaner cleaner;
 
  void *cls;
 
  const char *field;
 
  void *ptr;
 
  bool *missing;
 
  size_t *size_ptr;
 
  size_t ptr_size;
 
  bool is_optional;
};
 
 
enum GNUNET_GenericReturnValue
GNUNET_JSON_parse (const json_t *root,
                   struct GNUNET_JSON_Specification *spec,
                   const char **error_json_name,
                   unsigned int *error_line);
 
 
void
GNUNET_JSON_parse_free (struct GNUNET_JSON_Specification *spec);
 
 
/* ****************** Canonical parser specifications ******************* */
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_end (void);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_mark_optional (struct GNUNET_JSON_Specification spec,
                                bool *missing);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_fixed (const char *name,
                        void *obj,
                        size_t size);
 
 
#define GNUNET_JSON_spec_fixed_auto(name, obj) \
  GNUNET_JSON_spec_fixed (name, obj, sizeof(*obj))
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_fixed64 (const char *name,
                          void *obj,
                          size_t size);
 
 
#define GNUNET_JSON_spec_fixed64_auto(name, obj) \
  GNUNET_JSON_spec_fixed (name, obj, sizeof(*obj))
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_varsize (const char *name,
                          void **obj,
                          size_t *size);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_string (const char *name,
                         const char **strptr);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_json (const char *name,
                       json_t **jsonp);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_bool (const char *name,
                       bool *b);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_uint8 (const char *name,
                        uint8_t *u8);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_uint16 (const char *name,
                         uint16_t *u16);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_uint32 (const char *name,
                         uint32_t *u32);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_uint64 (const char *name,
                         uint64_t *u64);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_int64 (const char *name,
                        int64_t *i64);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_boolean (const char *name,
                          int *boolean);
 
 
/* ************ GNUnet-specific parser specifications ******************* */
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_timestamp (const char *name,
                            struct GNUNET_TIME_Timestamp *t);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_timestamp_nbo (const char *name,
                                struct GNUNET_TIME_TimestampNBO *tn);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_relative_time (const char *name,
                                struct GNUNET_TIME_Relative *rt);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_rsa_public_key (const char *name,
                                 struct GNUNET_CRYPTO_RsaPublicKey **pk);
 
 
struct GNUNET_JSON_Specification
GNUNET_JSON_spec_rsa_signature (const char *name,
                                struct GNUNET_CRYPTO_RsaSignature **sig);
 
 
/* ****************** Generic generator interface ******************* */
 
 
json_t *
GNUNET_JSON_from_data (const void *data,
                       size_t size);
 
 
json_t *
GNUNET_JSON_from_data64 (const void *data,
                         size_t size);
 
 
#define GNUNET_JSON_from_data_auto(ptr) \
  GNUNET_JSON_from_data (ptr, sizeof(*ptr))
 
 
#define GNUNET_JSON_from_data64_auto(ptr) \
  GNUNET_JSON_from_data64 (ptr, sizeof(*ptr))
 
 
json_t *
GNUNET_JSON_from_timestamp (struct GNUNET_TIME_Timestamp stamp);
 
 
json_t *
GNUNET_JSON_from_timestamp_nbo (struct GNUNET_TIME_TimestampNBO stamp);
 
 
json_t *
GNUNET_JSON_from_time_rel (struct GNUNET_TIME_Relative stamp);
 
 
json_t *
GNUNET_JSON_from_rsa_public_key (const struct GNUNET_CRYPTO_RsaPublicKey *pk);
 
 
json_t *
GNUNET_JSON_from_rsa_signature (const struct GNUNET_CRYPTO_RsaSignature *sig);
 
/* ******************* Helpers for MHD upload handling ******************* */
 
enum GNUNET_JSON_PostResult
{
  GNUNET_JSON_PR_SUCCESS,
 
  GNUNET_JSON_PR_CONTINUE,
 
  GNUNET_JSON_PR_OUT_OF_MEMORY,
 
  GNUNET_JSON_PR_REQUEST_TOO_LARGE,
 
  GNUNET_JSON_PR_JSON_INVALID
};
 
 
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);
 
 
void
GNUNET_JSON_post_parser_cleanup (void *con_cls);
 
 
/* ****************** GETOPT JSON helper ******************* */
 
 
struct GNUNET_GETOPT_CommandLineOption
GNUNET_JSON_getopt (char shortName,
                    const char *name,
                    const char *argumentHelp,
                    const char *description,
                    json_t **json);
 
 
/* ****************** JSON PACK helper ******************* */
 
 
struct GNUNET_JSON_PackSpec;
 
 
typedef json_t *
(*GNUNET_JSON_PackCallback)(const struct GNUNET_JSON_PackSpec *se);
 
 
struct GNUNET_JSON_PackSpec
{
  const char *field_name;
 
  json_t *object;
 
  bool allow_null;
};
 
 
json_t *
GNUNET_JSON_pack_ (struct GNUNET_JSON_PackSpec spec[]);
 
 
#define GNUNET_JSON_PACK(...) \
  GNUNET_JSON_pack_ ((struct GNUNET_JSON_PackSpec[]) {__VA_ARGS__, \
                                                      GNUNET_JSON_pack_end_ ()})
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_end_ (void);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_allow_null (struct GNUNET_JSON_PackSpec in);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_bool (const char *name,
                       bool b);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_string (const char *name,
                         const char *s);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_uint64 (const char *name,
                         uint64_t num);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_int64 (const char *name,
                        int64_t num);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_object_steal (const char *name,
                               json_t *o);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_object_incref (const char *name,
                                json_t *o);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_array_steal (const char *name,
                              json_t *a);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_array_incref (const char *name,
                               json_t *a);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_data_varsize (const char *name,
                               const void *blob,
                               size_t blob_size);
 
 
#define GNUNET_JSON_pack_data_auto(name,blob) \
  GNUNET_JSON_pack_data_varsize (name, blob, sizeof (*blob))
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_data64_varsize (const char *name,
                                 const void *blob,
                                 size_t blob_size);
 
 
#define GNUNET_JSON_pack_data64_auto(name,blob) \
  GNUNET_JSON_pack_data64_varsize (name, blob, sizeof (*blob))
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_timestamp (const char *name,
                            struct GNUNET_TIME_Timestamp at);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_timestamp_nbo (const char *name,
                                struct GNUNET_TIME_TimestampNBO at);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_time_rel (const char *name,
                           struct GNUNET_TIME_Relative rt);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_time_rel_nbo (const char *name,
                               struct GNUNET_TIME_RelativeNBO rt);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_rsa_public_key (const char *name,
                                 const struct GNUNET_CRYPTO_RsaPublicKey *pk);
 
 
struct GNUNET_JSON_PackSpec
GNUNET_JSON_pack_rsa_signature (const char *name,
                                const struct GNUNET_CRYPTO_RsaSignature *sig);
 
 
#endif
 
/* end of gnunet_json_lib.h */