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