src/include/gnunet_rest_lib.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2010-2015 Christian Grothoff (and other contributing authors)
   4
   5       GNUnet is free software; you can redistribute it and/or modify
   6       it under the terms of the GNU General Public License as published
   7       by the Free Software Foundation; either version 3, or (at your
   8       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       General Public License for more details.
  14
  15       You should have received a copy of the GNU General Public License
  16       along with GNUnet; see the file COPYING.  If not, write to the
  17       Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18       Boston, MA 02110-1301, USA.
  19  */
  20
  21 /**
  22  * @author Martin Schanzenbach
  23  *
  24  * @file
  25  * API for helper library to parse/create REST
  26  *
  27  * @defgroup rest  REST library
  28  * Helper library to parse/create REST
  29  * @{
  30  */
  31 #ifndef GNUNET_REST_LIB_H
  32 #define GNUNET_REST_LIB_H
  33
  34 #include "gnunet_util_lib.h"
  35 #include "microhttpd.h"
  36 #include <jansson.h>
  37
  38 #define GNUNET_REST_JSONAPI_KEY_DATA "data"
  39
  40 #define GNUNET_REST_JSONAPI_KEY_ID "id"
  41
  42 #define GNUNET_REST_JSONAPI_KEY_TYPE "type"
  43
  44 #define GNUNET_REST_HANDLER_END {NULL, NULL, NULL}
  45
  46 struct RestConnectionDataHandle
  47 {
  48   struct GNUNET_CONTAINER_MultiHashMap *url_param_map;
  49   const char *method;
  50   const char *url;
  51   const char *data;
  52   size_t data_size;
  53
  54 };
  55
  56 struct GNUNET_REST_RestConnectionHandler
  57 {
  58   /**
  59    * Http method to handle
  60    */
  61   const char *method;
  62
  63   /**
  64    * Namespace to handle
  65    */
  66   const char *namespace;
  67
  68   /**
  69    * callback handler
  70    */
  71   void (*proc) (struct RestConnectionDataHandle *handle,
  72                 const char *url,
  73                 void *cls);
  74
  75 };
  76
  77
  78 /**
  79  * Iterator called on obtained result for a REST result.
  80  *
  81  * @param cls closure
  82  * @param resp the response
  83  * @param status status code (HTTP)
  84  */
  85 typedef void (*GNUNET_REST_ResultProcessor) (void *cls,
  86                                              struct MHD_Response *resp,
  87                                              int status);
  88
  89
  90 /**
  91  * Resource structs for JSON API
  92  */
  93 struct JsonApiResource;
  94
  95 /**
  96  * Responses for JSON API
  97  */
  98 struct JsonApiObject;
  99
 100 /**
 101  * Create a JSON API resource
 102  *
 103  * @param type the JSON API resource type
 104  * @param id the JSON API resource id
 105  * @return a new JSON API resource or NULL on error.
 106  */
 107 struct JsonApiResource*
 108 GNUNET_REST_jsonapi_resource_new (const char *type, const char *id);
 109
 110 /**
 111  * Delete a JSON API resource
 112  *
 113  * @param res the JSON resource
 114  * @param result Pointer where the resource should be stored
 115  */
 116 void
 117 GNUNET_REST_jsonapi_resource_delete (struct JsonApiResource *resource);
 118
 119 /**
 120  * Add a JSON API attribute
 121  *
 122  * @param res the JSON resource
 123  * @param key the key for the attribute
 124  * @param json the json_t attribute to add
 125  * @return #GNUNET_OK if added successfully
 126  *         #GNUNET_SYSERR if not
 127  */
 128 int
 129 GNUNET_REST_jsonapi_resource_add_attr (const struct JsonApiResource *resource,
 130                                        const char* key,
 131                                        json_t *json);
 132 /**
 133  * Read a JSON API attribute
 134  *
 135  * @param res the JSON resource
 136  * @param key the key for the attribute
 137  * @return the json attr
 138  */
 139 json_t*
 140 GNUNET_REST_jsonapi_resource_read_attr (const struct JsonApiResource *resource,
 141                                        const char* key);
 142
 143
 144 /**
 145  * Check a JSON API resource id
 146  *
 147  * @param res the JSON resource
 148  * @param id the expected id
 149  * @return GNUNET_YES if id matches
 150  */
 151 int
 152 GNUNET_REST_jsonapi_resource_check_id (const struct JsonApiResource *resource,
 153                                        const char* id);
 154
 155
 156 /**
 157  * Check a JSON API resource type
 158  *
 159  * @param res the JSON resource
 160  * @param type the expected type
 161  * @return GNUNET_YES if id matches
 162  */
 163 int
 164 GNUNET_REST_jsonapi_resource_check_type (const struct JsonApiResource *resource,
 165                                          const char* type);
 166
 167
 168 /**
 169  * Create a JSON API primary data
 170  *
 171  * @param type the JSON API resource type
 172  * @param id the JSON API resource id
 173  * @return a new JSON API resource or NULL on error.
 174  */
 175 struct JsonApiObject*
 176 GNUNET_REST_jsonapi_object_new ();
 177
 178
 179 /**
 180  * Create a JSON API primary data from a string
 181  *
 182  * @param data the string of the JSON API data
 183  * @return a new JSON API resource or NULL on error.
 184  */
 185 struct JsonApiObject*
 186 GNUNET_REST_jsonapi_object_parse (const char* data);
 187
 188
 189 /**
 190  * Delete a JSON API primary data
 191  *
 192  * @param type the JSON API resource type
 193  * @param id the JSON API resource id
 194  * @return a new JSON API resource or NULL on error.
 195  */
 196 void
 197 GNUNET_REST_jsonapi_object_delete (struct JsonApiObject *resp);
 198
 199 /**
 200  * Add a JSON API resource to primary data
 201  *
 202  * @param data The JSON API data to add to
 203  * @param res the JSON API resource to add
 204  * @return the new number of resources
 205  */
 206 void
 207 GNUNET_REST_jsonapi_object_resource_add (struct JsonApiObject *resp,
 208                                            struct JsonApiResource *res);
 209 /**
 210  * Get a JSON API object resource count
 211  *
 212  * @param resp the JSON API object
 213  * @return the number of resources
 214  */
 215 int
 216 GNUNET_REST_jsonapi_object_resource_count (struct JsonApiObject *resp);
 217
 218 /**
 219  * Get a JSON API object resource num
 220  *
 221  * @param resp the JSON API object
 222  * @param num the number of the resource
 223  * @return the resource
 224  */
 225 struct JsonApiResource*
 226 GNUNET_REST_jsonapi_object_get_resource (struct JsonApiObject *resp, int num);
 227
 228
 229 /**
 230  * Add a JSON API resource to primary data
 231  *
 232  * @param resp The JSON API data to add to
 233  * @param res the JSON API resource to add
 234  * @return the new number of resources
 235  */
 236 void
 237 GNUNET_REST_jsonapi_data_resource_remove (struct JsonApiObject *resp,
 238                                           struct JsonApiResource *res);
 239
 240 /**
 241  * String serialze jsonapi primary data
 242  *
 243  * @param data the JSON API primary data
 244  * @param result where to store the result
 245  * @return GNUNET_SYSERR on error else GNUNET_OK
 246  */
 247 int
 248 GNUNET_REST_jsonapi_data_serialize (const struct JsonApiObject *resp,
 249                                     char **result);
 250
 251 /**
 252  * Check if namespace is in URL.
 253  *
 254  * @param url URL to check
 255  * @param namespace namespace to check against
 256  * @retun GNUNET_YES if namespace matches
 257  */
 258 int
 259 GNUNET_REST_namespace_match (const char *url, const char *namespace);
 260
 261 /**
 262  * Create JSON API MHD response
 263  *
 264  * @param data JSON result
 265  * @retun MHD response
 266  */
 267  struct MHD_Response*
 268 GNUNET_REST_create_json_response (const char *data);
 269
 270
 271 int
 272 GNUNET_REST_handle_request (struct RestConnectionDataHandle *conn,
 273                             const struct GNUNET_REST_RestConnectionHandler *handlers,
 274                             void *cls);
 275
 276
 277 #endif
 278
 279 /** @} */  /* end of group */