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 #include "platform.h"
  24 #include <gnunet/gnunet_util_lib.h>
  25 #include <jansson.h>
  26
  27
  28 /* ****************** Generic parser interface ******************* */
  29
  30 /**
  31  * @brief Entry in parser specification for #GNUNET_JSON_parse().
  32  */
  33 struct GNUNET_JSON_Specification;
  34
  35
  36 /**
  37  * Function called to parse JSON argument.
  38  *
  39  * @param cls closure
  40  * @param root JSON to parse
  41  * @param spec our specification entry with further details
  42  * @return #GNUNET_SYSERR on error,
  43  *         #GNUNET_OK on success
  44  */
  45 typedef int
  46 (*GNUNET_JSON_Parser)(void *cls,
  47                       json_t *root,
  48                       struct GNUNET_JSON_Specification *spec);
  49
  50
  51 /**
  52  * Function called to clean up data from earlier parsing.
  53  *
  54  * @param cls closure
  55  * @param spec our specification entry with data to clean.
  56  */
  57 typedef void
  58 (*GNUNET_JSON_Cleaner)(void *cls,
  59                        struct GNUNET_JSON_Specification *spec);
  60
  61
  62 /**
  63  * @brief Entry in parser specification for #GNUNET_JSON_parse().
  64  */
  65 struct GNUNET_JSON_Specification
  66 {
  67   /**
  68    * Function for how to parse this type of entry.
  69    */
  70   GNUNET_JSON_Parser parser;
  71
  72   /**
  73    * Function for how to clean up this type of entry.
  74    */
  75   GNUNET_JSON_Cleaner cleaner;
  76
  77   /**
  78    * Closure for @e parser and @e cleaner.
  79    */
  80   void *cls;
  81
  82   /**
  83    * Name of the field to parse, use NULL to get the JSON
  84    * of the main object instead of the JSON of an individual field.
  85    */
  86   const char *field;
  87
  88   /**
  89    * Pointer, details specific to the @e parser.
  90    */
  91   void *ptr;
  92
  93   /**
  94    * Number of bytes available in @e ptr.
  95    */
  96   size_t ptr_size;
  97
  98   /**
  99    * Where should we store the final size of @e ptr.
 100    */
 101   size_t *size_ptr;
 102
 103 };
 104
 105
 106 /**
 107  * Navigate and parse data in a JSON tree.  Tries to parse the @a root
 108  * to find all of the values given in the @a spec.  If one of the
 109  * entries in @a spec cannot be found or parsed, the name of the JSON
 110  * field is returned in @a error_json_name, and the offset of the
 111  * entry in @a spec is returned in @a error_line.
 112  *
 113  * @param root the JSON node to start the navigation at.
 114  * @param spec parse specification array
 115  * @param[out] error_json_name which JSON field was problematic
 116  * @param[out] which index into @a spec did we encounter an error
 117  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 118  */
 119 int
 120 GNUNET_JSON_parse (const json_t *root,
 121                    struct GNUNET_JSON_Specification *spec,
 122                    const char **error_json_name,
 123                    unsigned int *error_line);
 124
 125
 126 /**
 127  * Frees all elements allocated during a #GNUNET_JSON_parse()
 128  * operation.
 129  *
 130  * @param spec specification of the parse operation
 131  */
 132 void
 133 GNUNET_JSON_parse_free (struct GNUNET_JSON_Specification *spec);
 134
 135
 136
 137 /* ****************** Canonical parser specifications ******************* */
 138
 139
 140 /**
 141  * End of a parser specification.
 142  */
 143 struct GNUNET_JSON_Specification
 144 GNUNET_JSON_spec_end (void);
 145
 146
 147 /**
 148  * Variable size object (in network byte order, encoded using Crockford
 149  * Base32hex encoding).
 150  *
 151  * @param name name of the JSON field
 152  * @param[out] obj pointer where to write the data, must have @a size bytes
 153  * @param size number of bytes expected in @a obj
 154  */
 155 struct GNUNET_JSON_Specification
 156 GNUNET_JSON_spec_fixed (const char *name,
 157                         void *obj,
 158                         size_t size);
 159
 160
 161 /**
 162  * Fixed size object (in network byte order, encoded using Crockford
 163  * Base32hex encoding).
 164  *
 165  * @param name name of the JSON field
 166  * @param obj pointer where to write the data (type of `*obj` will determine size)
 167  */
 168 #define GNUNET_JSON_spec_fixed_auto(name,obj) GNUNET_JSON_spec_fixed (name, obj, sizeof (*obj))
 169
 170
 171 /**
 172  * Variable size object (in network byte order, encoded using
 173  * Crockford Base32hex encoding).
 174  *
 175  * @param name name of the JSON field
 176  * @param[out] obj pointer where to write the data, will be allocated
 177  * @param[out] size where to store the number of bytes allocated for @a obj
 178  */
 179 struct GNUNET_JSON_Specification
 180 GNUNET_JSON_spec_varsize (const char *name,
 181                           void **obj,
 182                           size_t *size);
 183
 184
 185 /**
 186  * The expected field stores a string.
 187  *
 188  * @param name name of the JSON field
 189  * @param strptr where to store a pointer to the field
 190  */
 191 struct GNUNET_JSON_Specification
 192 GNUNET_JSON_spec_string (const char *name,
 193                          const char **strptr);
 194
 195 /**
 196  * JSON object.
 197  *
 198  * @param name name of the JSON field
 199  * @param[out] jsonp where to store the JSON found under @a name
 200  */
 201 struct GNUNET_JSON_Specification
 202 GNUNET_JSON_spec_json (const char *name,
 203                        json_t **jsonp);
 204
 205
 206 /**
 207  * 8-bit integer.
 208  *
 209  * @param name name of the JSON field
 210  * @param[out] u8 where to store the integer found under @a name
 211  */
 212 struct GNUNET_JSON_Specification
 213 GNUNET_JSON_spec_uint8 (const char *name,
 214                         uint8_t *u8);
 215
 216
 217 /**
 218  * 16-bit integer.
 219  *
 220  * @param name name of the JSON field
 221  * @param[out] u16 where to store the integer found under @a name
 222  */
 223 struct GNUNET_JSON_Specification
 224 GNUNET_JSON_spec_uint16 (const char *name,
 225                          uint16_t *u16);
 226
 227
 228 /**
 229  * 32-bit integer.
 230  *
 231  * @param name name of the JSON field
 232  * @param[out] u32 where to store the integer found under @a name
 233  */
 234 struct GNUNET_JSON_Specification
 235 GNUNET_JSON_spec_uint32 (const char *name,
 236                          uint32_t *u32);
 237
 238
 239 /**
 240  * 64-bit integer.
 241  *
 242  * @param name name of the JSON field
 243  * @param[out] u64 where to store the integer found under @a name
 244  */
 245 struct GNUNET_JSON_Specification
 246 GNUNET_JSON_spec_uint64 (const char *name,
 247                          uint64_t *u64);
 248
 249
 250 /* ************ GNUnet-specific parser specifications ******************* */
 251
 252 /**
 253  * Absolute time.
 254  *
 255  * @param name name of the JSON field
 256  * @param[out] at where to store the absolute time found under @a name
 257  */
 258 struct GNUNET_JSON_Specification
 259 GNUNET_JSON_spec_absolute_time (const char *name,
 260                                 struct GNUNET_TIME_Absolute *at);
 261
 262
 263 /**
 264  * Relative time.
 265  *
 266  * @param name name of the JSON field
 267  * @param[out] rt where to store the relative time found under @a name
 268  */
 269 struct GNUNET_JSON_Specification
 270 GNUNET_JSON_spec_relative_time (const char *name,
 271                                 struct GNUNET_TIME_Relative *rt);
 272
 273
 274 /**
 275  * Specification for parsing an RSA public key.
 276  *
 277  * @param name name of the JSON field
 278  * @param pk where to store the RSA key found under @a name
 279  */
 280 struct GNUNET_JSON_Specification
 281 GNUNET_JSON_spec_rsa_public_key (const char *name,
 282                                  struct GNUNET_CRYPTO_rsa_PublicKey **pk);
 283
 284
 285 /**
 286  * Specification for parsing an RSA signature.
 287  *
 288  * @param name name of the JSON field
 289  * @param sig where to store the RSA signature found under @a name
 290  */
 291 struct GNUNET_JSON_Specification
 292 GNUNET_JSON_spec_rsa_signature (const char *name,
 293                                 struct GNUNET_CRYPTO_rsa_Signature **sig);
 294
 295
 296 /* ****************** Generic generator interface ******************* */
 297
 298
 299 /**
 300  * Convert binary data to a JSON string with the base32crockford
 301  * encoding.
 302  *
 303  * @param data binary data
 304  * @param size size of @a data in bytes
 305  * @return json string that encodes @a data
 306  */
 307 json_t *
 308 GNUNET_JSON_from_data (const void *data,
 309                        size_t size);
 310
 311
 312 /**
 313  * Convert absolute timestamp to a json string.
 314  *
 315  * @param stamp the time stamp
 316  * @return a json string with the timestamp in @a stamp
 317  */
 318 json_t *
 319 GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp);
 320
 321
 322 /**
 323  * Convert relative timestamp to a json string.
 324  *
 325  * @param stamp the time stamp
 326  * @return a json string with the timestamp in @a stamp
 327  */
 328 json_t *
 329 GNUNET_JSON_from_time_rel (struct GNUNET_TIME_Relative stamp);
 330
 331
 332 /**
 333  * Convert RSA public key to JSON.
 334  *
 335  * @param pk public key to convert
 336  * @return corresponding JSON encoding
 337  */
 338 json_t *
 339 GNUNET_JSON_from_rsa_public_key (const struct GNUNET_CRYPTO_rsa_PublicKey *pk);
 340
 341
 342 /**
 343  * Convert RSA signature to JSON.
 344  *
 345  * @param sig signature to convert
 346  * @return corresponding JSON encoding
 347  */
 348 json_t *
 349 GNUNET_JSON_from_rsa_signature (const struct GNUNET_CRYPTO_rsa_Signature *sig);
 350
 351
 352
 353
 354 /* end of gnunet_json_lib.h */