patch-management-instances-INSTANCE.h (14159B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Lesser General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER 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 Lesser General Public License for more details. 12 13 You should have received a copy of the GNU Lesser General Public License along with 14 TALER; see the file COPYING.LGPL. If not, see 15 <http://www.gnu.org/licenses/> 16 */ 17 /** 18 * @file src/include/taler/merchant/patch-management-instances-INSTANCE.h 19 * @brief C interface for PATCH /management/instances/$INSTANCE 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__PATCH_MANAGEMENT_INSTANCES_INSTANCE_H 23 #define _TALER_MERCHANT__PATCH_MANAGEMENT_INSTANCES_INSTANCE_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the PATCH /management/instances/$INSTANCE request. 30 */ 31 enum TALER_MERCHANT_PatchManagementInstancesOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_END = 0, 37 38 /** 39 * Set the default pay delay. 40 */ 41 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_DEFAULT_PAY_DELAY, 42 43 /** 44 * Set the default refund delay. 45 */ 46 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_DEFAULT_REFUND_DELAY, 47 48 /** 49 * Set the default wire transfer delay. 50 */ 51 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_DEFAULT_WIRE_TRANSFER_DELAY, 52 53 /** 54 * Set the default wire transfer rounding interval. 55 */ 56 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_DEFAULT_WIRE_TRANSFER_ROUNDING_INTERVAL, 57 58 /** 59 * Set the email address. 60 */ 61 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_EMAIL, 62 63 /** 64 * Set the phone number. 65 */ 66 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_PHONE_NUMBER, 67 68 /** 69 * Set the website URL. 70 */ 71 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_WEBSITE, 72 73 /** 74 * Set the logo. 75 */ 76 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_LOGO 77 78 }; 79 80 81 /** 82 * Value for an option for the PATCH /management/instances/$INSTANCE request. 83 */ 84 struct TALER_MERCHANT_PatchManagementInstancesOptionValue 85 { 86 87 /** 88 * Type of the option being set. 89 */ 90 enum TALER_MERCHANT_PatchManagementInstancesOption option; 91 92 /** 93 * Specific option value. 94 */ 95 union 96 { 97 98 /** 99 * Value if @e option is 100 * #TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_DEFAULT_PAY_DELAY. 101 */ 102 struct GNUNET_TIME_Relative default_pay_delay; 103 104 /** 105 * Value if @e option is 106 * #TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_DEFAULT_REFUND_DELAY. 107 */ 108 struct GNUNET_TIME_Relative default_refund_delay; 109 110 /** 111 * Value if @e option is 112 * #TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_DEFAULT_WIRE_TRANSFER_DELAY. 113 */ 114 struct GNUNET_TIME_Relative default_wire_transfer_delay; 115 116 /** 117 * Value if @e option is 118 * #TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_DEFAULT_WIRE_TRANSFER_ROUNDING_INTERVAL. 119 */ 120 enum GNUNET_TIME_RounderInterval default_wire_transfer_rounding_interval; 121 122 /** 123 * Value if @e option is 124 * #TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_EMAIL. 125 */ 126 const char *email; 127 128 /** 129 * Value if @e option is 130 * #TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_PHONE_NUMBER. 131 */ 132 const char *phone_number; 133 134 /** 135 * Value if @e option is 136 * #TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_WEBSITE. 137 */ 138 const char *website; 139 140 /** 141 * Value if @e option is 142 * #TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_LOGO. 143 */ 144 const char *logo; 145 146 } details; 147 148 }; 149 150 151 /** 152 * Handle for a PATCH /management/instances/$INSTANCE operation. 153 */ 154 struct TALER_MERCHANT_PatchManagementInstancesHandle; 155 156 157 /** 158 * Set up PATCH /management/instances/$INSTANCE operation. 159 * Note that you must explicitly start the operation after 160 * possibly setting options. 161 * 162 * @param ctx the context 163 * @param url base URL of the merchant backend 164 * @param instance_id identifier of the instance to patch 165 * @param name new human-readable name 166 * @param address new address (JSON) 167 * @param jurisdiction new jurisdiction (JSON) 168 * @param use_stefan whether to use the STEFAN curve for fee calculations 169 * @return handle to operation, NULL on error 170 */ 171 struct TALER_MERCHANT_PatchManagementInstancesHandle * 172 TALER_MERCHANT_patch_management_instances_create ( 173 struct GNUNET_CURL_Context *ctx, 174 const char *url, 175 const char *instance_id, 176 const char *name, 177 const json_t *address, 178 const json_t *jurisdiction, 179 bool use_stefan); 180 181 182 /** 183 * Terminate the list of the options. 184 * 185 * @return the terminating object of struct TALER_MERCHANT_PatchManagementInstancesOptionValue 186 */ 187 #define TALER_MERCHANT_patch_management_instances_option_end_() \ 188 (const struct TALER_MERCHANT_PatchManagementInstancesOptionValue) \ 189 { \ 190 .option = TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_END \ 191 } 192 193 /** 194 * Set default pay delay. 195 * 196 * @param d delay to set 197 * @return representation of the option 198 */ 199 #define TALER_MERCHANT_patch_management_instances_option_default_pay_delay(d) \ 200 (const struct TALER_MERCHANT_PatchManagementInstancesOptionValue) \ 201 { \ 202 .option = \ 203 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_DEFAULT_PAY_DELAY, \ 204 .details.default_pay_delay = (d) \ 205 } 206 207 /** 208 * Set default refund delay. 209 * 210 * @param d delay to set 211 * @return representation of the option 212 */ 213 #define TALER_MERCHANT_patch_management_instances_option_default_refund_delay(d) \ 214 (const struct TALER_MERCHANT_PatchManagementInstancesOptionValue) \ 215 { \ 216 .option = \ 217 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_DEFAULT_REFUND_DELAY, \ 218 .details.default_refund_delay = (d) \ 219 } 220 221 /** 222 * Set default wire transfer delay. 223 * 224 * @param d delay to set 225 * @return representation of the option 226 */ 227 #define \ 228 TALER_MERCHANT_patch_management_instances_option_default_wire_transfer_delay(d) \ 229 (const struct TALER_MERCHANT_PatchManagementInstancesOptionValue) \ 230 { \ 231 .option = \ 232 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_DEFAULT_WIRE_TRANSFER_DELAY, \ 233 .details.default_wire_transfer_delay = (d) \ 234 } 235 236 /** 237 * Set default wire transfer rounding interval. 238 * 239 * @param ri rounding interval to set 240 * @return representation of the option 241 */ 242 #define \ 243 TALER_MERCHANT_patch_management_instances_option_default_wire_transfer_rounding_interval(ri) \ 244 (const struct TALER_MERCHANT_PatchManagementInstancesOptionValue) \ 245 { \ 246 .option = \ 247 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_DEFAULT_WIRE_TRANSFER_ROUNDING_INTERVAL, \ 248 .details.default_wire_transfer_rounding_interval = (ri) \ 249 } 250 251 /** 252 * Set email address. 253 * 254 * @param e email to set 255 * @return representation of the option 256 */ 257 #define TALER_MERCHANT_patch_management_instances_option_email(e) \ 258 (const struct TALER_MERCHANT_PatchManagementInstancesOptionValue) \ 259 { \ 260 .option = \ 261 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_EMAIL, \ 262 .details.email = (e) \ 263 } 264 265 /** 266 * Set phone number. 267 * 268 * @param p phone number to set 269 * @return representation of the option 270 */ 271 #define TALER_MERCHANT_patch_management_instances_option_phone_number(p) \ 272 (const struct TALER_MERCHANT_PatchManagementInstancesOptionValue) \ 273 { \ 274 .option = \ 275 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_PHONE_NUMBER, \ 276 .details.phone_number = (p) \ 277 } 278 279 /** 280 * Set website URL. 281 * 282 * @param w website to set 283 * @return representation of the option 284 */ 285 #define TALER_MERCHANT_patch_management_instances_option_website(w) \ 286 (const struct TALER_MERCHANT_PatchManagementInstancesOptionValue) \ 287 { \ 288 .option = \ 289 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_WEBSITE, \ 290 .details.website = (w) \ 291 } 292 293 /** 294 * Set logo. 295 * 296 * @param l logo to set 297 * @return representation of the option 298 */ 299 #define TALER_MERCHANT_patch_management_instances_option_logo(l) \ 300 (const struct TALER_MERCHANT_PatchManagementInstancesOptionValue) \ 301 { \ 302 .option = \ 303 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_OPTION_LOGO, \ 304 .details.logo = (l) \ 305 } 306 307 308 /** 309 * Set the requested options for the operation. 310 * 311 * If any option fail other options may be or may be not applied. 312 * 313 * @param pmih the request to set the options for 314 * @param num_options length of the @a options array 315 * @param options an array of options 316 * @return #GNUNET_OK on success, 317 * #GNUNET_NO on failure, 318 * #GNUNET_SYSERR on internal error 319 */ 320 enum GNUNET_GenericReturnValue 321 TALER_MERCHANT_patch_management_instances_set_options_ ( 322 struct TALER_MERCHANT_PatchManagementInstancesHandle *pmih, 323 unsigned int num_options, 324 const struct TALER_MERCHANT_PatchManagementInstancesOptionValue *options); 325 326 327 /** 328 * Set the requested options for the operation. 329 * 330 * If any option fail other options may be or may be not applied. 331 * 332 * It should be used with helpers that create required options, for example: 333 * 334 * TALER_MERCHANT_patch_management_instances_set_options ( 335 * pmih, 336 * TALER_MERCHANT_patch_management_instances_option_email ( 337 * "foo@example.com")); 338 * 339 * @param pmih the request to set the options for 340 * @param ... the list of the options, each option must be created 341 * by helpers TALER_MERCHANT_patch_management_instances_option_NAME(VALUE) 342 * @return #GNUNET_OK on success, 343 * #GNUNET_NO on failure, 344 * #GNUNET_SYSERR on internal error 345 */ 346 #define TALER_MERCHANT_patch_management_instances_set_options(pmih,...) \ 347 TALER_MERCHANT_patch_management_instances_set_options_ ( \ 348 pmih, \ 349 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 350 ((const struct TALER_MERCHANT_PatchManagementInstancesOptionValue[]) \ 351 {__VA_ARGS__, TALER_MERCHANT_patch_management_instances_option_end_ \ 352 () } \ 353 )) 354 355 356 /** 357 * Response details for a PATCH /management/instances/$INSTANCE request. 358 */ 359 struct TALER_MERCHANT_PatchManagementInstancesResponse 360 { 361 /** 362 * HTTP response details. 363 */ 364 struct TALER_MERCHANT_HttpResponse hr; 365 }; 366 367 368 #ifndef TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_RESULT_CLOSURE 369 /** 370 * Type of the closure used by 371 * the #TALER_MERCHANT_PatchManagementInstancesCallback. 372 */ 373 #define TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_RESULT_CLOSURE void 374 #endif /* TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_RESULT_CLOSURE */ 375 376 /** 377 * Callback for a PATCH /management/instances/$INSTANCE request. 378 * 379 * @param cls closure 380 * @param result response details 381 */ 382 typedef void 383 (*TALER_MERCHANT_PatchManagementInstancesCallback)( 384 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_RESULT_CLOSURE *cls, 385 const struct TALER_MERCHANT_PatchManagementInstancesResponse *result); 386 387 388 /** 389 * Start PATCH /management/instances/$INSTANCE operation. 390 * 391 * @param[in,out] handle operation to start 392 * @param cb function to call with the result 393 * @param cb_cls closure for @a cb 394 * @return status code, #TALER_EC_NONE on success 395 */ 396 enum TALER_ErrorCode 397 TALER_MERCHANT_patch_management_instances_start ( 398 struct TALER_MERCHANT_PatchManagementInstancesHandle *handle, 399 TALER_MERCHANT_PatchManagementInstancesCallback cb, 400 TALER_MERCHANT_PATCH_MANAGEMENT_INSTANCES_RESULT_CLOSURE *cb_cls); 401 402 403 /** 404 * Cancel PATCH /management/instances/$INSTANCE operation. 405 * This function must not be called by clients after the 406 * callback has been invoked. 407 * 408 * @param[in] handle operation to cancel 409 */ 410 void 411 TALER_MERCHANT_patch_management_instances_cancel ( 412 struct TALER_MERCHANT_PatchManagementInstancesHandle *handle); 413 414 415 #endif /* _TALER_MERCHANT__PATCH_MANAGEMENT_INSTANCES_INSTANCE_H */