src/include/gnunet_jsonapi_lib.h

   1 /*
   2   This file is part of GNUnet
   3   Copyright (C) 2014, 2015, 2016 GNUnet e.V.
   4
   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.
   8
   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.
  12
  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/>
  15 */
  16 /**
  17  * @file gnunet_jsonapi_lib.h
  18  * @brief functions to parse jsonapi objects
  19  * @author Martin Schanzenbach
  20  */
  21 #ifndef GNUNET_JSONAPI_LIB_H
  22 #define GNUNET_JSONAPI_LIB_H
  23
  24 #include "gnunet_util_lib.h"
  25 #include "gnunet_json_lib.h"
  26
  27 #define GNUNET_JSONAPI_KEY_DATA "data"
  28
  29 #define GNUNET_JSONAPI_KEY_ID "id"
  30
  31 #define GNUNET_JSONAPI_KEY_TYPE "type"
  32
  33 #define GNUNET_JSONAPI_KEY_META "meta"
  34
  35 #define GNUNET_JSONAPI_KEY_ATTRIBUTES "attributes"
  36
  37 #define GNUNET_JSONAPI_KEY_CODE "code"
  38
  39 #define GNUNET_JSONAPI_KEY_TITLE "title"
  40
  41 #define GNUNET_JSONAPI_KEY_DETAIL "detail"
  42
  43 #define GNUNET_JSONAPI_KEY_SOURCE "source"
  44
  45 #define GNUNET_JSONAPI_KEY_LINKS "links"
  46
  47 #define GNUNET_JSONAPI_KEY_STATUS "status"
  48
  49 #define GNUNET_JSONAPI_KEY_ERRORS "errors"
  50
  51 /* ****************** JSONAPI parsing ******************* */
  52
  53 struct GNUNET_JSONAPI_Relationship;
  54
  55 struct GNUNET_JSONAPI_Error;
  56
  57 struct GNUNET_JSONAPI_Resource;
  58
  59 struct GNUNET_JSONAPI_Document;
  60
  61 /**
  62  * Specification for parsing a jsonapi relationship.
  63  *
  64  * @param jsonapi_obj where to store the jsonapi relationship
  65  */
  66 struct GNUNET_JSON_Specification
  67 GNUNET_JSON_spec_jsonapi_relationship (struct GNUNET_JSONAPI_Relationship **jsonapi_obj);
  68
  69 /**
  70  * Specification for parsing a jsonapi error.
  71  *
  72  * @param jsonapi_obj where to store the jsonapi error
  73  */
  74 struct GNUNET_JSON_Specification
  75 GNUNET_JSON_spec_jsonapi_error (struct GNUNET_JSONAPI_Error **jsonapi_obj);
  76
  77 /**
  78  * Specification for parsing a jsonapi resource.
  79  *
  80  * @param jsonapi_obj where to store the jsonapi resource
  81  */
  82 struct GNUNET_JSON_Specification
  83 GNUNET_JSON_spec_jsonapi_resource (struct GNUNET_JSONAPI_Resource **jsonapi_obj);
  84
  85 /**
  86  * Specification for parsing a jsonapi object.
  87  *
  88  * @param jsonapi_obj where to store the jsonapi object
  89  */
  90 struct GNUNET_JSON_Specification
  91 GNUNET_JSON_spec_jsonapi_document (struct GNUNET_JSONAPI_Document **jsonapi_obj);
  92
  93 /**
  94  * Delete a JSON API relationship
  95  *
  96  * @param res the JSON resource
  97  * @param result Pointer where the resource should be stored
  98  */
  99 void
 100 GNUNET_JSONAPI_relationship_delete (struct GNUNET_JSONAPI_Relationship *rel);
 101
 102
 103 /****************** jsonapi Error API ********************/
 104
 105 /**
 106  * Create a JSON API error
 107  *
 108  * @param res the JSON error
 109  */
 110 struct GNUNET_JSONAPI_Error*
 111 GNUNET_JSONAPI_error_new (const char *id,
 112                           const char *status,
 113                           const char *code,
 114                           const char *title,
 115                           const char *detail,
 116                           json_t *links,
 117                           json_t *source,
 118                           json_t *meta);
 119
 120 /**
 121  * Delete a JSON API error
 122  *
 123  * @param res the JSON error
 124  */
 125 void
 126 GNUNET_JSONAPI_error_delete (struct GNUNET_JSONAPI_Error *error);
 127
 128
 129 /**
 130  * Add a JSON API error to document
 131  *
 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
 135  */
 136 void
 137 GNUNET_JSONAPI_document_error_add (struct GNUNET_JSONAPI_Document *doc,
 138                                       struct GNUNET_JSONAPI_Error *err);
 139
 140 /**
 141  * String serialze jsonapi error to json
 142  *
 143  * @param data the JSON API error
 144  * @param result where to store the result
 145  * @return GNUNET_SYSERR on error else GNUNET_OK
 146  */
 147 int
 148 GNUNET_JSONAPI_error_to_json (const struct GNUNET_JSONAPI_Error *err,
 149                               json_t **result);
 150
 151 /**
 152  * Parse json to error object
 153  *
 154  * @param err_json JSON object
 155  * @param[out] err error object
 156  * @return GNUNET_OK on success
 157  */
 158 int
 159 GNUNET_JSONAPI_json_to_error (json_t *err_json,
 160                               struct GNUNET_JSONAPI_Error **err);
 161
 162 /****************** jsonapi Resource API ********************/
 163
 164 /**
 165  * Create a JSON API resource
 166  *
 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.
 170  */
 171 struct GNUNET_JSONAPI_Resource*
 172 GNUNET_JSONAPI_resource_new (const char *type, const char *id);
 173
 174
 175 /**
 176  * Delete a JSON API resource
 177  *
 178  * @param res the JSON resource
 179  * @param result Pointer where the resource should be stored
 180  */
 181 void
 182 GNUNET_JSONAPI_resource_delete (struct GNUNET_JSONAPI_Resource *resource);
 183
 184
 185 /**
 186  * String serialze jsonapi to json
 187  *
 188  * @param data the JSON API resource
 189  * @param result where to store the result
 190  * @return GNUNET_SYSERR on error else GNUNET_OK
 191  */
 192 int
 193 GNUNET_JSONAPI_resource_to_json (const struct GNUNET_JSONAPI_Resource *res,
 194                                  json_t **result);
 195
 196
 197 /**
 198  * Parse json to resource object
 199  *
 200  * @param res_json JSON object
 201  * @param[out] res resource object
 202  * @return GNUNET_OK on success
 203  */
 204 int
 205 GNUNET_JSONAPI_json_to_resource (json_t *res_json,
 206                                  struct GNUNET_JSONAPI_Resource **res);
 207
 208
 209 /**
 210  * Add a JSON API attribute
 211  *
 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
 217  */
 218 int
 219 GNUNET_JSONAPI_resource_add_attr (struct GNUNET_JSONAPI_Resource *resource,
 220                                   const char* key,
 221                                   json_t *json);
 222 /**
 223  * Read a JSON API attribute
 224  *
 225  * @param res the JSON resource
 226  * @param key the key for the attribute
 227  * @return the json attr
 228  */
 229 json_t*
 230 GNUNET_JSONAPI_resource_read_attr (const struct GNUNET_JSONAPI_Resource *resource,
 231                                    const char* key);
 232
 233
 234 /**
 235  * Check a JSON API resource id
 236  *
 237  * @param res the JSON resource
 238  * @param id the expected id
 239  * @return GNUNET_YES if id matches
 240  */
 241 int
 242 GNUNET_JSONAPI_resource_check_id (const struct GNUNET_JSONAPI_Resource *resource,
 243                                   const char* id);
 244
 245 /**
 246  * Check a JSON API resource id
 247  *
 248  * @param res the JSON resource
 249  * @return the resource id
 250  */
 251 const char*
 252 GNUNET_JSONAPI_resource_get_id (const struct GNUNET_JSONAPI_Resource *resource);
 253
 254
 255 /**
 256  * Check a JSON API resource type
 257  *
 258  * @param res the JSON resource
 259  * @param type the expected type
 260  * @return GNUNET_YES if id matches
 261  */
 262 int
 263 GNUNET_JSONAPI_resource_check_type (const struct GNUNET_JSONAPI_Resource *resource,
 264                                     const char* type);
 265
 266 /****************** jsonapi Document API ********************/
 267
 268 /**
 269  * Create a JSON API primary data
 270  *
 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.
 274  */
 275 struct GNUNET_JSONAPI_Document*
 276 GNUNET_JSONAPI_document_new ();
 277
 278
 279 /**
 280  * Delete a JSON API primary data
 281  *
 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.
 285  */
 286 void
 287 GNUNET_JSONAPI_document_delete (struct GNUNET_JSONAPI_Document *resp);
 288
 289 /**
 290  * String serialze jsonapi primary data
 291  *
 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
 295  */
 296 int
 297 GNUNET_JSONAPI_document_to_json (const struct GNUNET_JSONAPI_Document *doc,
 298                                  json_t **root_json);
 299
 300 /**
 301  * Add a JSON API resource to primary data
 302  *
 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
 306  */
 307 void
 308 GNUNET_JSONAPI_document_resource_add (struct GNUNET_JSONAPI_Document *resp,
 309                                       struct GNUNET_JSONAPI_Resource *res);
 310 /**
 311  * Get a JSON API object resource count
 312  *
 313  * @param resp the JSON API object
 314  * @return the number of resources
 315  */
 316 int
 317 GNUNET_JSONAPI_document_resource_count (struct GNUNET_JSONAPI_Document *resp);
 318
 319 /**
 320  * Get a JSON API object resource num
 321  *
 322  * @param resp the JSON API object
 323  * @param num the number of the resource
 324  * @return the resource
 325  */
 326 struct GNUNET_JSONAPI_Resource*
 327 GNUNET_JSONAPI_document_get_resource (struct GNUNET_JSONAPI_Document *resp, int num);
 328
 329
 330 /**
 331  * Add a JSON API resource to primary data
 332  *
 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
 336  */
 337 void
 338 GNUNET_JSONAPI_document_resource_remove (struct GNUNET_JSONAPI_Document *resp,
 339                                          struct GNUNET_JSONAPI_Resource *res);
 340
 341 /**
 342  * String serialze jsonapi primary data
 343  *
 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
 347  */
 348 int
 349 GNUNET_JSONAPI_document_serialize (const struct GNUNET_JSONAPI_Document *resp,
 350                                    char **result);
 351
 352 /* end of gnunet_jsonapi_lib.h */
 353 #endif