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