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_rest_lib.h"
  26 #include "gnunet_json_lib.h"
  27
  28
  29 /* ****************** JSONAPI parsing ******************* */
  30
  31 struct GNUNET_JSONAPI_Resource;
  32
  33 struct GNUNET_JSONAPI_Object;
  34
  35 /**
  36  * Specification for parsing a jsonapi object.
  37  *
  38  * @param jsonapi_obj where to store the jsonapi object
  39  */
  40 struct GNUNET_JSON_Specification
  41 GNUNET_JSON_spec_jsonapi (struct GNUNET_JSONAPI_Object **jsonapi_obj);
  42
  43 /**
  44  * Create a JSON API resource
  45  *
  46  * @param type the JSON API resource type
  47  * @param id the JSON API resource id
  48  * @return a new JSON API resource or NULL on error.
  49  */
  50 struct GNUNET_JSONAPI_Resource*
  51 GNUNET_JSONAPI_resource_new (const char *type, const char *id);
  52
  53 /**
  54  * Delete a JSON API resource
  55  *
  56  * @param res the JSON resource
  57  * @param result Pointer where the resource should be stored
  58  */
  59 void
  60 GNUNET_JSONAPI_resource_delete (struct GNUNET_JSONAPI_Resource *resource);
  61
  62 /**
  63  * Add a JSON API attribute
  64  *
  65  * @param res the JSON resource
  66  * @param key the key for the attribute
  67  * @param json the json_t attribute to add
  68  * @return #GNUNET_OK if added successfully
  69  *         #GNUNET_SYSERR if not
  70  */
  71 int
  72 GNUNET_JSONAPI_resource_add_attr (const struct GNUNET_JSONAPI_Resource *resource,
  73                                        const char* key,
  74                                        json_t *json);
  75 /**
  76  * Read a JSON API attribute
  77  *
  78  * @param res the JSON resource
  79  * @param key the key for the attribute
  80  * @return the json attr
  81  */
  82 json_t*
  83 GNUNET_JSONAPI_resource_read_attr (const struct GNUNET_JSONAPI_Resource *resource,
  84                                        const char* key);
  85
  86
  87 /**
  88  * Check a JSON API resource id
  89  *
  90  * @param res the JSON resource
  91  * @param id the expected id
  92  * @return GNUNET_YES if id matches
  93  */
  94 int
  95 GNUNET_JSONAPI_resource_check_id (const struct GNUNET_JSONAPI_Resource *resource,
  96                                        const char* id);
  97
  98
  99 /**
 100  * Check a JSON API resource type
 101  *
 102  * @param res the JSON resource
 103  * @param type the expected type
 104  * @return GNUNET_YES if id matches
 105  */
 106 int
 107 GNUNET_JSONAPI_resource_check_type (const struct GNUNET_JSONAPI_Resource *resource,
 108                                          const char* type);
 109
 110
 111 /**
 112  * Create a JSON API primary data
 113  *
 114  * @param type the JSON API resource type
 115  * @param id the JSON API resource id
 116  * @return a new JSON API resource or NULL on error.
 117  */
 118 struct GNUNET_JSONAPI_Object*
 119 GNUNET_JSONAPI_object_new ();
 120
 121
 122 /**
 123  * Create a JSON API primary data from a string
 124  *
 125  * @param data the string of the JSON API data
 126  * @param Pointer where to store new jsonapi Object.
 127  * @return GNUNET_OK on success
 128  */
 129 int
 130 GNUNET_JSONAPI_object_parse (const char* data,
 131                              struct GNUNET_JSONAPI_Object** obj);
 132
 133
 134 /**
 135  * Delete a JSON API primary data
 136  *
 137  * @param type the JSON API resource type
 138  * @param id the JSON API resource id
 139  * @return a new JSON API resource or NULL on error.
 140  */
 141 void
 142 GNUNET_JSONAPI_object_delete (struct GNUNET_JSONAPI_Object *resp);
 143
 144 /**
 145  * Add a JSON API resource to primary data
 146  *
 147  * @param data The JSON API data to add to
 148  * @param res the JSON API resource to add
 149  * @return the new number of resources
 150  */
 151 void
 152 GNUNET_JSONAPI_object_resource_add (struct GNUNET_JSONAPI_Object *resp,
 153                                            struct GNUNET_JSONAPI_Resource *res);
 154 /**
 155  * Get a JSON API object resource count
 156  *
 157  * @param resp the JSON API object
 158  * @return the number of resources
 159  */
 160 int
 161 GNUNET_JSONAPI_object_resource_count (struct GNUNET_JSONAPI_Object *resp);
 162
 163 /**
 164  * Get a JSON API object resource num
 165  *
 166  * @param resp the JSON API object
 167  * @param num the number of the resource
 168  * @return the resource
 169  */
 170 struct GNUNET_JSONAPI_Resource*
 171 GNUNET_JSONAPI_object_get_resource (struct GNUNET_JSONAPI_Object *resp, int num);
 172
 173
 174 /**
 175  * Add a JSON API resource to primary data
 176  *
 177  * @param resp The JSON API data to add to
 178  * @param res the JSON API resource to add
 179  * @return the new number of resources
 180  */
 181 void
 182 GNUNET_JSONAPI_data_resource_remove (struct GNUNET_JSONAPI_Object *resp,
 183                                           struct GNUNET_JSONAPI_Resource *res);
 184
 185 /**
 186  * String serialze jsonapi primary data
 187  *
 188  * @param data the JSON API primary data
 189  * @param result where to store the result
 190  * @return GNUNET_SYSERR on error else GNUNET_OK
 191  */
 192 int
 193 GNUNET_JSONAPI_data_serialize (const struct GNUNET_JSONAPI_Object *resp,
 194                                     char **result);
 195
 196 /**
 197  * Check a JSON API resource id
 198  *
 199  * @param res the JSON resource
 200  * @return the resource id
 201  */
 202 json_t*
 203 GNUNET_JSONAPI_resource_get_id (const struct GNUNET_JSONAPI_Resource *resource);
 204
 205
 206 /* end of gnunet_jsonapi_lib.h */
 207
 208 /**
 209  * Check rest request for validity
 210  *
 211  * @param req handle to the request
 212  * @return GNUNET_OK if valid
 213  */
 214 int
 215 GNUNET_JSONAPI_check_request_acceptable (struct GNUNET_REST_RequestHandle *req);
 216
 217 /**
 218  * Check rest request for validity
 219  *
 220  * @param req handle to the request
 221  * @return GNUNET_OK if valid
 222  */
 223 int
 224 GNUNET_JSONAPI_check_request_supported (struct GNUNET_REST_RequestHandle *req);
 225
 226
 227 /**
 228  * Handle jsonapi rest request. Checks request headers for jsonapi compliance
 229  *
 230  * @param req rest request handle
 231  * @param handler rest request handlers
 232  * @param cls closure
 233  * @return GNUNET_OK if successful
 234  */
 235 int
 236 GNUNET_JSONAPI_handle_request (struct GNUNET_REST_RequestHandle *req,
 237                                const struct GNUNET_REST_RequestHandler *handlers,
 238                                struct GNUNET_REST_RequestHandlerError *err,
 239                                void *cls);
 240
 241 #endif