post-reserves-RESERVE_PUB-purse.h (8415B)
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 Affero General Public License as published by the Free Software 7 Foundation; either version 3, 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 Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file include/taler/exchange/post-reserves-RESERVE_PUB-purse.h 18 * @brief C interface for POST /reserves/$RESERVE_PUB/purse 19 * @author Christian Grothoff 20 */ 21 #ifndef _TALER_EXCHANGE__POST_RESERVES_RESERVE_PUB_PURSE_H 22 #define _TALER_EXCHANGE__POST_RESERVES_RESERVE_PUB_PURSE_H 23 24 #include <taler/exchange/common.h> 25 26 27 /** 28 * Possible options we can set for the POST /reserves/$RESERVE_PUB/purse request. 29 */ 30 enum TALER_EXCHANGE_PostReservesPurseOption 31 { 32 /** 33 * End of list of options. 34 */ 35 TALER_EXCHANGE_POST_RESERVES_PURSE_OPTION_END = 0, 36 37 /** 38 * Upload the contract to the exchange. 39 * If not set, defaults to not uploading the contract. 40 */ 41 TALER_EXCHANGE_POST_RESERVES_PURSE_OPTION_UPLOAD_CONTRACT 42 43 }; 44 45 46 /** 47 * Value for an option we can set for the POST /reserves/$RESERVE_PUB/purse request. 48 */ 49 struct TALER_EXCHANGE_PostReservesPurseOptionValue 50 { 51 /** 52 * Type of the option being set. 53 */ 54 enum TALER_EXCHANGE_PostReservesPurseOption option; 55 56 /** 57 * Specific option value. 58 */ 59 union 60 { 61 } details; 62 63 }; 64 65 66 /** 67 * Handle for an operation to POST /reserves/$RESERVE_PUB/purse. 68 */ 69 struct TALER_EXCHANGE_PostReservesPurseHandle; 70 71 72 /** 73 * Set up POST /reserves/$RESERVE_PUB/purse operation. 74 * Note that you must explicitly start the operation after setup. 75 * 76 * @param ctx curl context 77 * @param url exchange base URL 78 * @param keys exchange keys 79 * @param reserve_priv private key of the reserve 80 * @param purse_priv private key of the purse 81 * @param merge_priv private key of the merge capability 82 * @param contract_priv private key to get the contract 83 * @param contract_terms contract the purse is about 84 * @param pay_for_purse true to pay for purse creation 85 * @param merge_timestamp when should the merge happen (use current time) 86 * @return handle to operation, NULL on error 87 */ 88 struct TALER_EXCHANGE_PostReservesPurseHandle * 89 TALER_EXCHANGE_post_reserves_purse_create ( 90 struct GNUNET_CURL_Context *ctx, 91 const char *url, 92 struct TALER_EXCHANGE_Keys *keys, 93 const struct TALER_ReservePrivateKeyP *reserve_priv, 94 const struct TALER_PurseContractPrivateKeyP *purse_priv, 95 const struct TALER_PurseMergePrivateKeyP *merge_priv, 96 const struct TALER_ContractDiffiePrivateP *contract_priv, 97 const json_t *contract_terms, 98 bool pay_for_purse, // FIXME: turn into option (default: false) 99 struct GNUNET_TIME_Timestamp merge_timestamp); 100 101 102 /** 103 * Terminate the list of options. 104 * 105 * @return the terminating object of struct TALER_EXCHANGE_PostReservesPurseOptionValue 106 */ 107 #define TALER_EXCHANGE_post_reserves_purse_option_end_() \ 108 (const struct TALER_EXCHANGE_PostReservesPurseOptionValue) \ 109 { \ 110 .option = TALER_EXCHANGE_POST_RESERVES_PURSE_OPTION_END \ 111 } 112 113 /** 114 * Set flag to upload the contract to the exchange to true. 115 * 116 * @return representation of the option as a struct TALER_EXCHANGE_PostReservesPurseOptionValue 117 */ 118 #define TALER_EXCHANGE_post_reserves_purse_option_upload_contract() \ 119 (const struct TALER_EXCHANGE_PostReservesPurseOptionValue) \ 120 { \ 121 .option = TALER_EXCHANGE_POST_RESERVES_PURSE_OPTION_UPLOAD_CONTRACT, \ 122 } 123 124 125 /** 126 * Set the requested options for the operation. 127 * 128 * If any option fails, other options may or may not be applied. 129 * 130 * @param prph the request to set the options for 131 * @param num_options length of the @a options array 132 * @param options an array of options 133 * @return #GNUNET_OK on success, 134 * #GNUNET_NO on failure, 135 * #GNUNET_SYSERR on internal error 136 */ 137 enum GNUNET_GenericReturnValue 138 TALER_EXCHANGE_post_reserves_purse_set_options_ ( 139 struct TALER_EXCHANGE_PostReservesPurseHandle *prph, 140 unsigned int num_options, 141 const struct TALER_EXCHANGE_PostReservesPurseOptionValue options[]); 142 143 144 /** 145 * Set the requested options for the operation. 146 * 147 * If any option fails, other options may or may not be applied. 148 * 149 * @param prph the request to set the options for 150 * @param ... the list of the options, each option must be created 151 * by helpers TALER_EXCHANGE_post_reserves_purse_option_NAME(VALUE) 152 * @return #GNUNET_OK on success, 153 * #GNUNET_NO on failure, 154 * #GNUNET_SYSERR on internal error 155 */ 156 #define TALER_EXCHANGE_post_reserves_purse_set_options(prph,...) \ 157 TALER_EXCHANGE_post_reserves_purse_set_options_ ( \ 158 prph, \ 159 TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 160 ((const struct TALER_EXCHANGE_PostReservesPurseOptionValue[]) \ 161 {__VA_ARGS__, \ 162 TALER_EXCHANGE_post_reserves_purse_option_end_ ()} \ 163 )) 164 165 166 /** 167 * Response generated for a purse creation request via reserve. 168 */ 169 struct TALER_EXCHANGE_PostReservesPurseResponse 170 { 171 /** 172 * Full HTTP response. 173 */ 174 struct TALER_EXCHANGE_HttpResponse hr; 175 176 /** 177 * Reserve signature generated for the request 178 * (client-side). 179 */ 180 const struct TALER_ReserveSignatureP *reserve_sig; 181 182 /** 183 * Details depending on the HTTP status. 184 */ 185 union 186 { 187 /** 188 * Details returned on #MHD_HTTP_OK. 189 */ 190 struct 191 { 192 193 /** 194 * Signature by the exchange affirming the purse creation. 195 */ 196 struct TALER_ExchangeSignatureP exchange_sig; 197 198 /** 199 * Online signing key used by the exchange. 200 */ 201 struct TALER_ExchangePublicKeyP exchange_pub; 202 203 /** 204 * Timestamp of the exchange for @e exchange_sig. 205 */ 206 struct GNUNET_TIME_Timestamp exchange_timestamp; 207 208 /** 209 * Amount deposited (excluding deposit fees). 210 */ 211 struct TALER_Amount total_deposited; 212 213 } ok; 214 215 /** 216 * Details if the status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS. 217 */ 218 struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons; 219 220 } details; 221 222 }; 223 224 225 #ifndef TALER_EXCHANGE_POST_RESERVES_PURSE_RESULT_CLOSURE 226 /** 227 * Type of the closure used by 228 * the #TALER_EXCHANGE_PostReservesPurseCallback. 229 */ 230 #define TALER_EXCHANGE_POST_RESERVES_PURSE_RESULT_CLOSURE void 231 #endif /* TALER_EXCHANGE_POST_RESERVES_PURSE_RESULT_CLOSURE */ 232 233 /** 234 * Type of the function that receives the result of a 235 * POST /reserves/$RESERVE_PUB/purse request. 236 * 237 * @param cls closure 238 * @param result result returned by the HTTP server 239 */ 240 typedef void 241 (*TALER_EXCHANGE_PostReservesPurseCallback)( 242 TALER_EXCHANGE_POST_RESERVES_PURSE_RESULT_CLOSURE *cls, 243 const struct TALER_EXCHANGE_PostReservesPurseResponse *result); 244 245 246 /** 247 * Start POST /reserves/$RESERVE_PUB/purse operation. 248 * 249 * @param[in,out] prph operation to start 250 * @param cb function to call with the exchange's result 251 * @param cb_cls closure for @a cb 252 * @return status code, #TALER_EC_NONE on success 253 */ 254 enum TALER_ErrorCode 255 TALER_EXCHANGE_post_reserves_purse_start ( 256 struct TALER_EXCHANGE_PostReservesPurseHandle *prph, 257 TALER_EXCHANGE_PostReservesPurseCallback cb, 258 TALER_EXCHANGE_POST_RESERVES_PURSE_RESULT_CLOSURE *cb_cls); 259 260 261 /** 262 * Cancel POST /reserves/$RESERVE_PUB/purse operation. This function must not 263 * be called by clients after the TALER_EXCHANGE_PostReservesPurseCallback has 264 * been invoked (as in those cases it'll be called internally by the 265 * implementation already). 266 * 267 * @param[in] prph operation to cancel 268 */ 269 void 270 TALER_EXCHANGE_post_reserves_purse_cancel ( 271 struct TALER_EXCHANGE_PostReservesPurseHandle *prph); 272 273 274 #endif /* _TALER_EXCHANGE__POST_RESERVES_RESERVE_PUB_PURSE_H */