post-management-instances.h (15014B)
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/post-management-instances.h 19 * @brief C interface for the POST /management/instances endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_MANAGEMENT_INSTANCES_H 23 #define _TALER_MERCHANT__POST_MANAGEMENT_INSTANCES_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the POST /management/instances request. 30 */ 31 enum TALER_MERCHANT_PostManagementInstancesOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_END = 0, 37 38 /** 39 * Set the default pay delay. 40 */ 41 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_DEFAULT_PAY_DELAY, 42 43 /** 44 * Set the default refund delay. 45 */ 46 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_DEFAULT_REFUND_DELAY, 47 48 /** 49 * Set the default wire transfer delay. 50 */ 51 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_DEFAULT_WIRE_TRANSFER_DELAY, 52 53 /** 54 * Set the default wire transfer rounding interval. 55 */ 56 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_DEFAULT_WIRE_TRANSFER_ROUNDING_INTERVAL, 57 58 /** 59 * Set the email address. 60 */ 61 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_EMAIL, 62 63 /** 64 * Set the phone number. 65 */ 66 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_PHONE_NUMBER, 67 68 /** 69 * Set the website URL. 70 */ 71 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_WEBSITE, 72 73 /** 74 * Set the logo. 75 */ 76 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_LOGO, 77 78 /** 79 * Set the authentication password. 80 */ 81 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_AUTH_PASSWORD 82 83 }; 84 85 86 /** 87 * Value for an option for the POST /management/instances request. 88 */ 89 struct TALER_MERCHANT_PostManagementInstancesOptionValue 90 { 91 92 /** 93 * Type of the option being set. 94 */ 95 enum TALER_MERCHANT_PostManagementInstancesOption option; 96 97 /** 98 * Specific option value. 99 */ 100 union 101 { 102 103 /** 104 * Value if @e option is 105 * #TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_DEFAULT_PAY_DELAY. 106 */ 107 struct GNUNET_TIME_Relative default_pay_delay; 108 109 /** 110 * Value if @e option is 111 * #TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_DEFAULT_REFUND_DELAY. 112 */ 113 struct GNUNET_TIME_Relative default_refund_delay; 114 115 /** 116 * Value if @e option is 117 * #TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_DEFAULT_WIRE_TRANSFER_DELAY. 118 */ 119 struct GNUNET_TIME_Relative default_wire_transfer_delay; 120 121 /** 122 * Value if @e option is 123 * #TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_DEFAULT_WIRE_TRANSFER_ROUNDING_INTERVAL. 124 */ 125 enum GNUNET_TIME_RounderInterval default_wire_transfer_rounding_interval; 126 127 /** 128 * Value if @e option is 129 * #TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_EMAIL. 130 */ 131 const char *email; 132 133 /** 134 * Value if @e option is 135 * #TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_PHONE_NUMBER. 136 */ 137 const char *phone_number; 138 139 /** 140 * Value if @e option is 141 * #TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_WEBSITE. 142 */ 143 const char *website; 144 145 /** 146 * Value if @e option is 147 * #TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_LOGO. 148 */ 149 const char *logo; 150 151 /** 152 * Value if @e option is 153 * #TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_AUTH_PASSWORD. 154 */ 155 const char *auth_password; 156 157 } details; 158 159 }; 160 161 162 /** 163 * Handle for a POST /management/instances request. 164 */ 165 struct TALER_MERCHANT_PostManagementInstancesHandle; 166 167 168 /** 169 * Response details for a POST /management/instances request. 170 */ 171 struct TALER_MERCHANT_PostManagementInstancesResponse 172 { 173 174 /** 175 * HTTP response details. 176 */ 177 struct TALER_MERCHANT_HttpResponse hr; 178 179 /** 180 * Details depending on the HTTP status code. 181 */ 182 union 183 { 184 /** 185 * Details on #MHD_HTTP_ACCEPTED. 186 */ 187 struct TALER_MERCHANT_MfaChallengeResponse accepted; 188 } details; 189 190 }; 191 192 193 /** 194 * Set up POST /management/instances operation. 195 * Note that you must explicitly start the operation after 196 * possibly setting options. 197 * 198 * @param ctx the context 199 * @param url base URL of the merchant backend 200 * @param instance_id identifier for the new instance 201 * @param name human-readable name 202 * @param address address (JSON) 203 * @param jurisdiction jurisdiction (JSON) 204 * @param use_stefan whether to use the STEFAN curve for fee calculations 205 * @return handle to operation 206 */ 207 struct TALER_MERCHANT_PostManagementInstancesHandle * 208 TALER_MERCHANT_post_management_instances_create ( 209 struct GNUNET_CURL_Context *ctx, 210 const char *url, 211 const char *instance_id, 212 const char *name, 213 const json_t *address, 214 const json_t *jurisdiction, 215 bool use_stefan); 216 217 218 /** 219 * Terminate the list of the options. 220 * 221 * @return the terminating object of struct TALER_MERCHANT_PostManagementInstancesOptionValue 222 */ 223 #define TALER_MERCHANT_post_management_instances_option_end_() \ 224 (const struct TALER_MERCHANT_PostManagementInstancesOptionValue) \ 225 { \ 226 .option = TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_END \ 227 } 228 229 /** 230 * Set default pay delay. 231 * 232 * @param d delay to set 233 * @return representation of the option 234 */ 235 #define TALER_MERCHANT_post_management_instances_option_default_pay_delay(d) \ 236 (const struct TALER_MERCHANT_PostManagementInstancesOptionValue) \ 237 { \ 238 .option = \ 239 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_DEFAULT_PAY_DELAY, \ 240 .details.default_pay_delay = (d) \ 241 } 242 243 /** 244 * Set default refund delay. 245 * 246 * @param d delay to set 247 * @return representation of the option 248 */ 249 #define TALER_MERCHANT_post_management_instances_option_default_refund_delay(d) \ 250 (const struct TALER_MERCHANT_PostManagementInstancesOptionValue) \ 251 { \ 252 .option = \ 253 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_DEFAULT_REFUND_DELAY, \ 254 .details.default_refund_delay = (d) \ 255 } 256 257 /** 258 * Set default wire transfer delay. 259 * 260 * @param d delay to set 261 * @return representation of the option 262 */ 263 #define TALER_MERCHANT_post_management_instances_option_default_wire_transfer_delay(d) \ 264 (const struct TALER_MERCHANT_PostManagementInstancesOptionValue) \ 265 { \ 266 .option = \ 267 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_DEFAULT_WIRE_TRANSFER_DELAY, \ 268 .details.default_wire_transfer_delay = (d) \ 269 } 270 271 /** 272 * Set default wire transfer rounding interval. 273 * 274 * @param ri rounding interval to set 275 * @return representation of the option 276 */ 277 #define TALER_MERCHANT_post_management_instances_option_default_wire_transfer_rounding_interval(ri) \ 278 (const struct TALER_MERCHANT_PostManagementInstancesOptionValue) \ 279 { \ 280 .option = \ 281 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_DEFAULT_WIRE_TRANSFER_ROUNDING_INTERVAL, \ 282 .details.default_wire_transfer_rounding_interval = (ri) \ 283 } 284 285 /** 286 * Set email address. 287 * 288 * @param e email to set 289 * @return representation of the option 290 */ 291 #define TALER_MERCHANT_post_management_instances_option_email(e) \ 292 (const struct TALER_MERCHANT_PostManagementInstancesOptionValue) \ 293 { \ 294 .option = \ 295 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_EMAIL, \ 296 .details.email = (e) \ 297 } 298 299 /** 300 * Set phone number. 301 * 302 * @param p phone number to set 303 * @return representation of the option 304 */ 305 #define TALER_MERCHANT_post_management_instances_option_phone_number(p) \ 306 (const struct TALER_MERCHANT_PostManagementInstancesOptionValue) \ 307 { \ 308 .option = \ 309 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_PHONE_NUMBER, \ 310 .details.phone_number = (p) \ 311 } 312 313 /** 314 * Set website URL. 315 * 316 * @param w website to set 317 * @return representation of the option 318 */ 319 #define TALER_MERCHANT_post_management_instances_option_website(w) \ 320 (const struct TALER_MERCHANT_PostManagementInstancesOptionValue) \ 321 { \ 322 .option = \ 323 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_WEBSITE, \ 324 .details.website = (w) \ 325 } 326 327 /** 328 * Set logo. 329 * 330 * @param l logo to set 331 * @return representation of the option 332 */ 333 #define TALER_MERCHANT_post_management_instances_option_logo(l) \ 334 (const struct TALER_MERCHANT_PostManagementInstancesOptionValue) \ 335 { \ 336 .option = \ 337 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_LOGO, \ 338 .details.logo = (l) \ 339 } 340 341 /** 342 * Set authentication password. 343 * 344 * @param pw password to set 345 * @return representation of the option 346 */ 347 #define TALER_MERCHANT_post_management_instances_option_auth_password(pw) \ 348 (const struct TALER_MERCHANT_PostManagementInstancesOptionValue) \ 349 { \ 350 .option = \ 351 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_OPTION_AUTH_PASSWORD, \ 352 .details.auth_password = (pw) \ 353 } 354 355 356 /** 357 * Set the requested options for the operation. 358 * 359 * If any option fail other options may be or may be not applied. 360 * 361 * @param pmih the request to set the options for 362 * @param num_options length of the @a options array 363 * @param options an array of options 364 * @return #GNUNET_OK on success, 365 * #GNUNET_NO on failure, 366 * #GNUNET_SYSERR on internal error 367 */ 368 enum GNUNET_GenericReturnValue 369 TALER_MERCHANT_post_management_instances_set_options_ ( 370 struct TALER_MERCHANT_PostManagementInstancesHandle *pmih, 371 unsigned int num_options, 372 const struct TALER_MERCHANT_PostManagementInstancesOptionValue *options); 373 374 375 /** 376 * Set the requested options for the operation. 377 * 378 * If any option fail other options may be or may be not applied. 379 * 380 * It should be used with helpers that create required options, for example: 381 * 382 * TALER_MERCHANT_post_management_instances_set_options ( 383 * pmih, 384 * TALER_MERCHANT_post_management_instances_option_email ( 385 * "foo@example.com")); 386 * 387 * @param pmih the request to set the options for 388 * @param ... the list of the options, each option must be created 389 * by helpers TALER_MERCHANT_post_management_instances_option_NAME(VALUE) 390 * @return #GNUNET_OK on success, 391 * #GNUNET_NO on failure, 392 * #GNUNET_SYSERR on internal error 393 */ 394 #define TALER_MERCHANT_post_management_instances_set_options(pmih,...) \ 395 TALER_MERCHANT_post_management_instances_set_options_ ( \ 396 pmih, \ 397 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 398 ((const struct TALER_MERCHANT_PostManagementInstancesOptionValue[]) \ 399 {__VA_ARGS__, TALER_MERCHANT_post_management_instances_option_end_ () \ 400 } \ 401 )) 402 403 404 #ifndef TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_RESULT_CLOSURE 405 /** 406 * Type of the closure used by 407 * the #TALER_MERCHANT_PostManagementInstancesCallback. 408 */ 409 #define TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_RESULT_CLOSURE void 410 #endif /* TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_RESULT_CLOSURE */ 411 412 /** 413 * Callback for a POST /management/instances request. 414 * 415 * @param cls closure 416 * @param mir response details 417 */ 418 typedef void 419 (*TALER_MERCHANT_PostManagementInstancesCallback)( 420 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_RESULT_CLOSURE *cls, 421 const struct TALER_MERCHANT_PostManagementInstancesResponse *mir); 422 423 424 /** 425 * Start POST /management/instances operation. 426 * 427 * @param[in,out] pmih operation to start 428 * @param cb function to call with the merchant's result 429 * @param cb_cls closure for @a cb 430 * @return status code, #TALER_EC_NONE on success 431 */ 432 enum TALER_ErrorCode 433 TALER_MERCHANT_post_management_instances_start ( 434 struct TALER_MERCHANT_PostManagementInstancesHandle *pmih, 435 TALER_MERCHANT_PostManagementInstancesCallback cb, 436 TALER_MERCHANT_POST_MANAGEMENT_INSTANCES_RESULT_CLOSURE *cb_cls); 437 438 439 /** 440 * Cancel POST /management/instances operation. This function must not be 441 * called by clients after the TALER_MERCHANT_PostManagementInstancesCallback 442 * has been invoked (as in those cases it'll be called internally by the 443 * implementation already). 444 * 445 * @param[in] pmih operation to cancel 446 */ 447 void 448 TALER_MERCHANT_post_management_instances_cancel ( 449 struct TALER_MERCHANT_PostManagementInstancesHandle *pmih); 450 451 452 #endif /* _TALER_MERCHANT__POST_MANAGEMENT_INSTANCES_H */