diff options
Diffstat (limited to 'src/include/gnunet_json_lib.h')
-rw-r--r-- | src/include/gnunet_json_lib.h | 220 |
1 files changed, 187 insertions, 33 deletions
diff --git a/src/include/gnunet_json_lib.h b/src/include/gnunet_json_lib.h index 92f696e08..0b6b299d1 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 | */ |
51 | typedef int | 52 | typedef 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,9 +109,14 @@ struct GNUNET_JSON_Specification | |||
107 | size_t *size_ptr; | 109 | size_t *size_ptr; |
108 | 110 | ||
109 | /** | 111 | /** |
110 | * Set to #GNUNET_YES if this component is optional. | 112 | * Number of bytes available in @e ptr. |
113 | */ | ||
114 | size_t ptr_size; | ||
115 | |||
116 | /** | ||
117 | * Set to true if this component is optional. | ||
111 | */ | 118 | */ |
112 | int is_optional; | 119 | bool is_optional; |
113 | }; | 120 | }; |
114 | 121 | ||
115 | 122 | ||
@@ -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 | */ |
129 | enum GNUNET_GenericReturnValue | 136 | enum 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 | */ |
162 | struct GNUNET_JSON_Specification | 176 | struct GNUNET_JSON_Specification |
163 | GNUNET_JSON_spec_mark_optional (struct GNUNET_JSON_Specification spec); | 177 | GNUNET_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 | */ | ||
213 | struct GNUNET_JSON_Specification | ||
214 | GNUNET_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 | */ | ||
272 | struct GNUNET_JSON_Specification | ||
273 | GNUNET_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 | */ | ||
283 | struct GNUNET_JSON_Specification | ||
284 | GNUNET_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 | */ | ||
305 | struct GNUNET_JSON_Specification | ||
306 | GNUNET_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 | */ |
312 | struct GNUNET_JSON_Specification | 384 | struct GNUNET_JSON_Specification |
313 | GNUNET_JSON_spec_absolute_time (const char *name, | 385 | GNUNET_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 | */ |
323 | struct GNUNET_JSON_Specification | 395 | struct GNUNET_JSON_Specification |
324 | GNUNET_JSON_spec_absolute_time_nbo (const char *name, | 396 | GNUNET_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 | */ |
372 | json_t * | 444 | json_t * |
373 | GNUNET_JSON_from_data (const void *data, size_t size); | 445 | GNUNET_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 | */ | ||
457 | json_t * | ||
458 | GNUNET_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 | */ |
393 | json_t * | 490 | json_t * |
394 | GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp); | 491 | GNUNET_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 | */ |
403 | json_t * | 500 | json_t * |
404 | GNUNET_JSON_from_time_abs_nbo (struct GNUNET_TIME_AbsoluteNBO stamp); | 501 | GNUNET_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 | */ | ||
730 | struct GNUNET_JSON_PackSpec | ||
731 | GNUNET_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. | ||
751 | * | 863 | * |
752 | * @param name name of the field to add to the object | 864 | * @param name name of the field to add to the object |
753 | * @param at absolute time to pack, a value of 0 is only | 865 | * @param blob binary data to pack |
866 | * @param blob_size number of bytes in @a blob | ||
867 | * @return json pack specification | ||
868 | */ | ||
869 | struct GNUNET_JSON_PackSpec | ||
870 | GNUNET_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. | ||
892 | * | ||
893 | * @param name name of the field to add to the object | ||
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 | */ |
757 | struct GNUNET_JSON_PackSpec | 898 | struct GNUNET_JSON_PackSpec |
758 | GNUNET_JSON_pack_time_abs (const char *name, | 899 | GNUNET_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 | */ |
771 | struct GNUNET_JSON_PackSpec | 912 | struct GNUNET_JSON_PackSpec |
772 | GNUNET_JSON_pack_time_abs_nbo (const char *name, | 913 | GNUNET_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 | /** |
@@ -825,6 +966,19 @@ GNUNET_JSON_pack_rsa_signature (const char *name, | |||
825 | const struct GNUNET_CRYPTO_RsaSignature *sig); | 966 | const struct GNUNET_CRYPTO_RsaSignature *sig); |
826 | 967 | ||
827 | 968 | ||
969 | /** | ||
970 | * Generate packer instruction for a JSON field of type | ||
971 | * unblinded signature. | ||
972 | * | ||
973 | * @param name name of the field to add to the object | ||
974 | * @param sig unblinded signature | ||
975 | * @return json pack specification | ||
976 | */ | ||
977 | struct GNUNET_JSON_PackSpec | ||
978 | GNUNET_JSON_pack_unblinded_signature (const char *name, | ||
979 | const struct GNUNET_CRYPTO_UnblindedSignature *sig); | ||
980 | |||
981 | |||
828 | #endif | 982 | #endif |
829 | 983 | ||
830 | /* end of gnunet_json_lib.h */ | 984 | /* end of gnunet_json_lib.h */ |