get-orders-ORDER_ID.h (13048B)
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/get-orders-ORDER_ID.h 19 * @brief C interface for the GET /orders/$ORDER_ID endpoint (wallet-facing) 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__GET_ORDERS_ORDER_ID_H 23 #define _TALER_MERCHANT__GET_ORDERS_ORDER_ID_H 24 25 #include <taler/taler-merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the GET /orders/$ORDER_ID request. 30 */ 31 enum TALER_MERCHANT_GetOrdersOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_GET_ORDERS_OPTION_END = 0, 37 38 /** 39 * Long polling timeout. 40 */ 41 TALER_MERCHANT_GET_ORDERS_OPTION_TIMEOUT, 42 43 /** 44 * Session ID for repurchase detection. 45 */ 46 TALER_MERCHANT_GET_ORDERS_OPTION_SESSION_ID, 47 48 /** 49 * Minimum refund amount to wait for. 50 */ 51 TALER_MERCHANT_GET_ORDERS_OPTION_MIN_REFUND, 52 53 /** 54 * If true, wait until refund is confirmed obtained. 55 */ 56 TALER_MERCHANT_GET_ORDERS_OPTION_AWAIT_REFUND_OBTAINED, 57 58 /** 59 * Hash of the contract terms (for authentication). 60 */ 61 TALER_MERCHANT_GET_ORDERS_OPTION_H_CONTRACT, 62 63 /** 64 * Claim token for unclaimed order authentication. 65 */ 66 TALER_MERCHANT_GET_ORDERS_OPTION_TOKEN, 67 68 /** 69 * Whether refunded orders count for repurchase detection. 70 */ 71 TALER_MERCHANT_GET_ORDERS_OPTION_ALLOW_REFUNDED_FOR_REPURCHASE 72 73 }; 74 75 76 /** 77 * Value for an option for the GET /orders/$ORDER_ID request. 78 */ 79 struct TALER_MERCHANT_GetOrdersOptionValue 80 { 81 82 /** 83 * Type of the option being set. 84 */ 85 enum TALER_MERCHANT_GetOrdersOption option; 86 87 /** 88 * Specific option value. 89 */ 90 union 91 { 92 93 /** 94 * Value if @e option is 95 * #TALER_MERCHANT_GET_ORDERS_OPTION_TIMEOUT. 96 */ 97 struct GNUNET_TIME_Relative timeout; 98 99 /** 100 * Value if @e option is 101 * #TALER_MERCHANT_GET_ORDERS_OPTION_SESSION_ID. 102 */ 103 const char *session_id; 104 105 /** 106 * Value if @e option is 107 * #TALER_MERCHANT_GET_ORDERS_OPTION_MIN_REFUND. 108 */ 109 struct TALER_Amount min_refund; 110 111 /** 112 * Value if @e option is 113 * #TALER_MERCHANT_GET_ORDERS_OPTION_AWAIT_REFUND_OBTAINED. 114 */ 115 bool await_refund_obtained; 116 117 /** 118 * Value if @e option is 119 * #TALER_MERCHANT_GET_ORDERS_OPTION_H_CONTRACT. 120 */ 121 struct TALER_PrivateContractHashP h_contract; 122 123 /** 124 * Value if @e option is 125 * #TALER_MERCHANT_GET_ORDERS_OPTION_TOKEN. 126 */ 127 struct TALER_ClaimTokenP token; 128 129 /** 130 * Value if @e option is 131 * #TALER_MERCHANT_GET_ORDERS_OPTION_ALLOW_REFUNDED_FOR_REPURCHASE. 132 */ 133 enum TALER_EXCHANGE_YesNoAll allow_refunded_for_repurchase; 134 135 } details; 136 137 }; 138 139 140 /** 141 * Handle for a GET /orders/$ORDER_ID request (wallet-facing). 142 */ 143 struct TALER_MERCHANT_GetOrdersHandle; 144 145 146 /** 147 * Set up GET /orders/$ORDER_ID operation (wallet-facing). 148 * Note that you must explicitly start the operation after 149 * possibly setting options. 150 * 151 * @param ctx the context 152 * @param url base URL of the merchant backend 153 * @param order_id identifier of the order to check 154 * @return handle to operation 155 */ 156 struct TALER_MERCHANT_GetOrdersHandle * 157 TALER_MERCHANT_get_orders_create ( 158 struct GNUNET_CURL_Context *ctx, 159 const char *url, 160 const char *order_id); 161 162 163 /** 164 * Terminate the list of the options. 165 * 166 * @return the terminating object of struct TALER_MERCHANT_GetOrdersOptionValue 167 */ 168 #define TALER_MERCHANT_get_orders_option_end_() \ 169 (const struct TALER_MERCHANT_GetOrdersOptionValue) \ 170 { \ 171 .option = TALER_MERCHANT_GET_ORDERS_OPTION_END \ 172 } 173 174 /** 175 * Set long polling timeout. 176 * 177 * @param t timeout to use 178 * @return representation of the option as a struct TALER_MERCHANT_GetOrdersOptionValue 179 */ 180 #define TALER_MERCHANT_get_orders_option_timeout(t) \ 181 (const struct TALER_MERCHANT_GetOrdersOptionValue) \ 182 { \ 183 .option = TALER_MERCHANT_GET_ORDERS_OPTION_TIMEOUT, \ 184 .details.timeout = (t) \ 185 } 186 187 /** 188 * Set session ID for repurchase detection. 189 * 190 * @param s session ID to use 191 * @return representation of the option as a struct TALER_MERCHANT_GetOrdersOptionValue 192 */ 193 #define TALER_MERCHANT_get_orders_option_session_id(s) \ 194 (const struct TALER_MERCHANT_GetOrdersOptionValue) \ 195 { \ 196 .option = TALER_MERCHANT_GET_ORDERS_OPTION_SESSION_ID, \ 197 .details.session_id = (s) \ 198 } 199 200 /** 201 * Set minimum refund amount to wait for. 202 * 203 * @param a minimum refund amount 204 * @return representation of the option as a struct TALER_MERCHANT_GetOrdersOptionValue 205 */ 206 #define TALER_MERCHANT_get_orders_option_min_refund(a) \ 207 (const struct TALER_MERCHANT_GetOrdersOptionValue) \ 208 { \ 209 .option = TALER_MERCHANT_GET_ORDERS_OPTION_MIN_REFUND, \ 210 .details.min_refund = (a) \ 211 } 212 213 /** 214 * Set await refund obtained flag. 215 * 216 * @param b true to wait until refund is confirmed obtained 217 * @return representation of the option as a struct TALER_MERCHANT_GetOrdersOptionValue 218 */ 219 #define TALER_MERCHANT_get_orders_option_await_refund_obtained(b) \ 220 (const struct TALER_MERCHANT_GetOrdersOptionValue) \ 221 { \ 222 .option = TALER_MERCHANT_GET_ORDERS_OPTION_AWAIT_REFUND_OBTAINED, \ 223 .details.await_refund_obtained = (b) \ 224 } 225 226 /** 227 * Set hash of the contract terms (for authentication). 228 * 229 * @param h hash of contract terms 230 * @return representation of the option as a struct TALER_MERCHANT_GetOrdersOptionValue 231 */ 232 #define TALER_MERCHANT_get_orders_option_h_contract(h) \ 233 (const struct TALER_MERCHANT_GetOrdersOptionValue) \ 234 { \ 235 .option = TALER_MERCHANT_GET_ORDERS_OPTION_H_CONTRACT, \ 236 .details.h_contract = (h) \ 237 } 238 239 /** 240 * Set claim token for unclaimed order authentication. 241 * 242 * @param t claim token 243 * @return representation of the option as a struct TALER_MERCHANT_GetOrdersOptionValue 244 */ 245 #define TALER_MERCHANT_get_orders_option_token(t) \ 246 (const struct TALER_MERCHANT_GetOrdersOptionValue) \ 247 { \ 248 .option = TALER_MERCHANT_GET_ORDERS_OPTION_TOKEN, \ 249 .details.token = (t) \ 250 } 251 252 /** 253 * Set whether refunded orders count for repurchase detection. 254 * 255 * @param v yes/no/all value 256 * @return representation of the option as a struct TALER_MERCHANT_GetOrdersOptionValue 257 */ 258 #define TALER_MERCHANT_get_orders_option_allow_refunded_for_repurchase(v) \ 259 (const struct TALER_MERCHANT_GetOrdersOptionValue) \ 260 { \ 261 .option = TALER_MERCHANT_GET_ORDERS_OPTION_ALLOW_REFUNDED_FOR_REPURCHASE, \ 262 .details.allow_refunded_for_repurchase = (v) \ 263 } 264 265 266 /** 267 * Set the requested options for the operation. 268 * 269 * If any option fail other options may be or may be not applied. 270 * 271 * @param oph the request to set the options for 272 * @param num_options length of the @a options array 273 * @param options an array of options 274 * @return #GNUNET_OK on success, 275 * #GNUNET_NO on failure, 276 * #GNUNET_SYSERR on internal error 277 */ 278 enum GNUNET_GenericReturnValue 279 TALER_MERCHANT_get_orders_set_options_ ( 280 struct TALER_MERCHANT_GetOrdersHandle *oph, 281 unsigned int num_options, 282 const struct TALER_MERCHANT_GetOrdersOptionValue *options); 283 284 285 /** 286 * Set the requested options for the operation. 287 * 288 * If any option fail other options may be or may be not applied. 289 * 290 * It should be used with helpers that create required options, for example: 291 * 292 * TALER_MERCHANT_get_orders_set_options ( 293 * oph, 294 * TALER_MERCHANT_get_orders_option_timeout ( 295 * GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 30)), 296 * TALER_MERCHANT_get_orders_option_session_id ("mysession")); 297 * 298 * @param oph the request to set the options for 299 * @param ... the list of the options, each option must be created 300 * by helpers TALER_MERCHANT_get_orders_option_NAME(VALUE) 301 * @return #GNUNET_OK on success, 302 * #GNUNET_NO on failure, 303 * #GNUNET_SYSERR on internal error 304 */ 305 #define TALER_MERCHANT_get_orders_set_options(oph,...) \ 306 TALER_MERCHANT_get_orders_set_options_ ( \ 307 oph, \ 308 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 309 ((const struct TALER_MERCHANT_GetOrdersOptionValue[]) \ 310 {__VA_ARGS__, TALER_MERCHANT_get_orders_option_end_ () } \ 311 )) 312 313 314 /** 315 * Response details for a GET /orders/$ORDER_ID request (wallet-facing). 316 */ 317 struct TALER_MERCHANT_GetOrdersResponse 318 { 319 320 /** 321 * HTTP response details. 322 */ 323 struct TALER_MERCHANT_HttpResponse hr; 324 325 /** 326 * Details depending on the HTTP status code. 327 */ 328 union 329 { 330 331 /** 332 * Details on #MHD_HTTP_OK (order is paid, refund info available). 333 */ 334 struct 335 { 336 337 /** 338 * True if a refund has been granted. 339 */ 340 bool refunded; 341 342 /** 343 * True if a refund is still pending. 344 */ 345 bool refund_pending; 346 347 /** 348 * Total amount refunded. 349 */ 350 struct TALER_Amount refund_amount; 351 352 /** 353 * Total amount of refunds taken by the wallet so far. 354 */ 355 struct TALER_Amount refund_taken; 356 357 } ok; 358 359 /** 360 * Details on #MHD_HTTP_ACCEPTED (order claimed, goto reorder URL). 361 */ 362 struct 363 { 364 365 /** 366 * URL where the client should go to create a fresh order 367 * or trigger repurchase detection. 368 */ 369 const char *public_reorder_url; 370 371 } accepted; 372 373 /** 374 * Details on #MHD_HTTP_PAYMENT_REQUIRED (order not yet paid). 375 */ 376 struct 377 { 378 379 /** 380 * Taler pay URI for this order. 381 */ 382 const char *taler_pay_uri; 383 384 /** 385 * Order ID of a previously paid order that covers this one, 386 * or NULL if none. 387 */ 388 const char *already_paid_order_id; 389 390 /** 391 * Fulfillment URL of the order, or NULL if not available. 392 */ 393 const char *fulfillment_url; 394 395 } payment_required; 396 397 } details; 398 399 }; 400 401 402 #ifndef TALER_MERCHANT_GET_ORDERS_RESULT_CLOSURE 403 /** 404 * Type of the closure used by 405 * the #TALER_MERCHANT_GetOrdersCallback. 406 */ 407 #define TALER_MERCHANT_GET_ORDERS_RESULT_CLOSURE void 408 #endif /* TALER_MERCHANT_GET_ORDERS_RESULT_CLOSURE */ 409 410 /** 411 * Callback for a GET /orders/$ORDER_ID request (wallet-facing). 412 * 413 * @param cls closure 414 * @param owgr response details 415 */ 416 typedef void 417 (*TALER_MERCHANT_GetOrdersCallback)( 418 TALER_MERCHANT_GET_ORDERS_RESULT_CLOSURE *cls, 419 const struct TALER_MERCHANT_GetOrdersResponse *owgr); 420 421 422 /** 423 * Start GET /orders/$ORDER_ID operation (wallet-facing). 424 * 425 * @param[in,out] oph operation to start 426 * @param cb function to call with the merchant's result 427 * @param cb_cls closure for @a cb 428 * @return status code, #TALER_EC_NONE on success 429 */ 430 enum TALER_ErrorCode 431 TALER_MERCHANT_get_orders_start ( 432 struct TALER_MERCHANT_GetOrdersHandle *oph, 433 TALER_MERCHANT_GetOrdersCallback cb, 434 TALER_MERCHANT_GET_ORDERS_RESULT_CLOSURE *cb_cls); 435 436 437 /** 438 * Cancel GET /orders/$ORDER_ID operation (wallet-facing). This function 439 * must not be called by clients after the TALER_MERCHANT_GetOrdersCallback 440 * has been invoked (as in those cases it'll be called internally by 441 * the implementation already). 442 * 443 * @param[in] oph operation to cancel 444 */ 445 void 446 TALER_MERCHANT_get_orders_cancel ( 447 struct TALER_MERCHANT_GetOrdersHandle *oph); 448 449 450 #endif /* _TALER_MERCHANT__GET_ORDERS_ORDER_ID_H */