taler_twister_service.h (8006B)
1 /* 2 This file is part of Taler 3 Copyright (C) 2018 Taler Systems SA 4 5 Taler is free software; you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as 7 published by the Free Software Foundation; either version 3, 8 or (at your option) any later version. 9 10 Taler 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 13 the GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public 16 License along with Taler; see the file COPYING. If not, 17 write to the Free Software Foundation, Inc., 51 Franklin 18 Street, Fifth Floor, Boston, MA 02110-1301, USA. */ 19 20 #ifndef TALER_TWISTER_SERVICE_H_ 21 #define TALER_TWISTER_SERVICE_H_ 22 23 #define TWISTER_FAIL() \ 24 do {GNUNET_break (0); return NULL; } while (0) 25 26 /** 27 * @author Christian Grothoff 28 * @author Marcello Stanisci 29 */ 30 31 #ifdef __cplusplus 32 extern "C" 33 { 34 #if 0 /* keep Emacsens' auto-indent happy */ 35 } 36 #endif 37 #endif 38 39 #include <gnunet/gnunet_util_lib.h> 40 41 /** 42 * Version of the twister API. 43 */ 44 #define TALER_TWISTER_VERSION 0x00000000 45 46 /** 47 * Handle for 48 */ 49 struct TALER_TWISTER_Handle; 50 51 52 /** 53 * Return twister project data. 54 */ 55 const struct GNUNET_OS_ProjectData * 56 TWISTER_project_data (void); 57 58 59 /** 60 * Connect to the twister service. 61 * 62 * @param cfg the configuration to use 63 * @return handle to use in #TALER_TWISTER_disconnect to disconnect 64 */ 65 struct TALER_TWISTER_Handle * 66 TALER_TWISTER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); 67 68 69 /** 70 * Disconnect from twister service. 71 * 72 * @param h handle to destroy 73 */ 74 void 75 TALER_TWISTER_disconnect (struct TALER_TWISTER_Handle *h); 76 77 78 /** 79 * Opaque handle for asynchronous operation. 80 */ 81 struct TALER_TWISTER_Operation; 82 83 84 /** 85 * Change the response field pointed by @a modify_path with 86 * @a modify_value. 87 * 88 * @param h twister instance to control 89 * @param path object-like notation path to the object to modify 90 * @param value value to use for @a modify_path 91 * @param cb callback to call once twister gets this instruction. 92 * @param cb_cls closure for @a cb_callback 93 * 94 * @return operation handle. 95 */ 96 struct TALER_TWISTER_Operation * 97 TALER_TWISTER_modify_path_dl (struct TALER_TWISTER_Handle *h, 98 const char *path, 99 const char *value, 100 GNUNET_SCHEDULER_TaskCallback cb, 101 void *cb_cls); 102 103 104 /** 105 * Change the JSON field pointed by @a path to the new @a value. 106 * It only applies to upload objects. 107 * 108 * @param h twister instance to control 109 * @param path object-like notation path to the object to modify 110 * @param value value to use for @a modify_path 111 * @param cb callback to call once twister gets this instruction. 112 * @param cb_cls closure for @a cb_callback 113 * 114 * @return operation handle. 115 */ 116 struct TALER_TWISTER_Operation * 117 TALER_TWISTER_modify_path_ul (struct TALER_TWISTER_Handle *h, 118 const char *path, 119 const char *value, 120 GNUNET_SCHEDULER_TaskCallback cb, 121 void *cb_cls); 122 123 124 /** 125 * Change the HTTP response header of @a header to @a value. 126 * 127 * @param h twister instance to control 128 * @param header the HTTP response header to modify 129 * @param value value to use for @a header 130 * @param cb callback to call once twister gets this instruction. 131 * @param cb_cls closure for @a cb_callback 132 * 133 * @return operation handle. 134 */ 135 struct TALER_TWISTER_Operation * 136 TALER_TWISTER_modify_header_dl (struct TALER_TWISTER_Handle *h, 137 const char *header, 138 const char *value, 139 GNUNET_SCHEDULER_TaskCallback cb, 140 void *cb_cls); 141 142 143 /** 144 * Instruct the twister to flip a character into 145 * the string JSON field that belongs to the object 146 * being returned to the HTTP client. 147 * 148 * @param h twister instance to control 149 * @param path object-like notation to point the string 150 * object where we seek a character to flip. 151 * @param cb function to call once twister has processed this 152 * request 153 * @param cb_cls closure for @a cb 154 * @return operation handle (to possibly abort) 155 */ 156 struct TALER_TWISTER_Operation * 157 TALER_TWISTER_flip_download (struct TALER_TWISTER_Handle *h, 158 const char *path, 159 GNUNET_SCHEDULER_TaskCallback cb, 160 void *cb_cls); 161 162 163 /** 164 * Instruct the twister to flip a character into 165 * the string JSON field that belongs to the object 166 * being uploaded to the proxied service. 167 * 168 * @param h twister instance to control 169 * @param path object-like notation to point the string 170 * object where we seek a character to flip. 171 * @param cb function to call once twister has batched this 172 * request 173 * @param cb_cls closure for @a cb 174 * @return operation handle (to possibly abort) 175 */ 176 struct TALER_TWISTER_Operation * 177 TALER_TWISTER_flip_upload (struct TALER_TWISTER_Handle *h, 178 const char *path, 179 GNUNET_SCHEDULER_TaskCallback cb, 180 void *cb_cls); 181 182 183 /** 184 * Change the next response code to @a new_rc. 185 * 186 * @param h twister instance to control 187 * @param new_rc response code to return from the next response 188 * @param cb function to call once twister is ready 189 * @param cb_cls closure for @a cb 190 * @return operation handle (to possibly abort) 191 */ 192 struct TALER_TWISTER_Operation * 193 TALER_TWISTER_change_response_code (struct TALER_TWISTER_Handle *h, 194 unsigned int new_rc, 195 GNUNET_SCHEDULER_TaskCallback cb, 196 void *cb_cls); 197 198 199 /** 200 * Randomly truncate the response. 201 * 202 * @param h twister instance to control 203 * @param cb function to call once twister has processed this 204 * request. 205 * @param cb_cls closure for @a cb 206 * @return operation handle (to possibly abort) 207 */ 208 struct TALER_TWISTER_Operation * 209 TALER_TWISTER_malform (struct TALER_TWISTER_Handle *h, 210 GNUNET_SCHEDULER_TaskCallback cb, 211 void *cb_cls); 212 213 214 /** 215 * Randomly truncate the request. 216 * 217 * @param h twister instance to control 218 * @param cb function to call once twister is ready; typically 219 * a acknowledge function. 220 * @param cb_cls closure for @a cb 221 * @return operation handle (to possibly abort) 222 */ 223 struct TALER_TWISTER_Operation * 224 TALER_TWISTER_malform_upload (struct TALER_TWISTER_Handle *h, 225 GNUNET_SCHEDULER_TaskCallback cb, 226 void *cb_cls); 227 228 229 /** 230 * Delete the object pointed to by @a path. Note, this 231 * object belongs to the JSON response object. 232 * 233 * @param h twister instance to control 234 * @param path object-like notation to point the object to be 235 deleted. E.g., the path "f1.f2.0" will delete the object 236 {"f1": {"f2": [{"to be": "deleted"}]}}. 237 * @param cb function to call once twister is ready 238 * @param cb_cls closure for @a cb 239 * @return operation handle (to possibly abort) 240 */ 241 struct TALER_TWISTER_Operation * 242 TALER_TWISTER_delete_path (struct TALER_TWISTER_Handle *h, 243 const char *path, 244 GNUNET_SCHEDULER_TaskCallback cb, 245 void *cb_cls); 246 247 248 /** 249 * Abort operation. Twister behavior may then include the 250 * changes requested by the operation, or not! Must be called 251 * before the operations callback was invoked. 252 * 253 * @param op operation to cancel, 254 * operation's callback will not be called 255 */ 256 void 257 TALER_TWISTER_cancel (struct TALER_TWISTER_Operation *op); 258 259 260 #if 0 /* keep Emacsens' auto-indent happy */ 261 { 262 #endif 263 #ifdef __cplusplus 264 } 265 #endif 266 267 268 #endif /* TALER_NSE_SERVICE_H_ */