aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_json_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_json_lib.h')
-rw-r--r--src/include/gnunet_json_lib.h203
1 files changed, 172 insertions, 31 deletions
diff --git a/src/include/gnunet_json_lib.h b/src/include/gnunet_json_lib.h
index 5ef4592e5..203976b5c 100644
--- a/src/include/gnunet_json_lib.h
+++ b/src/include/gnunet_json_lib.h
@@ -27,6 +27,7 @@
27#ifndef GNUNET_JSON_LIB_H 27#ifndef GNUNET_JSON_LIB_H
28#define GNUNET_JSON_LIB_H 28#define GNUNET_JSON_LIB_H
29 29
30
30#include "gnunet_util_lib.h" 31#include "gnunet_util_lib.h"
31#include <jansson.h> 32#include <jansson.h>
32#include <microhttpd.h> 33#include <microhttpd.h>
@@ -48,10 +49,10 @@ struct GNUNET_JSON_Specification;
48 * @return #GNUNET_SYSERR on error, 49 * @return #GNUNET_SYSERR on error,
49 * #GNUNET_OK on success 50 * #GNUNET_OK on success
50 */ 51 */
51typedef int 52typedef enum GNUNET_GenericReturnValue
52(*GNUNET_JSON_Parser) (void *cls, 53(*GNUNET_JSON_Parser)(void *cls,
53 json_t *root, 54 json_t *root,
54 struct GNUNET_JSON_Specification *spec); 55 struct GNUNET_JSON_Specification *spec);
55 56
56 57
57/** 58/**
@@ -97,9 +98,10 @@ struct GNUNET_JSON_Specification
97 void *ptr; 98 void *ptr;
98 99
99 /** 100 /**
100 * Number of bytes available in @e ptr. 101 * Pointer to set to true if this argument is
102 * indeed missing. Can be NULL.
101 */ 103 */
102 size_t ptr_size; 104 bool *missing;
103 105
104 /** 106 /**
105 * Where should we store the final size of @e ptr. 107 * Where should we store the final size of @e ptr.
@@ -107,6 +109,11 @@ struct GNUNET_JSON_Specification
107 size_t *size_ptr; 109 size_t *size_ptr;
108 110
109 /** 111 /**
112 * Number of bytes available in @e ptr.
113 */
114 size_t ptr_size;
115
116 /**
110 * Set to true if this component is optional. 117 * Set to true if this component is optional.
111 */ 118 */
112 bool is_optional; 119 bool is_optional;
@@ -123,7 +130,7 @@ struct GNUNET_JSON_Specification
123 * @param root the JSON node to start the navigation at. 130 * @param root the JSON node to start the navigation at.
124 * @param spec parse specification array 131 * @param spec parse specification array
125 * @param[out] error_json_name which JSON field was problematic 132 * @param[out] error_json_name which JSON field was problematic
126 * @param[out] which index into @a spec did we encounter an error 133 * @param[out] error_line which index into @a spec did we encounter an error
127 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 134 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
128 */ 135 */
129enum GNUNET_GenericReturnValue 136enum GNUNET_GenericReturnValue
@@ -135,7 +142,13 @@ GNUNET_JSON_parse (const json_t *root,
135 142
136/** 143/**
137 * Frees all elements allocated during a #GNUNET_JSON_parse() 144 * Frees all elements allocated during a #GNUNET_JSON_parse()
138 * operation. 145 * operation. Convenience function to be called if cleaning
146 * up all heap-allocated data from a #GNUNET_JSON_parse() is
147 * desired. The function does not have to be called if no data
148 * was heap-allocated (e.g. only integers, strings and fixed-sized
149 * data was used), or if the application calls the respective
150 * code to free the heap (not always #GNUNET_free(), depends
151 * on the data type!) on the returned heap-allocated data itself.
139 * 152 *
140 * @param spec specification of the parse operation 153 * @param spec specification of the parse operation
141 */ 154 */
@@ -157,10 +170,12 @@ GNUNET_JSON_spec_end (void);
157 * Set the "optional" flag for a parser specification entry. 170 * Set the "optional" flag for a parser specification entry.
158 * 171 *
159 * @param spec specification to modify 172 * @param spec specification to modify
173 * @param[out] missing set to true if the argument is missing, NULL is allowed.
160 * @return spec copy of @a spec with optional bit set 174 * @return spec copy of @a spec with optional bit set
161 */ 175 */
162struct GNUNET_JSON_Specification 176struct GNUNET_JSON_Specification
163GNUNET_JSON_spec_mark_optional (struct GNUNET_JSON_Specification spec); 177GNUNET_JSON_spec_mark_optional (struct GNUNET_JSON_Specification spec,
178 bool *missing);
164 179
165 180
166/** 181/**
@@ -189,6 +204,29 @@ GNUNET_JSON_spec_fixed (const char *name,
189 204
190 205
191/** 206/**
207 * Variable size object (in network byte order, encoded using base64 encoding).
208 *
209 * @param name name of the JSON field
210 * @param[out] obj pointer where to write the data, must have @a size bytes
211 * @param size number of bytes expected in @a obj
212 */
213struct GNUNET_JSON_Specification
214GNUNET_JSON_spec_fixed64 (const char *name,
215 void *obj,
216 size_t size);
217
218
219/**
220 * Fixed size object (in network byte order, encoded using base64 encoding).
221 *
222 * @param name name of the JSON field
223 * @param obj pointer where to write the data (type of `*obj` will determine size)
224 */
225#define GNUNET_JSON_spec_fixed64_auto(name, obj) \
226 GNUNET_JSON_spec_fixed (name, obj, sizeof(*obj))
227
228
229/**
192 * Variable size object (in network byte order, encoded using 230 * Variable size object (in network byte order, encoded using
193 * Crockford Base32hex encoding). 231 * Crockford Base32hex encoding).
194 * 232 *
@@ -214,7 +252,8 @@ GNUNET_JSON_spec_string (const char *name,
214 252
215 253
216/** 254/**
217 * JSON object. 255 * JSON object or array. Reference counter is
256 * incremented.
218 * 257 *
219 * @param name name of the JSON field 258 * @param name name of the JSON field
220 * @param[out] jsonp where to store the JSON found under @a name 259 * @param[out] jsonp where to store the JSON found under @a name
@@ -225,6 +264,28 @@ GNUNET_JSON_spec_json (const char *name,
225 264
226 265
227/** 266/**
267 * JSON object, reference counter not incremented.
268 *
269 * @param name name of the JSON field
270 * @param[out] jsonp where to store the JSON found under @a name
271 */
272struct GNUNET_JSON_Specification
273GNUNET_JSON_spec_object_const (const char *name,
274 const json_t **jsonp);
275
276
277/**
278 * JSON array, reference counter not incremented.
279 *
280 * @param name name of the JSON field
281 * @param[out] jsonp where to store the JSON found under @a name
282 */
283struct GNUNET_JSON_Specification
284GNUNET_JSON_spec_array_const (const char *name,
285 const json_t **jsonp);
286
287
288/**
228 * boolean. 289 * boolean.
229 * 290 *
230 * @param name name of the JSON field 291 * @param name name of the JSON field
@@ -236,6 +297,17 @@ GNUNET_JSON_spec_bool (const char *name,
236 297
237 298
238/** 299/**
300 * double.
301 *
302 * @param name name of the JSON field
303 * @param[out] f where to store the double found under @a name
304 */
305struct GNUNET_JSON_Specification
306GNUNET_JSON_spec_double (const char *name,
307 double *f);
308
309
310/**
239 * 8-bit integer. 311 * 8-bit integer.
240 * 312 *
241 * @param name name of the JSON field 313 * @param name name of the JSON field
@@ -304,25 +376,25 @@ GNUNET_JSON_spec_boolean (const char *name,
304/* ************ GNUnet-specific parser specifications ******************* */ 376/* ************ GNUnet-specific parser specifications ******************* */
305 377
306/** 378/**
307 * Absolute time. 379 * Timestamp.
308 * 380 *
309 * @param name name of the JSON field 381 * @param name name of the JSON field
310 * @param[out] at where to store the absolute time found under @a name 382 * @param[out] t at where to store the absolute time found under @a name
311 */ 383 */
312struct GNUNET_JSON_Specification 384struct GNUNET_JSON_Specification
313GNUNET_JSON_spec_absolute_time (const char *name, 385GNUNET_JSON_spec_timestamp (const char *name,
314 struct GNUNET_TIME_Absolute *at); 386 struct GNUNET_TIME_Timestamp *t);
315 387
316 388
317/** 389/**
318 * Absolute time in network byte order. 390 * Timestamp in network byte order.
319 * 391 *
320 * @param name name of the JSON field 392 * @param name name of the JSON field
321 * @param[out] at where to store the absolute time found under @a name 393 * @param[out] tn where to store the absolute time found under @a name
322 */ 394 */
323struct GNUNET_JSON_Specification 395struct GNUNET_JSON_Specification
324GNUNET_JSON_spec_absolute_time_nbo (const char *name, 396GNUNET_JSON_spec_timestamp_nbo (const char *name,
325 struct GNUNET_TIME_AbsoluteNBO *at); 397 struct GNUNET_TIME_TimestampNBO *tn);
326 398
327 399
328/** 400/**
@@ -370,7 +442,21 @@ GNUNET_JSON_spec_rsa_signature (const char *name,
370 * @return json string that encodes @a data 442 * @return json string that encodes @a data
371 */ 443 */
372json_t * 444json_t *
373GNUNET_JSON_from_data (const void *data, size_t size); 445GNUNET_JSON_from_data (const void *data,
446 size_t size);
447
448
449/**
450 * Convert binary data to a JSON string with base64
451 * encoding.
452 *
453 * @param data binary data
454 * @param size size of @a data in bytes
455 * @return json string that encodes @a data
456 */
457json_t *
458GNUNET_JSON_from_data64 (const void *data,
459 size_t size);
374 460
375 461
376/** 462/**
@@ -385,23 +471,34 @@ GNUNET_JSON_from_data (const void *data, size_t size);
385 471
386 472
387/** 473/**
388 * Convert absolute timestamp to a json string. 474 * Convert binary data to a JSON string with base64
475 * encoding.
476 *
477 * @param ptr binary data, sizeof (*ptr) must yield correct size
478 * @return json string that encodes @a data
479 */
480#define GNUNET_JSON_from_data64_auto(ptr) \
481 GNUNET_JSON_from_data64 (ptr, sizeof(*ptr))
482
483
484/**
485 * Convert timestamp to a json string.
389 * 486 *
390 * @param stamp the time stamp 487 * @param stamp the time stamp
391 * @return a json string with the timestamp in @a stamp 488 * @return a json string with the timestamp in @a stamp
392 */ 489 */
393json_t * 490json_t *
394GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp); 491GNUNET_JSON_from_timestamp (struct GNUNET_TIME_Timestamp stamp);
395 492
396 493
397/** 494/**
398 * Convert absolute timestamp to a json string. 495 * Convert timestamp to a json string.
399 * 496 *
400 * @param stamp the time stamp 497 * @param stamp the time stamp
401 * @return a json string with the timestamp in @a stamp 498 * @return a json string with the timestamp in @a stamp
402 */ 499 */
403json_t * 500json_t *
404GNUNET_JSON_from_time_abs_nbo (struct GNUNET_TIME_AbsoluteNBO stamp); 501GNUNET_JSON_from_timestamp_nbo (struct GNUNET_TIME_TimestampNBO stamp);
405 502
406 503
407/** 504/**
@@ -624,6 +721,19 @@ GNUNET_JSON_pack_bool (const char *name,
624 721
625/** 722/**
626 * Generate packer instruction for a JSON field of type 723 * Generate packer instruction for a JSON field of type
724 * double.
725 *
726 * @param name name of the field to add to the object
727 * @param f double value
728 * @return json pack specification
729 */
730struct GNUNET_JSON_PackSpec
731GNUNET_JSON_pack_double (const char *name,
732 double f);
733
734
735/**
736 * Generate packer instruction for a JSON field of type
627 * string. 737 * string.
628 * 738 *
629 * @param name name of the field to add to the object 739 * @param name name of the field to add to the object
@@ -747,30 +857,61 @@ GNUNET_JSON_pack_data_varsize (const char *name,
747 857
748/** 858/**
749 * Generate packer instruction for a JSON field of type 859 * Generate packer instruction for a JSON field of type
750 * absolute time. 860 * variable size binary blob.
861 * Use base64-encoding, instead of the more common
862 * Crockford base32-encoding.
863 *
864 * @param name name of the field to add to the object
865 * @param blob binary data to pack
866 * @param blob_size number of bytes in @a blob
867 * @return json pack specification
868 */
869struct GNUNET_JSON_PackSpec
870GNUNET_JSON_pack_data64_varsize (const char *name,
871 const void *blob,
872 size_t blob_size);
873
874
875/**
876 * Generate packer instruction for a JSON field where the
877 * size is automatically determined from the argument.
878 * Use base64-encoding, instead of the more common
879 * Crockford base32-encoding.
880 *
881 * @param name name of the field to add to the object
882 * @param blob data to pack, must not be an array
883 * @return json pack specification
884 */
885#define GNUNET_JSON_pack_data64_auto(name,blob) \
886 GNUNET_JSON_pack_data64_varsize (name, blob, sizeof (*blob))
887
888
889/**
890 * Generate packer instruction for a JSON field of type
891 * timestamp.
751 * 892 *
752 * @param name name of the field to add to the object 893 * @param name name of the field to add to the object
753 * @param at absolute time to pack, a value of 0 is only 894 * @param at timestamp pack, a value of 0 is only
754 * allowed with #GNUNET_JSON_pack_allow_null()! 895 * allowed with #GNUNET_JSON_pack_allow_null()!
755 * @return json pack specification 896 * @return json pack specification
756 */ 897 */
757struct GNUNET_JSON_PackSpec 898struct GNUNET_JSON_PackSpec
758GNUNET_JSON_pack_time_abs (const char *name, 899GNUNET_JSON_pack_timestamp (const char *name,
759 struct GNUNET_TIME_Absolute at); 900 struct GNUNET_TIME_Timestamp at);
760 901
761 902
762/** 903/**
763 * Generate packer instruction for a JSON field of type 904 * Generate packer instruction for a JSON field of type
764 * absolute time in network byte order. 905 * timestamp in network byte order.
765 * 906 *
766 * @param name name of the field to add to the object 907 * @param name name of the field to add to the object
767 * @param at absolute time to pack, a value of 0 is only 908 * @param at timestamp to pack, a value of 0 is only
768 * allowed with #GNUNET_JSON_pack_allow_null()! 909 * allowed with #GNUNET_JSON_pack_allow_null()!
769 * @return json pack specification 910 * @return json pack specification
770 */ 911 */
771struct GNUNET_JSON_PackSpec 912struct GNUNET_JSON_PackSpec
772GNUNET_JSON_pack_time_abs_nbo (const char *name, 913GNUNET_JSON_pack_timestamp_nbo (const char *name,
773 struct GNUNET_TIME_AbsoluteNBO at); 914 struct GNUNET_TIME_TimestampNBO at);
774 915
775 916
776/** 917/**