common.h (10161B)
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/common.h 19 * @brief Common functions of libtalermerchant not specific to a particular endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__COMMON_H 23 #define _TALER_MERCHANT__COMMON_H 24 25 #include <jansson.h> 26 #include <taler/taler_util.h> 27 #include <taler/taler_error_codes.h> 28 #include <taler/taler_exchange_service.h> 29 #include <gnunet/gnunet_curl_lib.h> 30 #include <donau/donau_service.h> 31 32 33 /** 34 * Maximum number of options that can be set in one set_options 35 * call. Used as a dummy for "infinite" in the varargs case. 36 */ 37 #define TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE UINT_MAX 38 39 40 /** 41 * General information about the HTTP response we obtained 42 * from the merchant for a request. 43 */ 44 struct TALER_MERCHANT_HttpResponse 45 { 46 47 /** 48 * The complete JSON reply. NULL if we failed to parse the 49 * reply (too big, invalid JSON). 50 */ 51 const json_t *reply; 52 53 /** 54 * Set to the human-readable 'hint' that is optionally 55 * provided by the merchant together with errors. NULL 56 * if no hint was provided or if there was no error. 57 */ 58 const char *hint; 59 60 /** 61 * HTTP status code for the response. 0 if the 62 * HTTP request failed and we did not get any answer, or 63 * if the answer was invalid and we set @a ec to a 64 * client-side error code. 65 */ 66 unsigned int http_status; 67 68 /** 69 * Taler error code. #TALER_EC_NONE if everything was 70 * OK. Usually set to the "code" field of an error 71 * response, but may be set to values created at the 72 * client side, for example when the response was 73 * not in JSON format or was otherwise ill-formed. 74 */ 75 enum TALER_ErrorCode ec; 76 77 /** 78 * HTTP status code returned by the exchange, if 79 * the merchant forwarded an exchange error to us. 80 * Set to 0 if there was no exchange involved. 81 */ 82 unsigned int exchange_http_status; 83 84 /** 85 * JSON reply from the exchange, if the merchant 86 * forwarded an exchange error to us. NULL otherwise. 87 */ 88 const json_t *exchange_reply; 89 90 /** 91 * Taler error code from the exchange, if the merchant 92 * forwarded an exchange error to us. 93 */ 94 enum TALER_ErrorCode exchange_code; 95 96 /** 97 * Human-readable hint from the exchange, if the merchant 98 * forwarded an exchange error to us. NULL otherwise. 99 */ 100 const char *exchange_hint; 101 102 }; 103 104 105 /** 106 * Parse URI data for taler://pay/ URIs. 107 */ 108 struct TALER_MERCHANT_PayUriData 109 { 110 111 /** 112 * Hostname (and possibly port) of the merchant backend. 113 */ 114 char *merchant_host; 115 116 /** 117 * Prefix path at the merchant backend (may be NULL). 118 */ 119 char *merchant_prefix_path; 120 121 /** 122 * The order ID. 123 */ 124 char *order_id; 125 126 /** 127 * The session ID (may be NULL if none given). 128 */ 129 char *session_id; 130 131 /** 132 * Claim token (may be NULL if not given in the URI). 133 */ 134 struct TALER_ClaimTokenP *claim_token; 135 136 /** 137 * Subscription session ID (SSID), may be NULL. 138 */ 139 char *ssid; 140 141 /** 142 * Set to true if taler+http:// was used (test only). 143 */ 144 bool use_http; 145 146 }; 147 148 149 /** 150 * Parse URI data for taler://refund/ URIs. 151 */ 152 struct TALER_MERCHANT_RefundUriData 153 { 154 155 /** 156 * Hostname (and possibly port) of the merchant backend. 157 */ 158 char *merchant_host; 159 160 /** 161 * Prefix path at the merchant backend (may be NULL). 162 */ 163 char *merchant_prefix_path; 164 165 /** 166 * The order ID. 167 */ 168 char *order_id; 169 170 /** 171 * Subscription session ID (SSID), may be NULL. 172 */ 173 char *ssid; 174 175 /** 176 * Set to true if taler+http:// was used (test only). 177 */ 178 bool use_http; 179 180 }; 181 182 /** 183 * Entry for one measurement unit. 184 */ 185 struct TALER_MERCHANT_UnitEntry 186 { 187 188 /** 189 * Identifier of the unit. 190 */ 191 const char *unit; 192 193 /** 194 * Long (human-readable) name of the unit. 195 */ 196 const char *unit_name_long; 197 198 /** 199 * Short symbol for the unit. 200 */ 201 const char *unit_name_short; 202 203 const json_t *unit_name_long_i18n; 204 205 const json_t *unit_name_short_i18n; 206 207 /** 208 * Whether fractional quantities are allowed. 209 */ 210 bool unit_allow_fraction; 211 212 /** 213 * Precision level for fractional quantities. 214 */ 215 uint32_t unit_precision_level; 216 217 /** 218 * Whether this unit is currently active. 219 */ 220 bool unit_active; 221 222 bool unit_builtin; 223 224 /** 225 * Serial number of this unit in the database. 226 */ 227 uint64_t unit_serial; 228 }; 229 230 231 /** 232 * Wire transfer information associated with a paid order. 233 */ 234 struct TALER_MERCHANT_WireTransfer 235 { 236 237 /** 238 * Base URL of the exchange that made the transfer. 239 */ 240 const char *exchange_url; 241 242 /** 243 * When the transfer took place (note: may not be exact, 244 * as the time at which the exchange initiated the transfer 245 * may differ from the time the bank or the merchant observed). 246 * Zero if not known. 247 */ 248 struct GNUNET_TIME_Timestamp execution_time; 249 250 /** 251 * Wire transfer subject. 252 */ 253 struct TALER_WireTransferIdentifierRawP wtid; 254 255 /** 256 * Total amount that was transferred. 257 */ 258 struct TALER_Amount total_amount; 259 260 /** 261 * Deposit fees paid to the exchange for this order. 262 * @since protocol v26. 263 */ 264 struct TALER_Amount deposit_fee; 265 266 /** 267 * Whether this transfer was confirmed by the merchant using 268 * the POST /transfers API, or whether it was merely claimed 269 * by the exchange. 270 */ 271 bool confirmed; 272 273 /** 274 * Transfer serial ID of this wire transfer, useful as 275 * offset for the GET /private/incoming endpoint. 276 * @since protocol v25. 277 */ 278 uint64_t expected_transfer_serial_id; 279 280 }; 281 282 283 /** 284 * Type of a statistics metric / aggregation mode. 285 */ 286 enum TALER_MERCHANT_StatisticsType 287 { 288 /** 289 * Return statistics aggregated by bucket. 290 */ 291 TALER_MERCHANT_STATISTICS_BY_BUCKET = 0, 292 293 /** 294 * Return statistics aggregated by time interval. 295 */ 296 TALER_MERCHANT_STATISTICS_BY_INTERVAL = 1, 297 298 /** 299 * Return all available statistics (both buckets and intervals). 300 */ 301 TALER_MERCHANT_STATISTICS_ALL = 2 302 }; 303 304 305 /** 306 * Information about a single MFA challenge sent by the merchant. 307 */ 308 struct TALER_MERCHANT_MfaChallengeEntry 309 { 310 311 /** 312 * Hint about where the challenge was sent (e.g. masked phone/email). 313 */ 314 const char *tan_info; 315 316 /** 317 * Channel used for the challenge ("sms", "email", "totp"). 318 */ 319 const char *tan_channel; 320 321 /** 322 * Challenge identifier (format: "$SERIAL-$H_BODY_HEX"). 323 */ 324 const char *challenge_id; 325 326 }; 327 328 329 /** 330 * Response from the merchant requiring multi-factor authentication. 331 * Returned as HTTP 202 Accepted. 332 */ 333 struct TALER_MERCHANT_MfaChallengeResponse 334 { 335 336 /** 337 * If true, all challenges must be solved (AND combination). 338 * If false, solving any one challenge suffices (OR combination). 339 */ 340 bool combi_and; 341 342 /** 343 * Number of entries in @e challenges. 344 */ 345 unsigned int challenges_length; 346 347 /** 348 * Array of MFA challenges the client must solve. 349 */ 350 struct TALER_MERCHANT_MfaChallengeEntry *challenges; 351 352 }; 353 354 355 /** 356 * Free data within a #TALER_MERCHANT_MfaChallengeResponse (but not 357 * the struct itself). 358 * 359 * @param cr response to clean up 360 */ 361 void 362 TALER_MERCHANT_mfa_challenge_response_free ( 363 struct TALER_MERCHANT_MfaChallengeResponse *cr); 364 365 366 /** 367 * Parse a taler://pay/ URI into its components. 368 * 369 * @param pay_uri the URI to parse 370 * @param[out] parse_data parsed URI data, to be freed with 371 * #TALER_MERCHANT_parse_pay_uri_free() 372 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 373 */ 374 enum GNUNET_GenericReturnValue 375 TALER_MERCHANT_parse_pay_uri (const char *pay_uri, 376 struct TALER_MERCHANT_PayUriData *parse_data); 377 378 379 /** 380 * Free a #TALER_MERCHANT_PayUriData previously obtained from 381 * #TALER_MERCHANT_parse_pay_uri(). 382 * 383 * @param[in] parse_data the data to free (fields only, not the struct itself) 384 */ 385 void 386 TALER_MERCHANT_parse_pay_uri_free ( 387 struct TALER_MERCHANT_PayUriData *parse_data); 388 389 390 /** 391 * Parse a taler://refund/ URI into its components. 392 * 393 * @param refund_uri the URI to parse 394 * @param[out] parse_data parsed URI data, to be freed with 395 * #TALER_MERCHANT_parse_refund_uri_free() 396 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 397 */ 398 enum GNUNET_GenericReturnValue 399 TALER_MERCHANT_parse_refund_uri ( 400 const char *refund_uri, 401 struct TALER_MERCHANT_RefundUriData *parse_data); 402 403 404 /** 405 * Free a #TALER_MERCHANT_RefundUriData previously obtained from 406 * #TALER_MERCHANT_parse_refund_uri(). 407 * 408 * @param[in] parse_data the data to free (fields only, not the struct itself) 409 */ 410 void 411 TALER_MERCHANT_parse_refund_uri_free ( 412 struct TALER_MERCHANT_RefundUriData *parse_data); 413 414 415 /** 416 * Format a quantity into its decimal string representation. 417 * 418 * @param quantity integer part of the quantity 419 * @param quantity_frac fractional part 420 * @param[out] buffer output buffer 421 * @param buffer_length size of @a buffer 422 */ 423 void 424 TALER_MERCHANT_format_quantity_string (uint64_t quantity, 425 uint32_t quantity_frac, 426 char *buffer, 427 size_t buffer_length); 428 429 430 /** 431 * Format a stock value into its decimal string representation. 432 * 433 * @param total_stock integer part of the stock value 434 * @param total_stock_frac fractional part 435 * @param[out] buffer output buffer 436 * @param buffer_length size of @a buffer 437 */ 438 void 439 TALER_MERCHANT_format_stock_string (uint64_t total_stock, 440 uint32_t total_stock_frac, 441 char *buffer, 442 size_t buffer_length); 443 444 445 #endif