src/include/gnunet_json_lib.h

   1 /*
   2   This file is part of GNUnet
   3   Copyright (C) 2014, 2015, 2016 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 */
  20 /**
  21  * @file gnunet_json_lib.h
  22  * @brief functions to parse JSON objects into GNUnet objects
  23  * @author Florian Dold
  24  * @author Benedikt Mueller
  25  * @author Christian Grothoff
  26  */
  27 #ifndef GNUNET_JSON_LIB_H
  28 #define GNUNET_JSON_LIB_H
  29
  30 #include "gnunet_util_lib.h"
  31 #include "gnunet_gnsrecord_lib.h"
  32 #include <jansson.h>
  33
  34
  35 /* ****************** Generic parser interface ******************* */
  36
  37 /**
  38  * @brief Entry in parser specification for #GNUNET_JSON_parse().
  39  */
  40 struct GNUNET_JSON_Specification;
  41
  42
  43 /**
  44  * Function called to parse JSON argument.
  45  *
  46  * @param cls closure
  47  * @param root JSON to parse
  48  * @param spec our specification entry with further details
  49  * @return #GNUNET_SYSERR on error,
  50  *         #GNUNET_OK on success
  51  */
  52 typedef int
  53 (*GNUNET_JSON_Parser)(void *cls,
  54                       json_t *root,
  55                       struct GNUNET_JSON_Specification *spec);
  56
  57
  58 /**
  59  * Function called to clean up data from earlier parsing.
  60  *
  61  * @param cls closure
  62  * @param spec our specification entry with data to clean.
  63  */
  64 typedef void
  65 (*GNUNET_JSON_Cleaner)(void *cls,
  66                        struct GNUNET_JSON_Specification *spec);
  67
  68
  69 /**
  70  * @brief Entry in parser specification for #GNUNET_JSON_parse().
  71  */
  72 struct GNUNET_JSON_Specification
  73 {
  74   /**
  75    * Function for how to parse this type of entry.
  76    */
  77   GNUNET_JSON_Parser parser;
  78
  79   /**
  80    * Function for how to clean up this type of entry.
  81    */
  82   GNUNET_JSON_Cleaner cleaner;
  83
  84   /**
  85    * Closure for @e parser and @e cleaner.
  86    */
  87   void *cls;
  88
  89   /**
  90    * Name of the field to parse, use NULL to get the JSON
  91    * of the main object instead of the JSON of an individual field.
  92    */
  93   const char *field;
  94
  95   /**
  96    * Pointer, details specific to the @e parser.
  97    */
  98   void *ptr;
  99
 100   /**
 101    * Number of bytes available in @e ptr.
 102    */
 103   size_t ptr_size;
 104
 105   /**
 106    * Where should we store the final size of @e ptr.
 107    */
 108   size_t *size_ptr;
 109
 110 };
 111
 112
 113 /**
 114  * Navigate and parse data in a JSON tree.  Tries to parse the @a root
 115  * to find all of the values given in the @a spec.  If one of the
 116  * entries in @a spec cannot be found or parsed, the name of the JSON
 117  * field is returned in @a error_json_name, and the offset of the
 118  * entry in @a spec is returned in @a error_line.
 119  *
 120  * @param root the JSON node to start the navigation at.
 121  * @param spec parse specification array
 122  * @param[out] error_json_name which JSON field was problematic
 123  * @param[out] which index into @a spec did we encounter an error
 124  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 125  */
 126 int
 127 GNUNET_JSON_parse (const json_t *root,
 128                    struct GNUNET_JSON_Specification *spec,
 129                    const char **error_json_name,
 130                    unsigned int *error_line);
 131
 132
 133 /**
 134  * Frees all elements allocated during a #GNUNET_JSON_parse()
 135  * operation.
 136  *
 137  * @param spec specification of the parse operation
 138  */
 139 void
 140 GNUNET_JSON_parse_free (struct GNUNET_JSON_Specification *spec);
 141
 142
 143
 144 /* ****************** Canonical parser specifications ******************* */
 145
 146
 147 /**
 148  * End of a parser specification.
 149  */
 150 struct GNUNET_JSON_Specification
 151 GNUNET_JSON_spec_end (void);
 152
 153
 154 /**
 155  * Variable size object (in network byte order, encoded using Crockford
 156  * Base32hex encoding).
 157  *
 158  * @param name name of the JSON field
 159  * @param[out] obj pointer where to write the data, must have @a size bytes
 160  * @param size number of bytes expected in @a obj
 161  */
 162 struct GNUNET_JSON_Specification
 163 GNUNET_JSON_spec_fixed (const char *name,
 164                         void *obj,
 165                         size_t size);
 166
 167
 168 /**
 169  * Fixed size object (in network byte order, encoded using Crockford
 170  * Base32hex encoding).
 171  *
 172  * @param name name of the JSON field
 173  * @param obj pointer where to write the data (type of `*obj` will determine size)
 174  */
 175 #define GNUNET_JSON_spec_fixed_auto(name,obj) GNUNET_JSON_spec_fixed (name, obj, sizeof (*obj))
 176
 177
 178 /**
 179  * Variable size object (in network byte order, encoded using
 180  * Crockford Base32hex encoding).
 181  *
 182  * @param name name of the JSON field
 183  * @param[out] obj pointer where to write the data, will be allocated
 184  * @param[out] size where to store the number of bytes allocated for @a obj
 185  */
 186 struct GNUNET_JSON_Specification
 187 GNUNET_JSON_spec_varsize (const char *name,
 188                           void **obj,
 189                           size_t *size);
 190
 191
 192 /**
 193  * The expected field stores a string.
 194  *
 195  * @param name name of the JSON field
 196  * @param strptr where to store a pointer to the field
 197  */
 198 struct GNUNET_JSON_Specification
 199 GNUNET_JSON_spec_string (const char *name,
 200                          const char **strptr);
 201
 202 /**
 203  * JSON object.
 204  *
 205  * @param name name of the JSON field
 206  * @param[out] jsonp where to store the JSON found under @a name
 207  */
 208 struct GNUNET_JSON_Specification
 209 GNUNET_JSON_spec_json (const char *name,
 210                        json_t **jsonp);
 211
 212
 213 /**
 214  * 8-bit integer.
 215  *
 216  * @param name name of the JSON field
 217  * @param[out] u8 where to store the integer found under @a name
 218  */
 219 struct GNUNET_JSON_Specification
 220 GNUNET_JSON_spec_uint8 (const char *name,
 221                         uint8_t *u8);
 222
 223
 224 /**
 225  * 16-bit integer.
 226  *
 227  * @param name name of the JSON field
 228  * @param[out] u16 where to store the integer found under @a name
 229  */
 230 struct GNUNET_JSON_Specification
 231 GNUNET_JSON_spec_uint16 (const char *name,
 232                          uint16_t *u16);
 233
 234
 235 /**
 236  * 32-bit integer.
 237  *
 238  * @param name name of the JSON field
 239  * @param[out] u32 where to store the integer found under @a name
 240  */
 241 struct GNUNET_JSON_Specification
 242 GNUNET_JSON_spec_uint32 (const char *name,
 243                          uint32_t *u32);
 244
 245
 246 /**
 247  * 64-bit integer.
 248  *
 249  * @param name name of the JSON field
 250  * @param[out] u64 where to store the integer found under @a name
 251  */
 252 struct GNUNET_JSON_Specification
 253 GNUNET_JSON_spec_uint64 (const char *name,
 254                          uint64_t *u64);
 255
 256 /**
 257  * Boolean (true mapped to GNUNET_YES, false mapped to GNUNET_NO).
 258  *
 259  * @param name name of the JSON field
 260  * @param[out] boolean where to store the boolean found under @a name
 261  */
 262 struct GNUNET_JSON_Specification
 263 GNUNET_JSON_spec_boolean (const char *name,
 264                           int *boolean);
 265
 266
 267 /* ************ GNUnet-specific parser specifications ******************* */
 268
 269 /**
 270  * Absolute time.
 271  *
 272  * @param name name of the JSON field
 273  * @param[out] at where to store the absolute time found under @a name
 274  */
 275 struct GNUNET_JSON_Specification
 276 GNUNET_JSON_spec_absolute_time (const char *name,
 277                                 struct GNUNET_TIME_Absolute *at);
 278
 279
 280 /**
 281  * Absolute time in network byte order.
 282  *
 283  * @param name name of the JSON field
 284  * @param[out] at where to store the absolute time found under @a name
 285  */
 286 struct GNUNET_JSON_Specification
 287 GNUNET_JSON_spec_absolute_time_nbo (const char *name,
 288                                     struct GNUNET_TIME_AbsoluteNBO *at);
 289
 290
 291 /**
 292  * Relative time.
 293  *
 294  * @param name name of the JSON field
 295  * @param[out] rt where to store the relative time found under @a name
 296  */
 297 struct GNUNET_JSON_Specification
 298 GNUNET_JSON_spec_relative_time (const char *name,
 299                                 struct GNUNET_TIME_Relative *rt);
 300
 301
 302 /**
 303  * Specification for parsing an RSA public key.
 304  *
 305  * @param name name of the JSON field
 306  * @param pk where to store the RSA key found under @a name
 307  */
 308 struct GNUNET_JSON_Specification
 309 GNUNET_JSON_spec_rsa_public_key (const char *name,
 310                                  struct GNUNET_CRYPTO_RsaPublicKey **pk);
 311
 312
 313 /**
 314  * Specification for parsing an RSA signature.
 315  *
 316  * @param name name of the JSON field
 317  * @param sig where to store the RSA signature found under @a name
 318  */
 319 struct GNUNET_JSON_Specification
 320 GNUNET_JSON_spec_rsa_signature (const char *name,
 321                                 struct GNUNET_CRYPTO_RsaSignature **sig);
 322
 323
 324
 325 /**
 326  * JSON Specification for GNS Records.
 327  *
 328  * @param gnsrecord_object struct of GNUNET_GNSRECORD_Data to fill
 329  * @return JSON Specification
 330  */
 331 struct GNUNET_JSON_Specification
 332 GNUNET_JSON_spec_gnsrecord_data (struct GNUNET_GNSRECORD_Data **gnsrecord_object);
 333
 334
 335 /* ****************** Generic generator interface ******************* */
 336
 337
 338 /**
 339  * Convert binary data to a JSON string with the base32crockford
 340  * encoding.
 341  *
 342  * @param data binary data
 343  * @param size size of @a data in bytes
 344  * @return json string that encodes @a data
 345  */
 346 json_t *
 347 GNUNET_JSON_from_data (const void *data,
 348                        size_t size);
 349
 350
 351 /**
 352  * Convert binary data to a JSON string with the base32crockford
 353  * encoding.
 354  *
 355  * @param ptr binary data, sizeof (*ptr) must yield correct size
 356  * @return json string that encodes @a data
 357  */
 358 #define GNUNET_JSON_from_data_auto(ptr) GNUNET_JSON_from_data(ptr, sizeof (*ptr))
 359
 360
 361 /**
 362  * Convert absolute timestamp to a json string.
 363  *
 364  * @param stamp the time stamp
 365  * @return a json string with the timestamp in @a stamp
 366  */
 367 json_t *
 368 GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp);
 369
 370
 371 /**
 372  * Convert absolute timestamp to a json string.
 373  *
 374  * @param stamp the time stamp
 375  * @return a json string with the timestamp in @a stamp
 376  */
 377 json_t *
 378 GNUNET_JSON_from_time_abs_nbo (struct GNUNET_TIME_AbsoluteNBO stamp);
 379
 380
 381 /**
 382  * Convert relative timestamp to a json string.
 383  *
 384  * @param stamp the time stamp
 385  * @return a json string with the timestamp in @a stamp
 386  */
 387 json_t *
 388 GNUNET_JSON_from_time_rel (struct GNUNET_TIME_Relative stamp);
 389
 390
 391 /**
 392  * Convert RSA public key to JSON.
 393  *
 394  * @param pk public key to convert
 395  * @return corresponding JSON encoding
 396  */
 397 json_t *
 398 GNUNET_JSON_from_rsa_public_key (const struct GNUNET_CRYPTO_RsaPublicKey *pk);
 399
 400
 401 /**
 402  * Convert RSA signature to JSON.
 403  *
 404  * @param sig signature to convert
 405  * @return corresponding JSON encoding
 406  */
 407 json_t *
 408 GNUNET_JSON_from_rsa_signature (const struct GNUNET_CRYPTO_RsaSignature *sig);
 409
 410 /**
 411  * Convert Gns record to JSON.
 412  *
 413  * @param rname name of record
 414  * @param rd record data
 415  * @return corresponding JSON encoding
 416  */
 417 json_t *
 418 GNUNET_JSON_from_gns_record (const char* rname,
 419                                 const struct GNUNET_GNSRECORD_Data *rd);
 420
 421 /* ******************* Helpers for MHD upload handling ******************* */
 422
 423 /**
 424  * Return codes from #GNUNET_JSON_post_parser().
 425  */
 426 enum GNUNET_JSON_PostResult {
 427   /**
 428    * Parsing successful, JSON result is in `*json`.
 429    */
 430   GNUNET_JSON_PR_SUCCESS,
 431
 432   /**
 433    * Parsing continues, call again soon!
 434    */
 435   GNUNET_JSON_PR_CONTINUE,
 436
 437   /**
 438    * Sorry, memory allocation (malloc()) failed.
 439    */
 440   GNUNET_JSON_PR_OUT_OF_MEMORY,
 441
 442   /**
 443    * Request size exceeded `buffer_max` argument.
 444    */
 445   GNUNET_JSON_PR_REQUEST_TOO_LARGE,
 446
 447   /**
 448    * JSON parsing failed. This was not a JSON upload.
 449    */
 450   GNUNET_JSON_PR_JSON_INVALID
 451 };
 452
 453
 454 /**
 455  * Process a POST request containing a JSON object.  This function
 456  * realizes an MHD POST processor that will (incrementally) process
 457  * JSON data uploaded to the HTTP server.  It will store the required
 458  * state in the @a con_cls, which must be cleaned up using
 459  * #GNUNET_JSON_post_parser_callback().
 460  *
 461  * @param buffer_max maximum allowed size for the buffer
 462  * @param con_cls the closure (will point to a `struct Buffer *`)
 463  * @param upload_data the POST data
 464  * @param upload_data_size number of bytes in @a upload_data
 465  * @param json the JSON object for a completed request
 466  * @return result code indicating the status of the operation
 467  */
 468 enum GNUNET_JSON_PostResult
 469 GNUNET_JSON_post_parser (size_t buffer_max,
 470                          void **con_cls,
 471                          const char *upload_data,
 472                          size_t *upload_data_size,
 473                          json_t **json);
 474
 475
 476 /**
 477  * Function called whenever we are done with a request
 478  * to clean up our state.
 479  *
 480  * @param con_cls value as it was left by
 481  *        #GNUNET_JSON_post_parser(), to be cleaned up
 482  */
 483 void
 484 GNUNET_JSON_post_parser_cleanup (void *con_cls);
 485
 486
 487 /* ****************** GETOPT JSON helper ******************* */
 488
 489
 490 /**
 491  * Allow user to specify a JSON input value.
 492  *
 493  * @param shortName short name of the option
 494  * @param name long name of the option
 495  * @param argumentHelp help text for the option argument
 496  * @param description long help text for the option
 497  * @param[out] val set to the JSON specified at the command line
 498  */
 499 struct GNUNET_GETOPT_CommandLineOption
 500 GNUNET_JSON_getopt (char shortName,
 501                     const char *name,
 502                     const char *argumentHelp,
 503                     const char *description,
 504                     json_t **json);
 505
 506 #endif
 507
 508 /* end of gnunet_json_lib.h */