2 This file is part of GNUnet
3 Copyright (C) 2014, 2015, 2016 GNUnet e.V.
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.
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.
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/>
17 * @file gnunet_jsonapi_lib.h
18 * @brief functions to parse jsonapi objects
19 * @author Martin Schanzenbach
21 #ifndef GNUNET_JSONAPI_LIB_H
22 #define GNUNET_JSONAPI_LIB_H
24 #include "gnunet_util_lib.h"
25 #include "gnunet_json_lib.h"
27 #define GNUNET_JSONAPI_KEY_DATA "data"
29 #define GNUNET_JSONAPI_KEY_ID "id"
31 #define GNUNET_JSONAPI_KEY_TYPE "type"
33 #define GNUNET_JSONAPI_KEY_META "meta"
35 #define GNUNET_JSONAPI_KEY_ATTRIBUTES "attributes"
37 #define GNUNET_JSONAPI_KEY_CODE "code"
39 #define GNUNET_JSONAPI_KEY_TITLE "title"
41 #define GNUNET_JSONAPI_KEY_DETAIL "detail"
43 #define GNUNET_JSONAPI_KEY_SOURCE "source"
45 #define GNUNET_JSONAPI_KEY_LINKS "links"
47 #define GNUNET_JSONAPI_KEY_STATUS "status"
49 #define GNUNET_JSONAPI_KEY_ERRORS "errors"
51 /* ****************** JSONAPI parsing ******************* */
53 struct GNUNET_JSONAPI_Relationship;
55 struct GNUNET_JSONAPI_Error;
57 struct GNUNET_JSONAPI_Resource;
59 struct GNUNET_JSONAPI_Document;
62 * Specification for parsing a jsonapi relationship.
64 * @param jsonapi_obj where to store the jsonapi relationship
66 struct GNUNET_JSON_Specification
67 GNUNET_JSON_spec_jsonapi_relationship (struct GNUNET_JSONAPI_Relationship **jsonapi_obj);
70 * Specification for parsing a jsonapi error.
72 * @param jsonapi_obj where to store the jsonapi error
74 struct GNUNET_JSON_Specification
75 GNUNET_JSON_spec_jsonapi_error (struct GNUNET_JSONAPI_Error **jsonapi_obj);
78 * Specification for parsing a jsonapi resource.
80 * @param jsonapi_obj where to store the jsonapi resource
82 struct GNUNET_JSON_Specification
83 GNUNET_JSON_spec_jsonapi_resource (struct GNUNET_JSONAPI_Resource **jsonapi_obj);
86 * Specification for parsing a jsonapi object.
88 * @param jsonapi_obj where to store the jsonapi object
90 struct GNUNET_JSON_Specification
91 GNUNET_JSON_spec_jsonapi_document (struct GNUNET_JSONAPI_Document **jsonapi_obj);
94 * Delete a JSON API relationship
96 * @param res the JSON resource
97 * @param result Pointer where the resource should be stored
100 GNUNET_JSONAPI_relationship_delete (struct GNUNET_JSONAPI_Relationship *rel);
103 /****************** jsonapi Error API ********************/
106 * Create a JSON API error
108 * @param res the JSON error
110 struct GNUNET_JSONAPI_Error*
111 GNUNET_JSONAPI_error_new (const char *id,
121 * Delete a JSON API error
123 * @param res the JSON error
126 GNUNET_JSONAPI_error_delete (struct GNUNET_JSONAPI_Error *error);
130 * Add a JSON API error to document
132 * @param data The JSON API document to add to
133 * @param res the JSON API error to add
134 * @return the new number of resources
137 GNUNET_JSONAPI_document_error_add (struct GNUNET_JSONAPI_Document *doc,
138 struct GNUNET_JSONAPI_Error *err);
141 * String serialze jsonapi error to json
143 * @param data the JSON API error
144 * @param result where to store the result
145 * @return GNUNET_SYSERR on error else GNUNET_OK
148 GNUNET_JSONAPI_error_to_json (const struct GNUNET_JSONAPI_Error *err,
152 * Parse json to error object
154 * @param err_json JSON object
155 * @param[out] err error object
156 * @return GNUNET_OK on success
159 GNUNET_JSONAPI_json_to_error (json_t *err_json,
160 struct GNUNET_JSONAPI_Error **err);
162 /****************** jsonapi Resource API ********************/
165 * Create a JSON API resource
167 * @param type the JSON API resource type
168 * @param id the JSON API resource id
169 * @return a new JSON API resource or NULL on error.
171 struct GNUNET_JSONAPI_Resource*
172 GNUNET_JSONAPI_resource_new (const char *type, const char *id);
176 * Delete a JSON API resource
178 * @param res the JSON resource
179 * @param result Pointer where the resource should be stored
182 GNUNET_JSONAPI_resource_delete (struct GNUNET_JSONAPI_Resource *resource);
186 * String serialze jsonapi to json
188 * @param data the JSON API resource
189 * @param result where to store the result
190 * @return GNUNET_SYSERR on error else GNUNET_OK
193 GNUNET_JSONAPI_resource_to_json (const struct GNUNET_JSONAPI_Resource *res,
198 * Parse json to resource object
200 * @param res_json JSON object
201 * @param[out] res resource object
202 * @return GNUNET_OK on success
205 GNUNET_JSONAPI_json_to_resource (json_t *res_json,
206 struct GNUNET_JSONAPI_Resource **res);
210 * Add a JSON API attribute
212 * @param res the JSON resource
213 * @param key the key for the attribute
214 * @param json the json_t attribute to add
215 * @return #GNUNET_OK if added successfully
216 * #GNUNET_SYSERR if not
219 GNUNET_JSONAPI_resource_add_attr (struct GNUNET_JSONAPI_Resource *resource,
223 * Read a JSON API attribute
225 * @param res the JSON resource
226 * @param key the key for the attribute
227 * @return the json attr
230 GNUNET_JSONAPI_resource_read_attr (const struct GNUNET_JSONAPI_Resource *resource,
235 * Check a JSON API resource id
237 * @param res the JSON resource
238 * @param id the expected id
239 * @return GNUNET_YES if id matches
242 GNUNET_JSONAPI_resource_check_id (const struct GNUNET_JSONAPI_Resource *resource,
246 * Check a JSON API resource id
248 * @param res the JSON resource
249 * @return the resource id
252 GNUNET_JSONAPI_resource_get_id (const struct GNUNET_JSONAPI_Resource *resource);
256 * Check a JSON API resource type
258 * @param res the JSON resource
259 * @param type the expected type
260 * @return GNUNET_YES if id matches
263 GNUNET_JSONAPI_resource_check_type (const struct GNUNET_JSONAPI_Resource *resource,
266 /****************** jsonapi Document API ********************/
269 * Create a JSON API primary data
271 * @param type the JSON API resource type
272 * @param id the JSON API resource id
273 * @return a new JSON API resource or NULL on error.
275 struct GNUNET_JSONAPI_Document*
276 GNUNET_JSONAPI_document_new ();
280 * Delete a JSON API primary data
282 * @param type the JSON API resource type
283 * @param id the JSON API resource id
284 * @return a new JSON API resource or NULL on error.
287 GNUNET_JSONAPI_document_delete (struct GNUNET_JSONAPI_Document *resp);
290 * String serialze jsonapi primary data
292 * @param data the JSON API primary data
293 * @param result where to store the result
294 * @return GNUNET_SYSERR on error else GNUNET_OK
297 GNUNET_JSONAPI_document_to_json (const struct GNUNET_JSONAPI_Document *doc,
301 * Add a JSON API resource to primary data
303 * @param data The JSON API data to add to
304 * @param res the JSON API resource to add
305 * @return the new number of resources
308 GNUNET_JSONAPI_document_resource_add (struct GNUNET_JSONAPI_Document *resp,
309 struct GNUNET_JSONAPI_Resource *res);
311 * Get a JSON API object resource count
313 * @param resp the JSON API object
314 * @return the number of resources
317 GNUNET_JSONAPI_document_resource_count (struct GNUNET_JSONAPI_Document *resp);
320 * Get a JSON API object resource num
322 * @param resp the JSON API object
323 * @param num the number of the resource
324 * @return the resource
326 struct GNUNET_JSONAPI_Resource*
327 GNUNET_JSONAPI_document_get_resource (struct GNUNET_JSONAPI_Document *resp, int num);
331 * Add a JSON API resource to primary data
333 * @param resp The JSON API data to add to
334 * @param res the JSON API resource to add
335 * @return the new number of resources
338 GNUNET_JSONAPI_document_resource_remove (struct GNUNET_JSONAPI_Document *resp,
339 struct GNUNET_JSONAPI_Resource *res);
342 * String serialze jsonapi primary data
344 * @param data the JSON API primary data
345 * @param result where to store the result
346 * @return GNUNET_SYSERR on error else GNUNET_OK
349 GNUNET_JSONAPI_document_serialize (const struct GNUNET_JSONAPI_Document *resp,
352 /* end of gnunet_jsonapi_lib.h */