1 files changed, 138 insertions, 5 deletions

diff --git a/src/include/gnunet_json_lib.h b/src/include/gnunet_json_lib.h
index 2002a0130..203976b5c 100644
--- a/src/include/gnunet_json_lib.h
+++ b/src/include/gnunet_json_lib.h
@@ -27,6 +27,7 @@
 #ifndef GNUNET_JSON_LIB_H
 #define GNUNET_JSON_LIB_H
 
+
 #include "gnunet_util_lib.h"
 #include <jansson.h>
 #include <microhttpd.h>
@@ -129,7 +130,7 @@ struct GNUNET_JSON_Specification
  * @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
+ * @param[out] error_line which index into @a spec did we encounter an error
  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
  */
 enum GNUNET_GenericReturnValue
@@ -141,7 +142,13 @@ GNUNET_JSON_parse (const json_t *root,
 
 /**
  * Frees all elements allocated during a #GNUNET_JSON_parse()
- * operation.
+ * operation.  Convenience function to be called if cleaning
+ * up all heap-allocated data from a #GNUNET_JSON_parse() is
+ * desired. The function does not have to be called if no data
+ * was heap-allocated (e.g. only integers, strings and fixed-sized
+ * data was used), or if the application calls the respective
+ * code to free the heap (not always #GNUNET_free(), depends
+ * on the data type!) on the returned heap-allocated data itself.
  *
  * @param spec specification of the parse operation
  */
@@ -197,6 +204,29 @@ GNUNET_JSON_spec_fixed (const char *name,
 
 
 /**
+ * Variable size object (in network byte order, encoded using base64 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_fixed64 (const char *name,
+                          void *obj,
+                          size_t size);
+
+
+/**
+ * Fixed size object (in network byte order, encoded using base64 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_fixed64_auto(name, obj) \
+  GNUNET_JSON_spec_fixed (name, obj, sizeof(*obj))
+
+
+/**
  * Variable size object (in network byte order, encoded using
  * Crockford Base32hex encoding).
  *
@@ -222,7 +252,8 @@ GNUNET_JSON_spec_string (const char *name,
 
 
 /**
- * JSON object.
+ * JSON object or array. Reference counter is
+ * incremented.
  *
  * @param name name of the JSON field
  * @param[out] jsonp where to store the JSON found under @a name
@@ -233,6 +264,28 @@ GNUNET_JSON_spec_json (const char *name,
 
 
 /**
+ * JSON object, reference counter not incremented.
+ *
+ * @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_object_const (const char *name,
+                               const json_t **jsonp);
+
+
+/**
+ * JSON array, reference counter not incremented.
+ *
+ * @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_array_const (const char *name,
+                              const json_t **jsonp);
+
+
+/**
  * boolean.
  *
  * @param name name of the JSON field
@@ -244,6 +297,17 @@ GNUNET_JSON_spec_bool (const char *name,
 
 
 /**
+ * double.
+ *
+ * @param name name of the JSON field
+ * @param[out] f where to store the double found under @a name
+ */
+struct GNUNET_JSON_Specification
+GNUNET_JSON_spec_double (const char *name,
+                         double *f);
+
+
+/**
  * 8-bit integer.
  *
  * @param name name of the JSON field
@@ -315,7 +379,7 @@ GNUNET_JSON_spec_boolean (const char *name,
  * Timestamp.
  *
  * @param name name of the JSON field
- * @param[out] at where to store the absolute time found under @a name
+ * @param[out] t at where to store the absolute time found under @a name
  */
 struct GNUNET_JSON_Specification
 GNUNET_JSON_spec_timestamp (const char *name,
@@ -378,7 +442,21 @@ GNUNET_JSON_spec_rsa_signature (const char *name,
  * @return json string that encodes @a data
  */
 json_t *
-GNUNET_JSON_from_data (const void *data, size_t size);
+GNUNET_JSON_from_data (const void *data,
+                       size_t size);
+
+
+/**
+ * Convert binary data to a JSON string with base64
+ * 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_data64 (const void *data,
+                         size_t size);
 
 
 /**
@@ -393,6 +471,17 @@ GNUNET_JSON_from_data (const void *data, size_t size);
 
 
 /**
+ * Convert binary data to a JSON string with base64
+ * encoding.
+ *
+ * @param ptr binary data, sizeof (*ptr) must yield correct size
+ * @return json string that encodes @a data
+ */
+#define GNUNET_JSON_from_data64_auto(ptr) \
+  GNUNET_JSON_from_data64 (ptr, sizeof(*ptr))
+
+
+/**
  * Convert timestamp to a json string.
  *
  * @param stamp the time stamp
@@ -632,6 +721,19 @@ GNUNET_JSON_pack_bool (const char *name,
 
 /**
  * Generate packer instruction for a JSON field of type
+ * double.
+ *
+ * @param name name of the field to add to the object
+ * @param f double value
+ * @return json pack specification
+ */
+struct GNUNET_JSON_PackSpec
+GNUNET_JSON_pack_double (const char *name,
+                         double f);
+
+
+/**
+ * Generate packer instruction for a JSON field of type
  * string.
  *
  * @param name name of the field to add to the object
@@ -755,6 +857,37 @@ GNUNET_JSON_pack_data_varsize (const char *name,
 
 /**
  * Generate packer instruction for a JSON field of type
+ * variable size binary blob.
+ * Use base64-encoding, instead of the more common
+ * Crockford base32-encoding.
+ *
+ * @param name name of the field to add to the object
+ * @param blob binary data to pack
+ * @param blob_size number of bytes in @a blob
+ * @return json pack specification
+ */
+struct GNUNET_JSON_PackSpec
+GNUNET_JSON_pack_data64_varsize (const char *name,
+                                 const void *blob,
+                                 size_t blob_size);
+
+
+/**
+ * Generate packer instruction for a JSON field where the
+ * size is automatically determined from the argument.
+ * Use base64-encoding, instead of the more common
+ * Crockford base32-encoding.
+ *
+ * @param name name of the field to add to the object
+ * @param blob data to pack, must not be an array
+ * @return json pack specification
+ */
+#define GNUNET_JSON_pack_data64_auto(name,blob) \
+  GNUNET_JSON_pack_data64_varsize (name, blob, sizeof (*blob))
+
+
+/**
+ * Generate packer instruction for a JSON field of type
  * timestamp.
  *
  * @param name name of the field to add to the object