adding library for basic JSON conversions

1 files changed, 354 insertions, 0 deletions

diff --git a/src/include/gnunet_json_lib.h b/src/include/gnunet_json_lib.h
new file mode 100644
index 000000000..e39938858
--- /dev/null
+++ b/src/include/gnunet_json_lib.h
@@ -0,0 +1,354 @@
+/*
+  This file is part of GNUnet
+  Copyright (C) 2014, 2015, 2016 GNUnet e.V.
+
+  GNUnet is free software; you can redistribute it and/or modify it under the
+  terms of the GNU General Public License as published by the Free Software
+  Foundation; either version 3, or (at your option) any later version.
+
+  GNUnet is distributed in the hope that it will be useful, but WITHOUT ANY
+  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+  A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License along with
+  GNUnet; see the file COPYING.  If not, If not, see <http://www.gnu.org/licenses/>
+*/
+/**
+ * @file gnunet_json_lib.h
+ * @brief functions to parse JSON objects into GNUnet objects
+ * @author Florian Dold
+ * @author Benedikt Mueller
+ * @author Christian Grothoff
+ */
+#include "platform.h"
+#include <gnunet/gnunet_util_lib.h>
+#include <jansson.h>
+
+
+/* ****************** Generic parser interface ******************* */
+
+/**
+ * @brief Entry in parser specification for #GNUNET_JSON_parse().
+ */
+struct GNUNET_JSON_Specification;
+
+
+/**
+ * Function called to parse JSON argument.
+ *
+ * @param cls closure
+ * @param root JSON to parse
+ * @param spec our specification entry with further details
+ * @return #GNUNET_SYSERR on error,
+ *         #GNUNET_OK on success
+ */
+typedef int
+(*GNUNET_JSON_Parser)(void *cls,
+                      json_t *root,
+                      struct GNUNET_JSON_Specification *spec);
+
+
+/**
+ * Function called to clean up data from earlier parsing.
+ *
+ * @param cls closure
+ * @param spec our specification entry with data to clean.
+ */
+typedef void
+(*GNUNET_JSON_Cleaner)(void *cls,
+                       struct GNUNET_JSON_Specification *spec);
+
+
+/**
+ * @brief Entry in parser specification for #GNUNET_JSON_parse().
+ */
+struct GNUNET_JSON_Specification
+{
+  /**
+   * Function for how to parse this type of entry.
+   */
+  GNUNET_JSON_Parser parser;
+
+  /**
+   * Function for how to clean up this type of entry.
+   */
+  GNUNET_JSON_Cleaner cleaner;
+
+  /**
+   * Closure for @e parser and @e cleaner.
+   */
+  void *cls;
+
+  /**
+   * Name of the field to parse, use NULL to get the JSON
+   * of the main object instead of the JSON of an individual field.
+   */
+  const char *field;
+
+  /**
+   * Pointer, details specific to the @e parser.
+   */
+  void *ptr;
+
+  /**
+   * Number of bytes available in @e ptr.
+   */
+  size_t ptr_size;
+
+  /**
+   * Where should we store the final size of @e ptr.
+   */
+  size_t *size_ptr;
+
+};
+
+
+/**
+ * Navigate and parse data in a JSON tree.  Tries to parse the @a root
+ * to find all of the values given in the @a spec.  If one of the
+ * entries in @a spec cannot be found or parsed, the name of the JSON
+ * field is returned in @a error_json_name, and the offset of the
+ * entry in @a spec is returned in @a error_line.
+ *
+ * @param root the JSON node to start the navigation at.
+ * @param spec parse specification array
+ * @param[out] error_json_name which JSON field was problematic
+ * @param[out] which index into @a spec did we encounter an error
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
+ */
+int
+GNUNET_JSON_parse (const json_t *root,
+                   struct GNUNET_JSON_Specification *spec,
+                   const char **error_json_name,
+                   unsigned int *error_line);
+
+
+/**
+ * Frees all elements allocated during a #GNUNET_JSON_parse()
+ * operation.
+ *
+ * @param spec specification of the parse operation
+ */
+void
+GNUNET_JSON_parse_free (struct GNUNET_JSON_Specification *spec);
+
+
+
+/* ****************** Canonical parser specifications ******************* */
+
+
+/**
+ * End of a parser specification.
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_end (void);
+
+
+/**
+ * Variable size object (in network byte order, encoded using Crockford
+ * Base32hex encoding).
+ *
+ * @param name name of the JSON field
+ * @param[out] obj pointer where to write the data, must have @a size bytes
+ * @param size number of bytes expected in @a obj
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_fixed (const char *name,
+                        void *obj,
+                        size_t size);
+
+
+/**
+ * Fixed size object (in network byte order, encoded using Crockford
+ * Base32hex encoding).
+ *
+ * @param name name of the JSON field
+ * @param obj pointer where to write the data (type of `*obj` will determine size)
+ */
+#define GNUNET_JSON_spec_fixed_auto(name,obj) GNUNET_JSON_spec_fixed (name, obj, sizeof (*obj))
+
+
+/**
+ * Variable size object (in network byte order, encoded using
+ * Crockford Base32hex encoding).
+ *
+ * @param name name of the JSON field
+ * @param[out] obj pointer where to write the data, will be allocated
+ * @param[out] size where to store the number of bytes allocated for @a obj
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_varsize (const char *name,
+                          void **obj,
+                          size_t *size);
+
+
+/**
+ * The expected field stores a string.
+ *
+ * @param name name of the JSON field
+ * @param strptr where to store a pointer to the field
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_string (const char *name,
+                         const char **strptr);
+
+/**
+ * JSON object.
+ *
+ * @param name name of the JSON field
+ * @param[out] jsonp where to store the JSON found under @a name
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_json (const char *name,
+                       json_t **jsonp);
+
+
+/**
+ * 8-bit integer.
+ *
+ * @param name name of the JSON field
+ * @param[out] u8 where to store the integer found under @a name
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_uint8 (const char *name,
+                        uint8_t *u8);
+
+
+/**
+ * 16-bit integer.
+ *
+ * @param name name of the JSON field
+ * @param[out] u16 where to store the integer found under @a name
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_uint16 (const char *name,
+                         uint16_t *u16);
+
+
+/**
+ * 32-bit integer.
+ *
+ * @param name name of the JSON field
+ * @param[out] u32 where to store the integer found under @a name
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_uint32 (const char *name,
+                         uint32_t *u32);
+
+
+/**
+ * 64-bit integer.
+ *
+ * @param name name of the JSON field
+ * @param[out] u64 where to store the integer found under @a name
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_uint64 (const char *name,
+                         uint64_t *u64);
+
+
+/* ************ GNUnet-specific parser specifications ******************* */
+
+/**
+ * Absolute time.
+ *
+ * @param name name of the JSON field
+ * @param[out] at where to store the absolute time found under @a name
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_absolute_time (const char *name,
+                                struct GNUNET_TIME_Absolute *at);
+
+
+/**
+ * Relative time.
+ *
+ * @param name name of the JSON field
+ * @param[out] rt where to store the relative time found under @a name
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_relative_time (const char *name,
+                                struct GNUNET_TIME_Relative *rt);
+
+
+/**
+ * Specification for parsing an RSA public key.
+ *
+ * @param name name of the JSON field
+ * @param pk where to store the RSA key found under @a name
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_rsa_public_key (const char *name,
+                                 struct GNUNET_CRYPTO_rsa_PublicKey **pk);
+
+
+/**
+ * Specification for parsing an RSA signature.
+ *
+ * @param name name of the JSON field
+ * @param sig where to store the RSA signature found under @a name
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_rsa_signature (const char *name,
+                                struct GNUNET_CRYPTO_rsa_Signature **sig);
+
+
+/* ****************** Generic generator interface ******************* */
+
+
+/**
+ * Convert binary data to a JSON string with the base32crockford
+ * encoding.
+ *
+ * @param data binary data
+ * @param size size of @a data in bytes
+ * @return json string that encodes @a data
+ */
+json_t *
+GNUNET_JSON_from_data (const void *data,
+                       size_t size);
+
+
+/**
+ * Convert absolute timestamp to a json string.
+ *
+ * @param stamp the time stamp
+ * @return a json string with the timestamp in @a stamp
+ */
+json_t *
+GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp);
+
+
+/**
+ * Convert relative timestamp to a json string.
+ *
+ * @param stamp the time stamp
+ * @return a json string with the timestamp in @a stamp
+ */
+json_t *
+GNUNET_JSON_from_time_rel (struct GNUNET_TIME_Relative stamp);
+
+
+/**
+ * Convert RSA public key to JSON.
+ *
+ * @param pk public key to convert
+ * @return corresponding JSON encoding
+ */
+json_t *
+GNUNET_JSON_from_rsa_public_key (const struct GNUNET_CRYPTO_rsa_PublicKey *pk);
+
+
+/**
+ * Convert RSA signature to JSON.
+ *
+ * @param sig signature to convert
+ * @return corresponding JSON encoding
+ */
+json_t *
+GNUNET_JSON_from_rsa_signature (const struct GNUNET_CRYPTO_rsa_Signature *sig);
+
+
+
+
+/* end of gnunet_json_lib.h */