post-private-orders.h (13900B)
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 include/taler/taler-merchant/post-private-orders.h 19 * @brief C interface for the POST /private/orders endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_PRIVATE_ORDERS_H 23 #define _TALER_MERCHANT__POST_PRIVATE_ORDERS_H 24 25 #include <taler/taler-merchant/common.h> 26 27 28 /** 29 * A product from inventory to include in an order. 30 */ 31 struct TALER_MERCHANT_PostPrivateOrdersInventoryProduct 32 { 33 34 /** 35 * Identifier of the product. 36 */ 37 const char *product_id; 38 39 /** 40 * Quantity of the product to include. 41 */ 42 uint32_t quantity; 43 44 /** 45 * Fractional part of the quantity. 46 */ 47 uint32_t quantity_frac; 48 49 /** 50 * Money pot to use for this product, overrides value from 51 * the inventory if given. -1 if not set. 52 * @since protocol v25. 53 */ 54 int32_t product_money_pot; 55 56 /** 57 * Whether to use fractional quantity. 58 */ 59 bool use_fractional_quantity; 60 61 }; 62 63 64 /** 65 * Possible options for the POST /private/orders request. 66 */ 67 enum TALER_MERCHANT_PostPrivateOrdersOption 68 { 69 /** 70 * End of list of options. 71 */ 72 TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_END = 0, 73 74 /** 75 * Refund delay. 76 */ 77 TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_REFUND_DELAY, 78 79 /** 80 * Payment target (type of payment method). 81 */ 82 TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_PAYMENT_TARGET, 83 84 /** 85 * Session identifier for session-bound payments. 86 */ 87 TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_SESSION_ID, 88 89 /** 90 * Whether to create a claim token. 91 */ 92 TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_CREATE_TOKEN, 93 94 /** 95 * OTP device ID. 96 */ 97 TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_OTP_ID, 98 99 /** 100 * Inventory products to include in the order. 101 */ 102 TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_INVENTORY_PRODUCTS, 103 104 /** 105 * Lock UUIDs for inventory locks. 106 */ 107 TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_LOCK_UUIDS 108 109 }; 110 111 112 /** 113 * Value for an option for the POST /private/orders request. 114 */ 115 struct TALER_MERCHANT_PostPrivateOrdersOptionValue 116 { 117 118 /** 119 * Type of the option being set. 120 */ 121 enum TALER_MERCHANT_PostPrivateOrdersOption option; 122 123 /** 124 * Specific option value. 125 */ 126 union 127 { 128 129 /** 130 * Value if @e option is 131 * #TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_REFUND_DELAY. 132 */ 133 struct GNUNET_TIME_Relative refund_delay; 134 135 /** 136 * Value if @e option is 137 * #TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_PAYMENT_TARGET. 138 */ 139 const char *payment_target; 140 141 /** 142 * Value if @e option is 143 * #TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_SESSION_ID. 144 */ 145 const char *session_id; 146 147 /** 148 * Value if @e option is 149 * #TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_CREATE_TOKEN. 150 */ 151 bool create_token; 152 153 /** 154 * Value if @e option is 155 * #TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_OTP_ID. 156 */ 157 const char *otp_id; 158 159 /** 160 * Value if @e option is 161 * #TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_INVENTORY_PRODUCTS. 162 */ 163 struct 164 { 165 unsigned int num; 166 const struct TALER_MERCHANT_PostPrivateOrdersInventoryProduct *products; 167 } inventory_products; 168 169 /** 170 * Value if @e option is 171 * #TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_LOCK_UUIDS. 172 */ 173 struct 174 { 175 unsigned int num; 176 const char **uuids; 177 } lock_uuids; 178 179 } details; 180 181 }; 182 183 184 /** 185 * Handle for a POST /private/orders request. 186 */ 187 struct TALER_MERCHANT_PostPrivateOrdersHandle; 188 189 190 /** 191 * Detail about why a specific exchange was rejected when 192 * creating an order. 193 */ 194 struct TALER_MERCHANT_ExchangeRejectionDetail 195 { 196 197 /** 198 * Base URL of the rejected exchange. 199 */ 200 const char *exchange_url; 201 202 /** 203 * Error code indicating why this exchange was not acceptable. 204 */ 205 enum TALER_ErrorCode code; 206 207 /** 208 * Human-readable hint about the error, or NULL. 209 */ 210 const char *hint; 211 212 }; 213 214 215 /** 216 * Response details for a POST /private/orders request. 217 */ 218 struct TALER_MERCHANT_PostPrivateOrdersResponse 219 { 220 221 /** 222 * HTTP response details. 223 */ 224 struct TALER_MERCHANT_HttpResponse hr; 225 226 /** 227 * Details depending on the HTTP status code. 228 */ 229 union 230 { 231 232 /** 233 * Details on #MHD_HTTP_OK. 234 */ 235 struct 236 { 237 238 /** 239 * Identifier of the created order. 240 */ 241 const char *order_id; 242 243 /** 244 * Claim token, or NULL. 245 */ 246 const struct TALER_ClaimTokenP *token; 247 248 /** 249 * Payment deadline. 250 */ 251 struct GNUNET_TIME_Timestamp pay_deadline; 252 253 } ok; 254 255 /** 256 * Details on #MHD_HTTP_GONE (product out of stock). 257 */ 258 struct 259 { 260 261 /** 262 * Product that is out of stock. 263 */ 264 const char *product_id; 265 266 /** 267 * Requested quantity (integer part). 268 */ 269 uint64_t requested_quantity; 270 271 /** 272 * Requested quantity (fractional part). 273 */ 274 uint32_t requested_quantity_frac; 275 276 /** 277 * Available quantity (integer part). 278 */ 279 uint64_t available_quantity; 280 281 /** 282 * Available quantity (fractional part). 283 */ 284 uint32_t available_quantity_frac; 285 286 /** 287 * Requested quantity as string in "<integer>[.<fraction>]" format, 288 * or NULL if not provided. 289 */ 290 const char *unit_requested_quantity; 291 292 /** 293 * Available quantity as string in "<integer>[.<fraction>]" format, 294 * or NULL if not provided. 295 */ 296 const char *unit_available_quantity; 297 298 /** 299 * Expected restock time. 300 */ 301 struct GNUNET_TIME_Timestamp restock_expected; 302 303 } gone; 304 305 /** 306 * Details on #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS. 307 * @since protocol v25. 308 */ 309 struct 310 { 311 312 /** 313 * Number of entries in @a exchange_rejections. 314 */ 315 unsigned int num_exchange_rejections; 316 317 /** 318 * Array of exchange rejection details. 319 */ 320 const struct TALER_MERCHANT_ExchangeRejectionDetail 321 *exchange_rejections; 322 323 } unavailable_for_legal_reasons; 324 325 } details; 326 327 }; 328 329 330 /** 331 * Terminate the list of the options. 332 * 333 * @return the terminating object 334 */ 335 #define TALER_MERCHANT_post_private_orders_option_end_() \ 336 (const struct TALER_MERCHANT_PostPrivateOrdersOptionValue) \ 337 { \ 338 .option = TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_END \ 339 } 340 341 /** 342 * Set refund delay. 343 * 344 * @param d refund delay 345 * @return representation of the option 346 */ 347 #define TALER_MERCHANT_post_private_orders_option_refund_delay(d) \ 348 (const struct TALER_MERCHANT_PostPrivateOrdersOptionValue) \ 349 { \ 350 .option = TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_REFUND_DELAY, \ 351 .details.refund_delay = (d) \ 352 } 353 354 /** 355 * Set payment target. 356 * 357 * @param t payment target string 358 * @return representation of the option 359 */ 360 #define TALER_MERCHANT_post_private_orders_option_payment_target(t) \ 361 (const struct TALER_MERCHANT_PostPrivateOrdersOptionValue) \ 362 { \ 363 .option = TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_PAYMENT_TARGET, \ 364 .details.payment_target = (t) \ 365 } 366 367 /** 368 * Set session identifier. 369 * 370 * @param s session ID 371 * @return representation of the option 372 */ 373 #define TALER_MERCHANT_post_private_orders_option_session_id(s) \ 374 (const struct TALER_MERCHANT_PostPrivateOrdersOptionValue) \ 375 { \ 376 .option = TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_SESSION_ID, \ 377 .details.session_id = (s) \ 378 } 379 380 /** 381 * Set whether to create a claim token. 382 * 383 * @param c true to create token, false to disable 384 * @return representation of the option 385 */ 386 #define TALER_MERCHANT_post_private_orders_option_create_token(c) \ 387 (const struct TALER_MERCHANT_PostPrivateOrdersOptionValue) \ 388 { \ 389 .option = TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_CREATE_TOKEN, \ 390 .details.create_token = (c) \ 391 } 392 393 /** 394 * Set OTP device ID. 395 * 396 * @param o OTP device ID 397 * @return representation of the option 398 */ 399 #define TALER_MERCHANT_post_private_orders_option_otp_id(o) \ 400 (const struct TALER_MERCHANT_PostPrivateOrdersOptionValue) \ 401 { \ 402 .option = TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_OTP_ID, \ 403 .details.otp_id = (o) \ 404 } 405 406 /** 407 * Set inventory products. 408 * 409 * @param n number of products 410 * @param p array of inventory products 411 * @return representation of the option 412 */ 413 #define TALER_MERCHANT_post_private_orders_option_inventory_products(n,p) \ 414 (const struct TALER_MERCHANT_PostPrivateOrdersOptionValue) \ 415 { \ 416 .option = TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_INVENTORY_PRODUCTS \ 417 , \ 418 .details.inventory_products = { .num = (n), .products = (p) } \ 419 } 420 421 /** 422 * Set lock UUIDs. 423 * 424 * @param n number of UUIDs 425 * @param u array of UUID strings 426 * @return representation of the option 427 */ 428 #define TALER_MERCHANT_post_private_orders_option_lock_uuids(n,u) \ 429 (const struct TALER_MERCHANT_PostPrivateOrdersOptionValue) \ 430 { \ 431 .option = TALER_MERCHANT_POST_PRIVATE_ORDERS_OPTION_LOCK_UUIDS, \ 432 .details.lock_uuids = { .num = (n), .uuids = (u) } \ 433 } 434 435 436 /** 437 * Set the requested options for the operation. 438 * 439 * @param ppoh the request to set the options for 440 * @param num_options length of the @a options array 441 * @param options an array of options 442 * @return #GNUNET_OK on success, 443 * #GNUNET_NO on failure, 444 * #GNUNET_SYSERR on internal error 445 */ 446 enum GNUNET_GenericReturnValue 447 TALER_MERCHANT_post_private_orders_set_options_ ( 448 struct TALER_MERCHANT_PostPrivateOrdersHandle *ppoh, 449 unsigned int num_options, 450 const struct TALER_MERCHANT_PostPrivateOrdersOptionValue *options); 451 452 453 /** 454 * Set the requested options for the operation. 455 * 456 * @param ppoh the request to set the options for 457 * @param ... the list of the options 458 * @return #GNUNET_OK on success, 459 * #GNUNET_NO on failure, 460 * #GNUNET_SYSERR on internal error 461 */ 462 #define TALER_MERCHANT_post_private_orders_set_options(ppoh,...) \ 463 TALER_MERCHANT_post_private_orders_set_options_ ( \ 464 ppoh, \ 465 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 466 ((const struct TALER_MERCHANT_PostPrivateOrdersOptionValue[]) \ 467 {__VA_ARGS__, TALER_MERCHANT_post_private_orders_option_end_ () } \ 468 )) 469 470 471 /** 472 * Set up POST /private/orders operation. 473 * Note that you must explicitly start the operation after 474 * possibly setting options. 475 * 476 * @param ctx the context 477 * @param url base URL of the merchant backend 478 * @param order order contract (JSON) 479 * @return handle to operation 480 */ 481 struct TALER_MERCHANT_PostPrivateOrdersHandle * 482 TALER_MERCHANT_post_private_orders_create ( 483 struct GNUNET_CURL_Context *ctx, 484 const char *url, 485 const json_t *order); 486 487 488 #ifndef TALER_MERCHANT_POST_PRIVATE_ORDERS_RESULT_CLOSURE 489 /** 490 * Type of the closure used by 491 * the #TALER_MERCHANT_PostPrivateOrdersCallback. 492 */ 493 #define TALER_MERCHANT_POST_PRIVATE_ORDERS_RESULT_CLOSURE void 494 #endif /* TALER_MERCHANT_POST_PRIVATE_ORDERS_RESULT_CLOSURE */ 495 496 /** 497 * Callback for a POST /private/orders request. 498 * 499 * @param cls closure 500 * @param por response details 501 */ 502 typedef void 503 (*TALER_MERCHANT_PostPrivateOrdersCallback)( 504 TALER_MERCHANT_POST_PRIVATE_ORDERS_RESULT_CLOSURE *cls, 505 const struct TALER_MERCHANT_PostPrivateOrdersResponse *por); 506 507 508 /** 509 * Start POST /private/orders operation. 510 * 511 * @param[in,out] ppoh operation to start 512 * @param cb function to call with the merchant's result 513 * @param cb_cls closure for @a cb 514 * @return status code, #TALER_EC_NONE on success 515 */ 516 enum TALER_ErrorCode 517 TALER_MERCHANT_post_private_orders_start ( 518 struct TALER_MERCHANT_PostPrivateOrdersHandle *ppoh, 519 TALER_MERCHANT_PostPrivateOrdersCallback cb, 520 TALER_MERCHANT_POST_PRIVATE_ORDERS_RESULT_CLOSURE *cb_cls); 521 522 523 /** 524 * Cancel POST /private/orders operation. This function must not be 525 * called by clients after the TALER_MERCHANT_PostPrivateOrdersCallback 526 * has been invoked (as in those cases it'll be called internally by the 527 * implementation already). 528 * 529 * @param[in] ppoh operation to cancel 530 */ 531 void 532 TALER_MERCHANT_post_private_orders_cancel ( 533 struct TALER_MERCHANT_PostPrivateOrdersHandle *ppoh); 534 535 536 #endif /* _TALER_MERCHANT__POST_PRIVATE_ORDERS_H */