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