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