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