get-private-orders.h (17631B)
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/get-private-orders.h 19 * @brief C interface for the GET /private/orders endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__GET_PRIVATE_ORDERS_H 23 #define _TALER_MERCHANT__GET_PRIVATE_ORDERS_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the GET /private/orders request. 30 */ 31 enum TALER_MERCHANT_GetPrivateOrdersOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_END = 0, 37 38 /** 39 * Filter by paid status. 40 */ 41 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_PAID, 42 43 /** 44 * Filter by refunded status. 45 */ 46 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_REFUNDED, 47 48 /** 49 * Filter by wired status. 50 */ 51 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_WIRED, 52 53 /** 54 * Return at most N values. Negative values 55 * to return before offset, positive to return after offset. 56 * Default is -20. 57 */ 58 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_LIMIT, 59 60 /** 61 * Starting row_id for pagination. 62 */ 63 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_OFFSET, 64 65 /** 66 * Date threshold for filtering. 67 */ 68 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_DATE, 69 70 /** 71 * Long polling timeout. 72 */ 73 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_TIMEOUT, 74 75 /** 76 * Filter by session ID. 77 */ 78 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_SESSION_ID, 79 80 /** 81 * Filter by fulfillment URL. 82 */ 83 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_FULFILLMENT_URL, 84 85 /** 86 * Filter by summary text (case-insensitive substring match). 87 */ 88 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_SUMMARY_FILTER, 89 90 /** 91 * Only return orders younger than the specified age. 92 * Only applicable if limit is positive. 93 * @since protocol v27. 94 */ 95 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_MAX_AGE, 96 97 /** 98 * Filter by expiration status. 99 * @since protocol v37. 100 */ 101 TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_EXPIRED 102 103 }; 104 105 106 /** 107 * Value for an option for the GET /private/orders request. 108 */ 109 struct TALER_MERCHANT_GetPrivateOrdersOptionValue 110 { 111 112 /** 113 * Type of the option being set. 114 */ 115 enum TALER_MERCHANT_GetPrivateOrdersOption option; 116 117 /** 118 * Specific option value. 119 */ 120 union 121 { 122 123 /** 124 * Value if @e option is 125 * #TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_PAID. 126 */ 127 enum TALER_EXCHANGE_YesNoAll paid; 128 129 /** 130 * Value if @e option is 131 * #TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_REFUNDED. 132 */ 133 enum TALER_EXCHANGE_YesNoAll refunded; 134 135 /** 136 * Value if @e option is 137 * #TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_WIRED. 138 */ 139 enum TALER_EXCHANGE_YesNoAll wired; 140 141 /** 142 * Value if @e option is 143 * #TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_EXPIRED. 144 */ 145 enum TALER_EXCHANGE_YesNoAll expired; 146 147 /** 148 * Value if @e option is 149 * #TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_LIMIT. 150 */ 151 int64_t limit; 152 153 /** 154 * Value if @e option is 155 * #TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_OFFSET. 156 */ 157 uint64_t offset; 158 159 /** 160 * Value if @e option is 161 * #TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_DATE. 162 */ 163 struct GNUNET_TIME_Timestamp date; 164 165 /** 166 * Value if @e option is 167 * #TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_TIMEOUT. 168 */ 169 struct GNUNET_TIME_Relative timeout; 170 171 /** 172 * Value if @e option is 173 * #TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_SESSION_ID. 174 */ 175 const char *session_id; 176 177 /** 178 * Value if @e option is 179 * #TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_FULFILLMENT_URL. 180 */ 181 const char *fulfillment_url; 182 183 /** 184 * Value if @e option is 185 * #TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_SUMMARY_FILTER. 186 */ 187 const char *summary_filter; 188 189 /** 190 * Value if @e option is 191 * #TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_MAX_AGE. 192 */ 193 struct GNUNET_TIME_Relative max_age; 194 195 } details; 196 197 }; 198 199 200 /** 201 * Handle for a GET /private/orders request. 202 */ 203 struct TALER_MERCHANT_GetPrivateOrdersHandle; 204 205 206 /** 207 * Set up GET /private/orders operation. 208 * Note that you must explicitly start the operation after 209 * possibly setting options. 210 * 211 * @param ctx the context 212 * @param url base URL of the merchant backend 213 * @return handle to operation 214 */ 215 struct TALER_MERCHANT_GetPrivateOrdersHandle * 216 TALER_MERCHANT_get_private_orders_create ( 217 struct GNUNET_CURL_Context *ctx, 218 const char *url); 219 220 221 /** 222 * Terminate the list of the options. 223 * 224 * @return the terminating object of struct TALER_MERCHANT_GetPrivateOrdersOptionValue 225 */ 226 #define TALER_MERCHANT_get_private_orders_option_end_() \ 227 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 228 { \ 229 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_END \ 230 } 231 232 /** 233 * Set filter on paid status. 234 * 235 * @param p paid filter to use 236 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrdersOptionValue 237 */ 238 #define TALER_MERCHANT_get_private_orders_option_paid(p) \ 239 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 240 { \ 241 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_PAID, \ 242 .details.paid = (p) \ 243 } 244 245 /** 246 * Set filter on refunded status. 247 * 248 * @param r refunded filter to use 249 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrdersOptionValue 250 */ 251 #define TALER_MERCHANT_get_private_orders_option_refunded(r) \ 252 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 253 { \ 254 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_REFUNDED, \ 255 .details.refunded = (r) \ 256 } 257 258 /** 259 * Set filter on wired status. 260 * 261 * @param w wired filter to use 262 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrdersOptionValue 263 */ 264 #define TALER_MERCHANT_get_private_orders_option_wired(w) \ 265 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 266 { \ 267 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_WIRED, \ 268 .details.wired = (w) \ 269 } 270 271 /** 272 * Set filter on expiration status. 273 * 274 * @param e expiration filter to use 275 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrdersOptionValue 276 */ 277 #define TALER_MERCHANT_get_private_orders_option_expired(e) \ 278 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 279 { \ 280 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_EXPIRED, \ 281 .details.expired = (e) \ 282 } 283 284 /** 285 * Set limit on the number of results to return. 286 * 287 * @param l limit on the number of results to return 288 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrdersOptionValue 289 */ 290 #define TALER_MERCHANT_get_private_orders_option_limit(l) \ 291 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 292 { \ 293 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_LIMIT, \ 294 .details.limit = (l) \ 295 } 296 297 /** 298 * Set row offset from which to return results. 299 * 300 * @param o offset to use 301 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrdersOptionValue 302 */ 303 #define TALER_MERCHANT_get_private_orders_option_offset(o) \ 304 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 305 { \ 306 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_OFFSET, \ 307 .details.offset = (o) \ 308 } 309 310 /** 311 * Set date threshold for filtering. 312 * 313 * @param d date threshold to use 314 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrdersOptionValue 315 */ 316 #define TALER_MERCHANT_get_private_orders_option_date(d) \ 317 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 318 { \ 319 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_DATE, \ 320 .details.date = (d) \ 321 } 322 323 /** 324 * Set long polling timeout. 325 * 326 * @param t timeout to use 327 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrdersOptionValue 328 */ 329 #define TALER_MERCHANT_get_private_orders_option_timeout(t) \ 330 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 331 { \ 332 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_TIMEOUT, \ 333 .details.timeout = (t) \ 334 } 335 336 /** 337 * Set session ID filter. 338 * 339 * @param s session ID to filter by 340 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrdersOptionValue 341 */ 342 #define TALER_MERCHANT_get_private_orders_option_session_id(s) \ 343 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 344 { \ 345 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_SESSION_ID, \ 346 .details.session_id = (s) \ 347 } 348 349 /** 350 * Set fulfillment URL filter. 351 * 352 * @param u fulfillment URL to filter by 353 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrdersOptionValue 354 */ 355 #define TALER_MERCHANT_get_private_orders_option_fulfillment_url(u) \ 356 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 357 { \ 358 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_FULFILLMENT_URL, \ 359 .details.fulfillment_url = (u) \ 360 } 361 362 /** 363 * Set summary text filter. 364 * 365 * @param f summary filter string (case-insensitive substring match) 366 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrdersOptionValue 367 */ 368 #define TALER_MERCHANT_get_private_orders_option_summary_filter(f) \ 369 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 370 { \ 371 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_SUMMARY_FILTER, \ 372 .details.summary_filter = (f) \ 373 } 374 375 /** 376 * Set maximum age filter. Only return orders younger than the 377 * specified age. Only applicable if limit is positive. 378 * Transmitted with a granularity of one second, so sub-second 379 * parts of @a a are rounded down. 380 * @since protocol v27. 381 * 382 * @param a maximum age as a relative time 383 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrdersOptionValue 384 */ 385 #define TALER_MERCHANT_get_private_orders_option_max_age(a) \ 386 (const struct TALER_MERCHANT_GetPrivateOrdersOptionValue) \ 387 { \ 388 .option = TALER_MERCHANT_GET_PRIVATE_ORDERS_OPTION_MAX_AGE, \ 389 .details.max_age = (a) \ 390 } 391 392 393 /** 394 * Set the requested options for the operation. 395 * 396 * If any option fail other options may be or may be not applied. 397 * 398 * @param oph the request to set the options for 399 * @param num_options length of the @a options array 400 * @param options an array of options 401 * @return #GNUNET_OK on success, 402 * #GNUNET_NO on failure, 403 * #GNUNET_SYSERR on internal error 404 */ 405 enum GNUNET_GenericReturnValue 406 TALER_MERCHANT_get_private_orders_set_options_ ( 407 struct TALER_MERCHANT_GetPrivateOrdersHandle *oph, 408 unsigned int num_options, 409 const struct TALER_MERCHANT_GetPrivateOrdersOptionValue *options); 410 411 412 /** 413 * Set the requested options for the operation. 414 * 415 * If any option fail other options may be or may be not applied. 416 * 417 * It should be used with helpers that create required options, for example: 418 * 419 * TALER_MERCHANT_get_private_orders_set_options ( 420 * oph, 421 * TALER_MERCHANT_get_private_orders_option_paid ( 422 * TALER_EXCHANGE_YNA_YES), 423 * TALER_MERCHANT_get_private_orders_option_limit (-20)); 424 * 425 * @param oph the request to set the options for 426 * @param ... the list of the options, each option must be created 427 * by helpers TALER_MERCHANT_get_private_orders_option_NAME(VALUE) 428 * @return #GNUNET_OK on success, 429 * #GNUNET_NO on failure, 430 * #GNUNET_SYSERR on internal error 431 */ 432 #define TALER_MERCHANT_get_private_orders_set_options(oph,...) \ 433 TALER_MERCHANT_get_private_orders_set_options_ ( \ 434 oph, \ 435 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 436 ((const struct TALER_MERCHANT_GetPrivateOrdersOptionValue[]) \ 437 {__VA_ARGS__, TALER_MERCHANT_get_private_orders_option_end_ () } \ 438 )) 439 440 441 /** 442 * Entry for one order in the GET /private/orders response. 443 */ 444 struct TALER_MERCHANT_GetPrivateOrdersOrderEntry 445 { 446 447 /** 448 * The order identifier string. 449 */ 450 const char *order_id; 451 452 /** 453 * Timestamp when the order was created. 454 */ 455 struct GNUNET_TIME_Timestamp timestamp; 456 457 /** 458 * Serial number of the order in the database. 459 */ 460 uint64_t order_serial; 461 462 /** 463 * Total amount of the order. 464 */ 465 struct TALER_Amount amount; 466 467 /** 468 * Amount refunded so far. 469 */ 470 struct TALER_Amount refund_amount; 471 472 /** 473 * Amount still pending refund. 474 */ 475 struct TALER_Amount pending_refund_amount; 476 477 /** 478 * Short summary of the order. 479 */ 480 const char *summary; 481 482 /** 483 * True if refund is possible. 484 */ 485 bool refundable; 486 487 /** 488 * True if the order has been paid. 489 */ 490 bool paid; 491 492 /** 493 * True if the exchange reports that it wired the order's funds. 494 * False if the response came from a backend older than protocol v38. 495 * @since protocol v38. 496 */ 497 bool wired; 498 499 /** 500 * Deadline by which the order must be paid. 501 * Zero if the response came from a backend older than protocol v37. 502 * @since protocol v37. 503 */ 504 struct GNUNET_TIME_Timestamp pay_deadline; 505 506 }; 507 508 509 /** 510 * Response details for a GET /private/orders request. 511 */ 512 struct TALER_MERCHANT_GetPrivateOrdersResponse 513 { 514 515 /** 516 * HTTP response details. 517 */ 518 struct TALER_MERCHANT_HttpResponse hr; 519 520 /** 521 * Details depending on the HTTP status code. 522 */ 523 union 524 { 525 526 /** 527 * Details on #MHD_HTTP_OK. 528 */ 529 struct 530 { 531 532 /** 533 * Number of orders in @a orders. 534 */ 535 unsigned int orders_length; 536 537 /** 538 * Array of order entries. 539 */ 540 const struct TALER_MERCHANT_GetPrivateOrdersOrderEntry *orders; 541 542 } ok; 543 544 } details; 545 546 }; 547 548 549 #ifndef TALER_MERCHANT_GET_PRIVATE_ORDERS_RESULT_CLOSURE 550 /** 551 * Type of the closure used by 552 * the #TALER_MERCHANT_GetPrivateOrdersCallback. 553 */ 554 #define TALER_MERCHANT_GET_PRIVATE_ORDERS_RESULT_CLOSURE void 555 #endif /* TALER_MERCHANT_GET_PRIVATE_ORDERS_RESULT_CLOSURE */ 556 557 /** 558 * Callback for a GET /private/orders request. 559 * 560 * @param cls closure 561 * @param ogr response details 562 */ 563 typedef void 564 (*TALER_MERCHANT_GetPrivateOrdersCallback)( 565 TALER_MERCHANT_GET_PRIVATE_ORDERS_RESULT_CLOSURE *cls, 566 const struct TALER_MERCHANT_GetPrivateOrdersResponse *ogr); 567 568 569 /** 570 * Start GET /private/orders operation. 571 * 572 * @param[in,out] oph operation to start 573 * @param cb function to call with the merchant's result 574 * @param cb_cls closure for @a cb 575 * @return status code, #TALER_EC_NONE on success 576 */ 577 enum TALER_ErrorCode 578 TALER_MERCHANT_get_private_orders_start ( 579 struct TALER_MERCHANT_GetPrivateOrdersHandle *oph, 580 TALER_MERCHANT_GetPrivateOrdersCallback cb, 581 TALER_MERCHANT_GET_PRIVATE_ORDERS_RESULT_CLOSURE *cb_cls); 582 583 584 /** 585 * Cancel GET /private/orders operation. This function must not be 586 * called by clients after the TALER_MERCHANT_GetPrivateOrdersCallback 587 * has been invoked (as in those cases it'll be called internally by 588 * the implementation already). 589 * 590 * @param[in] oph operation to cancel 591 */ 592 void 593 TALER_MERCHANT_get_private_orders_cancel ( 594 struct TALER_MERCHANT_GetPrivateOrdersHandle *oph); 595 596 597 #endif /* _TALER_MERCHANT__GET_PRIVATE_ORDERS_H */