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/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  * Relative time.
 267  *
 268  * @param name name of the JSON field
 269  * @param[out] rt where to store the relative time found under @a name
 270  */
 271 struct GNUNET_JSON_Specification
 272 GNUNET_JSON_spec_relative_time (const char *name,
 273                                 struct GNUNET_TIME_Relative *rt);
 274
 275
 276 /**
 277  * Specification for parsing an RSA public key.
 278  *
 279  * @param name name of the JSON field
 280  * @param pk where to store the RSA key found under @a name
 281  */
 282 struct GNUNET_JSON_Specification
 283 GNUNET_JSON_spec_rsa_public_key (const char *name,
 284                                  struct GNUNET_CRYPTO_rsa_PublicKey **pk);
 285
 286
 287 /**
 288  * Specification for parsing an RSA signature.
 289  *
 290  * @param name name of the JSON field
 291  * @param sig where to store the RSA signature found under @a name
 292  */
 293 struct GNUNET_JSON_Specification
 294 GNUNET_JSON_spec_rsa_signature (const char *name,
 295                                 struct GNUNET_CRYPTO_rsa_Signature **sig);
 296
 297
 298 /* ****************** Generic generator interface ******************* */
 299
 300
 301 /**
 302  * Convert binary data to a JSON string with the base32crockford
 303  * encoding.
 304  *
 305  * @param data binary data
 306  * @param size size of @a data in bytes
 307  * @return json string that encodes @a data
 308  */
 309 json_t *
 310 GNUNET_JSON_from_data (const void *data,
 311                        size_t size);
 312
 313
 314 /**
 315  * Convert absolute timestamp to a json string.
 316  *
 317  * @param stamp the time stamp
 318  * @return a json string with the timestamp in @a stamp
 319  */
 320 json_t *
 321 GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp);
 322
 323
 324 /**
 325  * Convert relative timestamp to a json string.
 326  *
 327  * @param stamp the time stamp
 328  * @return a json string with the timestamp in @a stamp
 329  */
 330 json_t *
 331 GNUNET_JSON_from_time_rel (struct GNUNET_TIME_Relative stamp);
 332
 333
 334 /**
 335  * Convert RSA public key to JSON.
 336  *
 337  * @param pk public key to convert
 338  * @return corresponding JSON encoding
 339  */
 340 json_t *
 341 GNUNET_JSON_from_rsa_public_key (const struct GNUNET_CRYPTO_rsa_PublicKey *pk);
 342
 343
 344 /**
 345  * Convert RSA signature to JSON.
 346  *
 347  * @param sig signature to convert
 348  * @return corresponding JSON encoding
 349  */
 350 json_t *
 351 GNUNET_JSON_from_rsa_signature (const struct GNUNET_CRYPTO_rsa_Signature *sig);
 352
 353
 354 #endif
 355
 356 /* end of gnunet_json_lib.h */