patch-private-products-PRODUCT_ID.h (20803B)
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-private-products-PRODUCT_ID.h 19 * @brief C interface for PATCH /private/products/$PRODUCT_ID 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__PATCH_PRIVATE_PRODUCTS_PRODUCT_ID_H 23 #define _TALER_MERCHANT__PATCH_PRIVATE_PRODUCTS_PRODUCT_ID_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the PATCH /private/products/$PRODUCT_ID request. 30 */ 31 enum TALER_MERCHANT_PatchPrivateProductOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_END = 0, 37 38 /** 39 * Set value and fractional part of total stock. 40 */ 41 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TOTAL_STOCK, 42 43 /** 44 * Set value part of total stock (-1 for unlimited). 45 */ 46 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TOTAL_STOCK_VAL, 47 48 /** 49 * Set fractional part of total stock. 50 */ 51 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TOTAL_STOCK_FRAC, 52 53 /** 54 * Set whether fractional quantities are allowed. 55 */ 56 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_UNIT_ALLOW_FRACTION, 57 58 /** 59 * Set precision level for fractions. 60 */ 61 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_UNIT_PRECISION_LEVEL, 62 63 /** 64 * Internationalized descriptions (JSON). 65 */ 66 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_DESCRIPTION_I18N, 67 68 /** 69 * Product image (base64-encoded data URL). 70 */ 71 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_IMAGE, 72 73 /** 74 * Tax information (JSON array). 75 */ 76 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TAXES, 77 78 /** 79 * Total units lost/expired. 80 */ 81 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TOTAL_LOST, 82 83 /** 84 * Storage location (JSON). 85 */ 86 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_ADDRESS, 87 88 /** 89 * Expected restock time. 90 */ 91 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_NEXT_RESTOCK, 92 93 /** 94 * Explicit product name (distinct from description). 95 */ 96 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_PRODUCT_NAME, 97 98 /** 99 * Category IDs. 100 */ 101 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_CATEGORIES, 102 103 /** 104 * Minimum age requirement. 105 */ 106 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_MINIMUM_AGE, 107 108 /** 109 * Product group ID. 110 */ 111 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_PRODUCT_GROUP_ID, 112 113 /** 114 * Money pot ID. 115 */ 116 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_MONEY_POT_ID, 117 118 /** 119 * Whether the price is net (before tax). 120 */ 121 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_PRICE_IS_NET 122 123 }; 124 125 126 /** 127 * Value for an option for the PATCH /private/products/$PRODUCT_ID request. 128 */ 129 struct TALER_MERCHANT_PatchPrivateProductOptionValue 130 { 131 132 /** 133 * Type of the option being set. 134 */ 135 enum TALER_MERCHANT_PatchPrivateProductOption option; 136 137 /** 138 * Specific option value. 139 */ 140 union 141 { 142 143 /** 144 * Value if @e option is 145 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TOTAL_STOCK_FRAC. 146 */ 147 uint32_t total_stock_frac; 148 149 /** 150 * Value if @e option is 151 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_UNIT_ALLOW_FRACTION. 152 */ 153 bool unit_allow_fraction; 154 155 /** 156 * Value if @e option is 157 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_UNIT_PRECISION_LEVEL. 158 */ 159 uint32_t unit_precision_level; 160 161 /** 162 * Value if @e option is 163 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_DESCRIPTION_I18N. 164 */ 165 const json_t *description_i18n; 166 167 /** 168 * Value if @e option is 169 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_IMAGE. 170 */ 171 const char *image; 172 173 /** 174 * Value if @e option is 175 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TAXES. 176 */ 177 const json_t *taxes; 178 179 struct 180 { 181 182 /** 183 * Value if @e option is 184 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TOTAL_STOCK. 185 * -1 for infinite stock. 186 */ 187 int64_t val; 188 189 /** 190 * Value if @e option is 191 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TOTAL_STOCK_FRAC. 192 */ 193 uint32_t frac; 194 } total_stock; 195 196 /** 197 * Value if @e option is 198 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TOTAL_LOST. 199 */ 200 uint64_t total_lost; 201 202 /** 203 * Value if @e option is 204 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_ADDRESS. 205 */ 206 const json_t *address; 207 208 /** 209 * Value if @e option is 210 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_NEXT_RESTOCK. 211 */ 212 struct GNUNET_TIME_Timestamp next_restock; 213 214 /** 215 * Value if @e option is 216 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_PRODUCT_NAME. 217 */ 218 const char *product_name; 219 220 /** 221 * Value if @e option is 222 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_CATEGORIES. 223 */ 224 struct 225 { 226 unsigned int num; 227 const uint64_t *cats; 228 } categories; 229 230 /** 231 * Value if @e option is 232 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_MINIMUM_AGE. 233 */ 234 uint32_t minimum_age; 235 236 /** 237 * Value if @e option is 238 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_PRODUCT_GROUP_ID. 239 */ 240 uint64_t product_group_id; 241 242 /** 243 * Value if @e option is 244 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_MONEY_POT_ID. 245 */ 246 uint64_t money_pot_id; 247 248 /** 249 * Value if @e option is 250 * #TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_PRICE_IS_NET. 251 */ 252 bool price_is_net; 253 254 } details; 255 256 }; 257 258 259 /** 260 * Handle for a PATCH /private/products/$PRODUCT_ID operation. 261 */ 262 struct TALER_MERCHANT_PatchPrivateProductHandle; 263 264 265 /** 266 * Set up PATCH /private/products/$PRODUCT_ID operation. 267 * Note that you must explicitly start the operation after 268 * possibly setting options. 269 * 270 * @param ctx the context 271 * @param url base URL of the merchant backend 272 * @param product_id identifier of the product to update 273 * @param description new human-readable description 274 * @param unit unit of measurement 275 * @param num_prices length of the @e prices array 276 * @param prices new unit prices 277 * @return handle to operation, NULL on error 278 */ 279 struct TALER_MERCHANT_PatchPrivateProductHandle * 280 TALER_MERCHANT_patch_private_product_create ( 281 struct GNUNET_CURL_Context *ctx, 282 const char *url, 283 const char *product_id, 284 const char *description, 285 const char *unit, 286 unsigned int num_prices, 287 const struct TALER_Amount prices[static num_prices]); 288 289 290 /** 291 * Terminate the list of the options. 292 * 293 * @return the terminating object of struct TALER_MERCHANT_PatchPrivateProductOptionValue 294 */ 295 #define TALER_MERCHANT_patch_private_product_option_end_() \ 296 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 297 { \ 298 .option = TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_END \ 299 } 300 301 /** 302 * Set value and fractional part of total stock. 303 * 304 * @param v value part of stock 305 * @param f fractional stock value 306 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateProductOptionValue 307 */ 308 #define TALER_MERCHANT_patch_private_product_option_total_stock(v,f) \ 309 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 310 { \ 311 .option = TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TOTAL_STOCK_FRAC, \ 312 .details.total_stock.val = (v), \ 313 .details.total_stock.frac = (f) \ 314 } 315 316 /** 317 * Set fractional part of total stock. 318 * 319 * @param f fractional stock value 320 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateProductOptionValue 321 */ 322 #define TALER_MERCHANT_patch_private_product_option_total_stock_frac(f) \ 323 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 324 { \ 325 .option = TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TOTAL_STOCK_FRAC, \ 326 .details.total_stock.frac = (f) \ 327 } 328 329 /** 330 * Set value part of total stock (-1 for unlimited). 331 * 332 * @param v stock value 333 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateProductOptionValue 334 */ 335 #define TALER_MERCHANT_patch_private_product_option_total_stock_val(v) \ 336 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 337 { \ 338 .option = TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TOTAL_STOCK_VAL, \ 339 .details.total_stock.val = (v) \ 340 } 341 342 /** 343 * Set whether fractional quantities are allowed. 344 * 345 * @param a true if fractional quantities are allowed 346 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateProductOptionValue 347 */ 348 #define TALER_MERCHANT_patch_private_product_option_unit_allow_fraction(a) \ 349 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 350 { \ 351 .option = TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_UNIT_ALLOW_FRACTION, \ 352 .details.unit_allow_fraction = (a) \ 353 } 354 355 /** 356 * Set precision level for fractions. 357 * 358 * @param p precision level value 359 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateProductOptionValue 360 */ 361 #define TALER_MERCHANT_patch_private_product_option_unit_precision_level(p) \ 362 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 363 { \ 364 .option = \ 365 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_UNIT_PRECISION_LEVEL, \ 366 .details.unit_precision_level = (p) \ 367 } 368 369 /** 370 * Set internationalized descriptions. 371 * 372 * @param d descriptions JSON object 373 * @return representation of the option 374 */ 375 #define TALER_MERCHANT_patch_private_product_option_description_i18n(d) \ 376 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 377 { \ 378 .option = \ 379 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_DESCRIPTION_I18N, \ 380 .details.description_i18n = (d) \ 381 } 382 383 /** 384 * Set product image (base64-encoded data URL). 385 * 386 * @param i image string 387 * @return representation of the option 388 */ 389 #define TALER_MERCHANT_patch_private_product_option_image(i) \ 390 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 391 { \ 392 .option = TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_IMAGE, \ 393 .details.image = (i) \ 394 } 395 396 /** 397 * Set tax information. 398 * 399 * @param t taxes JSON array 400 * @return representation of the option 401 */ 402 #define TALER_MERCHANT_patch_private_product_option_taxes(t) \ 403 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 404 { \ 405 .option = TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TAXES, \ 406 .details.taxes = (t) \ 407 } 408 409 /** 410 * Set total units lost/expired. 411 * 412 * @param l total lost value 413 * @return representation of the option 414 */ 415 #define TALER_MERCHANT_patch_private_product_option_total_lost(l) \ 416 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 417 { \ 418 .option = TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_TOTAL_LOST, \ 419 .details.total_lost = (l) \ 420 } 421 422 /** 423 * Set storage address. 424 * 425 * @param a address JSON object 426 * @return representation of the option 427 */ 428 #define TALER_MERCHANT_patch_private_product_option_address(a) \ 429 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 430 { \ 431 .option = TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_ADDRESS, \ 432 .details.address = (a) \ 433 } 434 435 /** 436 * Set expected restock time. 437 * 438 * @param r restock timestamp 439 * @return representation of the option 440 */ 441 #define TALER_MERCHANT_patch_private_product_option_next_restock(r) \ 442 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 443 { \ 444 .option = TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_NEXT_RESTOCK, \ 445 .details.next_restock = (r) \ 446 } 447 448 /** 449 * Set explicit product name (distinct from description). 450 * 451 * @param n product name string 452 * @return representation of the option 453 */ 454 #define TALER_MERCHANT_patch_private_product_option_product_name(n) \ 455 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 456 { \ 457 .option = \ 458 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_PRODUCT_NAME, \ 459 .details.product_name = (n) \ 460 } 461 462 /** 463 * Set category IDs. 464 * 465 * @param n number of categories 466 * @param c array of category IDs 467 * @return representation of the option 468 */ 469 #define TALER_MERCHANT_patch_private_product_option_categories(n,c) \ 470 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 471 { \ 472 .option = TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_CATEGORIES, \ 473 .details.categories = { .num = (n), .cats = (c) } \ 474 } 475 476 /** 477 * Set minimum age requirement. 478 * 479 * @param a minimum age (0 for none) 480 * @return representation of the option 481 */ 482 #define TALER_MERCHANT_patch_private_product_option_minimum_age(a) \ 483 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 484 { \ 485 .option = TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_MINIMUM_AGE, \ 486 .details.minimum_age = (a) \ 487 } 488 489 /** 490 * Set product group ID. 491 * 492 * @param g product group ID 493 * @return representation of the option 494 */ 495 #define TALER_MERCHANT_patch_private_product_option_product_group_id(g) \ 496 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 497 { \ 498 .option = \ 499 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_PRODUCT_GROUP_ID, \ 500 .details.product_group_id = (g) \ 501 } 502 503 /** 504 * Set money pot ID. 505 * 506 * @param m money pot ID 507 * @return representation of the option 508 */ 509 #define TALER_MERCHANT_patch_private_product_option_money_pot_id(m) \ 510 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 511 { \ 512 .option = \ 513 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_MONEY_POT_ID, \ 514 .details.money_pot_id = (m) \ 515 } 516 517 /** 518 * Set whether the price is net (before tax). 519 * 520 * @param b true if price is net 521 * @return representation of the option 522 */ 523 #define TALER_MERCHANT_patch_private_product_option_price_is_net(b) \ 524 (const struct TALER_MERCHANT_PatchPrivateProductOptionValue) \ 525 { \ 526 .option = \ 527 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_OPTION_PRICE_IS_NET, \ 528 .details.price_is_net = (b) \ 529 } 530 531 532 /** 533 * Set the requested options for the operation. 534 * 535 * If any option fail other options may be or may be not applied. 536 * 537 * @param pph the request to set the options for 538 * @param num_options length of the @a options array 539 * @param options an array of options 540 * @return #GNUNET_OK on success, 541 * #GNUNET_NO on failure, 542 * #GNUNET_SYSERR on internal error 543 */ 544 enum GNUNET_GenericReturnValue 545 TALER_MERCHANT_patch_private_product_set_options_ ( 546 struct TALER_MERCHANT_PatchPrivateProductHandle *pph, 547 unsigned int num_options, 548 const struct TALER_MERCHANT_PatchPrivateProductOptionValue *options); 549 550 551 /** 552 * Set the requested options for the operation. 553 * 554 * If any option fail other options may be or may be not applied. 555 * 556 * It should be used with helpers that create required options, for example: 557 * 558 * TALER_MERCHANT_patch_private_product_set_options ( 559 * pph, 560 * TALER_MERCHANT_patch_private_product_option_total_stock_frac (500), 561 * TALER_MERCHANT_patch_private_product_option_unit_allow_fraction (true)); 562 * 563 * @param pph the request to set the options for 564 * @param ... the list of the options, each option must be created 565 * by helpers TALER_MERCHANT_patch_private_product_option_NAME(VALUE) 566 * @return #GNUNET_OK on success, 567 * #GNUNET_NO on failure, 568 * #GNUNET_SYSERR on internal error 569 */ 570 #define TALER_MERCHANT_patch_private_product_set_options(pph,...) \ 571 TALER_MERCHANT_patch_private_product_set_options_ ( \ 572 pph, \ 573 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 574 ((const struct TALER_MERCHANT_PatchPrivateProductOptionValue[]) \ 575 {__VA_ARGS__, TALER_MERCHANT_patch_private_product_option_end_ () } \ 576 )) 577 578 579 /** 580 * Response details for a PATCH /private/products/$PRODUCT_ID request. 581 */ 582 struct TALER_MERCHANT_PatchPrivateProductResponse 583 { 584 /** 585 * HTTP response details. 586 */ 587 struct TALER_MERCHANT_HttpResponse hr; 588 }; 589 590 591 #ifndef TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_RESULT_CLOSURE 592 /** 593 * Type of the closure used by 594 * the #TALER_MERCHANT_PatchPrivateProductCallback. 595 */ 596 #define TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_RESULT_CLOSURE void 597 #endif /* TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_RESULT_CLOSURE */ 598 599 /** 600 * Callback for a PATCH /private/products/$PRODUCT_ID request. 601 * 602 * @param cls closure 603 * @param result response details 604 */ 605 typedef void 606 (*TALER_MERCHANT_PatchPrivateProductCallback)( 607 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_RESULT_CLOSURE *cls, 608 const struct TALER_MERCHANT_PatchPrivateProductResponse *result); 609 610 611 /** 612 * Start PATCH /private/products/$PRODUCT_ID operation. 613 * 614 * @param[in,out] pph operation to start 615 * @param cb function to call with the result 616 * @param cb_cls closure for @a cb 617 * @return status code, #TALER_EC_NONE on success 618 */ 619 enum TALER_ErrorCode 620 TALER_MERCHANT_patch_private_product_start ( 621 struct TALER_MERCHANT_PatchPrivateProductHandle *pph, 622 TALER_MERCHANT_PatchPrivateProductCallback cb, 623 TALER_MERCHANT_PATCH_PRIVATE_PRODUCT_RESULT_CLOSURE *cb_cls); 624 625 626 /** 627 * Cancel PATCH /private/products/$PRODUCT_ID operation. 628 * This function must not be called by clients after the 629 * callback has been invoked. 630 * 631 * @param[in] pph operation to cancel 632 */ 633 void 634 TALER_MERCHANT_patch_private_product_cancel ( 635 struct TALER_MERCHANT_PatchPrivateProductHandle *pph); 636 637 638 #endif /* _TALER_MERCHANT__PATCH_PRIVATE_PRODUCTS_PRODUCT_ID_H */