post-private-orders.h (6891B)
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 POST /private/orders of the merchant backend 20 * @author Christian Grothoff 21 * @author Marcello Stanisci 22 */ 23 #ifndef _TALER_MERCHANT__POST_PRIVATE_ORDERS_H 24 #define _TALER_MERCHANT__POST_PRIVATE_ORDERS_H 25 26 #include <taler/taler-merchant/common.h> 27 28 29 /** 30 * Handle for a POST /private/orders request. 31 */ 32 struct TALER_MERCHANT_PostOrdersHandle; 33 34 35 /** 36 * One inventory product entry for POST /orders. 37 */ 38 struct TALER_MERCHANT_InventoryProduct 39 { 40 41 /** 42 * Identifier of the product in the inventory. 43 */ 44 const char *product_id; 45 46 /** 47 * How many units of this product should be ordered. 48 */ 49 uint64_t quantity; 50 51 /** 52 * Fractional component of the quantity in units of 1/1000000 of the 53 * base value. 54 */ 55 uint32_t quantity_frac; 56 57 /** 58 * Set to true if this product uses fractional quantity fields. 59 */ 60 bool use_fractional_quantity; 61 62 }; 63 64 65 /** 66 * Response details for a POST /private/orders request. 67 */ 68 struct TALER_MERCHANT_PostOrdersReply 69 { 70 71 /** 72 * HTTP response details. 73 */ 74 struct TALER_MERCHANT_HttpResponse hr; 75 76 /** 77 * Details depending on the HTTP status code. 78 */ 79 union 80 { 81 82 /** 83 * Details on #MHD_HTTP_OK. 84 */ 85 struct 86 { 87 88 /** 89 * The assigned order identifier. 90 */ 91 const char *order_id; 92 93 /** 94 * Claim token for the order, or NULL if none was issued. 95 */ 96 const struct TALER_ClaimTokenP *token; 97 98 /** 99 * Deadline by which the wallet must pay (may be zero for old backends). 100 */ 101 struct GNUNET_TIME_Timestamp pay_deadline; 102 103 } ok; 104 105 /** 106 * Details on #MHD_HTTP_GONE (product out of stock). 107 */ 108 struct 109 { 110 111 /** 112 * Identifier of the product that ran out of stock. 113 */ 114 const char *product_id; 115 116 /** 117 * Quantity that was requested. 118 */ 119 uint64_t requested_quantity; 120 121 /** 122 * Fractional part of the requested quantity. 123 */ 124 uint32_t requested_quantity_frac; 125 126 /** 127 * Quantity that is available. 128 */ 129 uint64_t available_quantity; 130 131 /** 132 * Fractional part of the available quantity. 133 */ 134 uint32_t available_quantity_frac; 135 136 /** 137 * When restocking is expected (may be zero/unset). 138 */ 139 struct GNUNET_TIME_Timestamp restock_expected; 140 141 } gone; 142 143 } details; 144 145 }; 146 147 148 /** 149 * Callback for a POST /private/orders request. 150 * 151 * @param cls closure 152 * @param por response details 153 */ 154 typedef void 155 (*TALER_MERCHANT_PostOrdersCallback)( 156 void *cls, 157 const struct TALER_MERCHANT_PostOrdersReply *por); 158 159 160 /** 161 * Issue a POST /private/orders request (simple form). 162 * 163 * @param ctx CURL context to use 164 * @param backend_url base URL of the merchant backend 165 * @param order JSON object describing the order 166 * @param refund_delay refund delay for this order 167 * @param cb callback to invoke with the result 168 * @param cb_cls closure for @a cb 169 * @return handle for the request, NULL on hard error 170 */ 171 struct TALER_MERCHANT_PostOrdersHandle * 172 TALER_MERCHANT_orders_post (struct GNUNET_CURL_Context *ctx, 173 const char *backend_url, 174 const json_t *order, 175 struct GNUNET_TIME_Relative refund_delay, 176 TALER_MERCHANT_PostOrdersCallback cb, 177 void *cb_cls); 178 179 180 /** 181 * Issue a POST /private/orders request with extended options. 182 * 183 * @param ctx CURL context to use 184 * @param backend_url base URL of the merchant backend 185 * @param order JSON object describing the order 186 * @param refund_delay refund delay for this order 187 * @param payment_target desired payment target, or NULL for default 188 * @param inventory_products_length number of entries in @a inventory_products 189 * @param inventory_products array of inventory products to lock 190 * @param uuids_length number of entries in @a uuids 191 * @param uuids array of idempotency UUIDs 192 * @param create_token whether to create a claim token 193 * @param cb callback to invoke with the result 194 * @param cb_cls closure for @a cb 195 * @return handle for the request, NULL on hard error 196 */ 197 struct TALER_MERCHANT_PostOrdersHandle * 198 TALER_MERCHANT_orders_post2 ( 199 struct GNUNET_CURL_Context *ctx, 200 const char *backend_url, 201 const json_t *order, 202 struct GNUNET_TIME_Relative refund_delay, 203 const char *payment_target, 204 unsigned int inventory_products_length, 205 const struct TALER_MERCHANT_InventoryProduct inventory_products[], 206 unsigned int uuids_length, 207 const char *uuids[], 208 bool create_token, 209 TALER_MERCHANT_PostOrdersCallback cb, 210 void *cb_cls); 211 212 213 /** 214 * Issue a POST /private/orders request with all options. 215 * 216 * @param ctx CURL context to use 217 * @param backend_url base URL of the merchant backend 218 * @param order JSON object describing the order 219 * @param session_id session identifier, or NULL 220 * @param refund_delay refund delay for this order 221 * @param payment_target desired payment target, or NULL for default 222 * @param inventory_products_length number of entries in @a inventory_products 223 * @param inventory_products array of inventory products to lock 224 * @param uuids_length number of entries in @a uuids 225 * @param uuids array of idempotency UUIDs 226 * @param create_token whether to create a claim token 227 * @param cb callback to invoke with the result 228 * @param cb_cls closure for @a cb 229 * @return handle for the request, NULL on hard error 230 */ 231 struct TALER_MERCHANT_PostOrdersHandle * 232 TALER_MERCHANT_orders_post3 ( 233 struct GNUNET_CURL_Context *ctx, 234 const char *backend_url, 235 const json_t *order, 236 const char *session_id, 237 struct GNUNET_TIME_Relative refund_delay, 238 const char *payment_target, 239 unsigned int inventory_products_length, 240 const struct TALER_MERCHANT_InventoryProduct inventory_products[], 241 unsigned int uuids_length, 242 const char *uuids[], 243 bool create_token, 244 TALER_MERCHANT_PostOrdersCallback cb, 245 void *cb_cls); 246 247 248 /** 249 * Cancel a POST /private/orders request. 250 * 251 * @param[in] po handle to cancel 252 */ 253 void 254 TALER_MERCHANT_orders_post_cancel ( 255 struct TALER_MERCHANT_PostOrdersHandle *po); 256 257 258 #endif