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