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