get-private-products-PRODUCT_ID.h (4573B)
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-private-products-PRODUCT_ID.h 19 * @brief C interface for GET /private/products/$PRODUCT_ID of the merchant backend 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__GET_PRIVATE_PRODUCTS_PRODUCT_ID_H 23 #define _TALER_MERCHANT__GET_PRIVATE_PRODUCTS_PRODUCT_ID_H 24 25 #include <taler/taler-merchant/common.h> 26 27 28 /** 29 * Handle for a GET /private/products/$PRODUCT_ID request. 30 */ 31 struct TALER_MERCHANT_ProductGetHandle; 32 33 34 /** 35 * Response details for a GET /private/products/$PRODUCT_ID request. 36 */ 37 struct TALER_MERCHANT_ProductGetResponse 38 { 39 40 /** 41 * HTTP response details. 42 */ 43 struct TALER_MERCHANT_HttpResponse hr; 44 45 /** 46 * Details depending on the HTTP status code. 47 */ 48 union 49 { 50 51 /** 52 * Details on #MHD_HTTP_OK. 53 */ 54 struct 55 { 56 57 /** 58 * Human-readable product name. 59 */ 60 const char *product_name; 61 62 /** 63 * Human-readable product description. 64 */ 65 const char *description; 66 67 /** 68 * Internationalized descriptions (JSON object), or NULL. 69 */ 70 const json_t *description_i18n; 71 72 /** 73 * Unit of measurement for this product. 74 */ 75 const char *unit; 76 77 /** 78 * Number of prices in @a unit_price. 79 */ 80 size_t unit_price_len; 81 82 /** 83 * Array of unit prices (for different payment options). 84 */ 85 const struct TALER_Amount *unit_price; 86 87 /** 88 * Single unit price (first element of @a unit_price, for backwards compatibility). 89 */ 90 struct TALER_Amount price; 91 92 /** 93 * Base64-encoded product image, or empty string. 94 */ 95 const char *image; 96 97 /** 98 * Tax information (JSON array), or NULL. 99 */ 100 const json_t *taxes; 101 102 /** 103 * Total available stock (-1 for unlimited). 104 */ 105 int64_t total_stock; 106 107 /** 108 * Total stock in fractional unit representation. 109 * Stock level encoded as a decimal string. Preferred source of truth for fractional stock. 110 */ 111 const char *unit_total_stock; 112 113 /** 114 * Whether fractional quantities are allowed. 115 */ 116 bool unit_allow_fraction; 117 118 /** 119 * Precision level for fractional quantities. 120 */ 121 uint32_t unit_precision_level; 122 123 /** 124 * Total number of units sold. 125 */ 126 uint64_t total_sold; 127 128 /** 129 * Total number of units lost/expired. 130 */ 131 uint64_t total_lost; 132 133 /** 134 * Storage location (JSON), or NULL. 135 */ 136 const json_t *location; 137 138 /** 139 * Expected time of next restock (may be zero if unknown). 140 */ 141 struct GNUNET_TIME_Timestamp next_restock; 142 143 } ok; 144 145 } details; 146 147 }; 148 149 150 /** 151 * Callback for a GET /private/products/$PRODUCT_ID request. 152 * 153 * @param cls closure 154 * @param pgr response details 155 */ 156 typedef void 157 (*TALER_MERCHANT_ProductGetCallback)( 158 void *cls, 159 const struct TALER_MERCHANT_ProductGetResponse *pgr); 160 161 162 /** 163 * Issue a GET /private/products/$PRODUCT_ID request. 164 * 165 * @param ctx CURL context to use 166 * @param backend_url base URL of the merchant backend 167 * @param product_id identifier of the product to retrieve 168 * @param cb callback to invoke with the result 169 * @param cb_cls closure for @a cb 170 * @return handle for the request, NULL on hard error 171 */ 172 struct TALER_MERCHANT_ProductGetHandle * 173 TALER_MERCHANT_product_get (struct GNUNET_CURL_Context *ctx, 174 const char *backend_url, 175 const char *product_id, 176 TALER_MERCHANT_ProductGetCallback cb, 177 void *cb_cls); 178 179 180 /** 181 * Cancel a GET /private/products/$PRODUCT_ID request. 182 * 183 * @param[in] pgh handle to cancel 184 */ 185 void 186 TALER_MERCHANT_product_get_cancel ( 187 struct TALER_MERCHANT_ProductGetHandle *pgh); 188 189 190 #endif