post-private-fountains.h (4906B)
1 /* 2 This file is part of TALER 3 Copyright (C) 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/post-private-fountains.h 19 * @brief C interface for the POST /private/fountains endpoint (DD 98) 20 * @author Bohdan Potuzhnyi 21 */ 22 #ifndef _TALER_MERCHANT__POST_PRIVATE_FOUNTAINS_H 23 #define _TALER_MERCHANT__POST_PRIVATE_FOUNTAINS_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Withdrawal rights of a fountain for one token family (DD 98). 30 */ 31 struct TALER_MERCHANT_FountainGrant 32 { 33 /** 34 * Slug of the token family this grant refers to. 35 */ 36 const char *token_family_slug; 37 38 /** 39 * Maximum number of tokens blind-signed per issue-key validity 40 * period for this family. 41 */ 42 uint64_t tokens_per_period_limit; 43 44 /** 45 * Number of tokens the wallet should aim to hold per period; 46 * at most @e tokens_per_period_limit. 47 */ 48 uint64_t tokens_per_period_stash; 49 50 /** 51 * Maximum number of future issue keys in addition to the current key. 52 * No key may start after now + key_window_size * duration. 53 * Each successive key is selected just after the previous key expires, 54 * using the token family's normal duration and rounding rules. The 55 * advertised window can be shorter if family bounds or rounding prevent 56 * further coverage. Zero allows only the current key. 57 */ 58 uint32_t key_window_size; 59 }; 60 61 62 /** 63 * Handle for a POST /private/fountains request. 64 */ 65 struct TALER_MERCHANT_PostPrivateFountainsHandle; 66 67 68 /** 69 * Response details for a POST /private/fountains request. 70 */ 71 struct TALER_MERCHANT_PostPrivateFountainsResponse 72 { 73 74 /** 75 * HTTP response details. 76 */ 77 struct TALER_MERCHANT_HttpResponse hr; 78 79 /** 80 * Details depending on the HTTP status. 81 */ 82 union 83 { 84 /** 85 * Details on #MHD_HTTP_OK. 86 */ 87 struct 88 { 89 /** 90 * Public identifier of the new fountain. 91 */ 92 const char *fountain_id; 93 94 /** 95 * Bearer credential of the new fountain, Crockford Base32. 96 * Returned exactly once; the backend stores only its hash. 97 */ 98 const char *fountain_secret; 99 } ok; 100 } details; 101 102 }; 103 104 105 #ifndef TALER_MERCHANT_POST_PRIVATE_FOUNTAINS_RESULT_CLOSURE 106 /** 107 * Type of the closure used by 108 * the #TALER_MERCHANT_PostPrivateFountainsCallback. 109 */ 110 #define TALER_MERCHANT_POST_PRIVATE_FOUNTAINS_RESULT_CLOSURE void 111 #endif /* TALER_MERCHANT_POST_PRIVATE_FOUNTAINS_RESULT_CLOSURE */ 112 113 /** 114 * Callback for a POST /private/fountains request. 115 * 116 * @param cls closure 117 * @param pfr response details 118 */ 119 typedef void 120 (*TALER_MERCHANT_PostPrivateFountainsCallback)( 121 TALER_MERCHANT_POST_PRIVATE_FOUNTAINS_RESULT_CLOSURE *cls, 122 const struct TALER_MERCHANT_PostPrivateFountainsResponse *pfr); 123 124 125 /** 126 * Set up POST /private/fountains operation. 127 * Note that you must explicitly start the operation. 128 * 129 * @param ctx the context 130 * @param url base URL of the merchant backend 131 * @param description description of the fountain 132 * @param poll_freq how often wallets should re-poll the fountain info 133 * @param num_grants length of the @a grants array 134 * @param grants withdrawal rights of the fountain 135 * @return handle to operation 136 */ 137 struct TALER_MERCHANT_PostPrivateFountainsHandle * 138 TALER_MERCHANT_post_private_fountains_create ( 139 struct GNUNET_CURL_Context *ctx, 140 const char *url, 141 const char *description, 142 struct GNUNET_TIME_Relative poll_freq, 143 unsigned int num_grants, 144 const struct TALER_MERCHANT_FountainGrant *grants); 145 146 147 /** 148 * Start POST /private/fountains operation. 149 * 150 * @param[in,out] ppfh operation to start 151 * @param cb function to call with the merchant's result 152 * @param cb_cls closure for @a cb 153 * @return status code, #TALER_EC_NONE on success 154 */ 155 enum TALER_ErrorCode 156 TALER_MERCHANT_post_private_fountains_start ( 157 struct TALER_MERCHANT_PostPrivateFountainsHandle *ppfh, 158 TALER_MERCHANT_PostPrivateFountainsCallback cb, 159 TALER_MERCHANT_POST_PRIVATE_FOUNTAINS_RESULT_CLOSURE *cb_cls); 160 161 162 /** 163 * Cancel POST /private/fountains operation. This function must not be 164 * called by clients after the callback has been invoked. 165 * 166 * @param[in] ppfh operation to cancel 167 */ 168 void 169 TALER_MERCHANT_post_private_fountains_cancel ( 170 struct TALER_MERCHANT_PostPrivateFountainsHandle *ppfh); 171 172 173 #endif /* _TALER_MERCHANT__POST_PRIVATE_FOUNTAINS_H */