get-reserves-RESERVE_PUB.h (7191B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2025, 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/taler-exchange/get-reserves-RESERVE_PUB.h 18 * @brief C interface for GET /reserves/$RESERVE_PUB 19 * @author Christian Grothoff 20 */ 21 #ifndef _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_H 22 #define _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_H 23 24 #include <taler/taler-exchange/common.h> 25 26 27 /** 28 * Possible options we can set for the GET reserves request. 29 */ 30 enum TALER_EXCHANGE_GetReservesOption 31 { 32 /** 33 * End of list of options. 34 */ 35 TALER_EXCHANGE_GET_RESERVES_OPTION_END = 0, 36 37 /** 38 * How long to wait for a reply, enabling long polling if the reserve 39 * does not yet exist. Default is zero (no long polling). 40 */ 41 TALER_EXCHANGE_GET_RESERVES_OPTION_TIMEOUT 42 43 }; 44 45 46 /** 47 * Value for an option for the GET reserves request. 48 */ 49 struct TALER_EXCHANGE_GetReservesOptionValue 50 { 51 /** 52 * Type of the option being set. 53 */ 54 enum TALER_EXCHANGE_GetReservesOption option; 55 56 /** 57 * Specific option value. 58 */ 59 union 60 { 61 /** 62 * Value if @e option is TALER_EXCHANGE_GET_RESERVES_OPTION_TIMEOUT. 63 */ 64 struct GNUNET_TIME_Relative timeout; 65 66 } details; 67 68 }; 69 70 71 /** 72 * Handle for an operation to GET /reserves/$RESERVE_PUB. 73 */ 74 struct TALER_EXCHANGE_GetReservesHandle; 75 76 77 /** 78 * Set up GET /reserves/$RESERVE_PUB operation. 79 * Note that you must explicitly start the operation after 80 * possibly setting options. 81 * 82 * @param ctx the context 83 * @param url base URL of the exchange 84 * @param reserve_pub public key of the reserve to inspect 85 * @return handle to operation 86 */ 87 struct TALER_EXCHANGE_GetReservesHandle * 88 TALER_EXCHANGE_get_reserves_create ( 89 struct GNUNET_CURL_Context *ctx, 90 const char *url, 91 const struct TALER_ReservePublicKeyP *reserve_pub); 92 93 94 /** 95 * Terminate the list of options. 96 * 97 * @return the terminating object of struct TALER_EXCHANGE_GetReservesOptionValue 98 */ 99 #define TALER_EXCHANGE_get_reserves_option_end_() \ 100 (const struct TALER_EXCHANGE_GetReservesOptionValue) \ 101 { \ 102 .option = TALER_EXCHANGE_GET_RESERVES_OPTION_END \ 103 } 104 105 /** 106 * Set long-polling timeout. 107 * 108 * @param t how long to wait for an answer (enables long polling) 109 * @return representation of the option as a struct TALER_EXCHANGE_GetReservesOptionValue 110 */ 111 #define TALER_EXCHANGE_get_reserves_option_timeout(t) \ 112 (const struct TALER_EXCHANGE_GetReservesOptionValue) \ 113 { \ 114 .option = TALER_EXCHANGE_GET_RESERVES_OPTION_TIMEOUT, \ 115 .details.timeout = (t) \ 116 } 117 118 119 /** 120 * Set the requested options for the operation. 121 * 122 * If any option fails, other options may or may not be applied. 123 * 124 * @param grh the request to set the options for 125 * @param num_options length of the @a options array 126 * @param options an array of options 127 * @return #GNUNET_OK on success, 128 * #GNUNET_NO on failure, 129 * #GNUNET_SYSERR on internal error 130 */ 131 enum GNUNET_GenericReturnValue 132 TALER_EXCHANGE_get_reserves_set_options_ ( 133 struct TALER_EXCHANGE_GetReservesHandle *grh, 134 unsigned int num_options, 135 const struct TALER_EXCHANGE_GetReservesOptionValue *options); 136 137 138 /** 139 * Set the requested options for the operation. 140 * 141 * If any option fails, other options may or may not be applied. 142 * 143 * It should be used with helpers that create required options, for example: 144 * 145 * TALER_EXCHANGE_get_reserves_set_options ( 146 * grh, 147 * TALER_EXCHANGE_get_reserves_option_timeout (timeout)); 148 * 149 * @param grh the request to set the options for 150 * @param ... the list of options, each created by a 151 * TALER_EXCHANGE_get_reserves_option_NAME(VALUE) helper 152 * @return #GNUNET_OK on success, 153 * #GNUNET_NO on failure, 154 * #GNUNET_SYSERR on internal error 155 */ 156 #define TALER_EXCHANGE_get_reserves_set_options(grh,...) \ 157 TALER_EXCHANGE_get_reserves_set_options_ ( \ 158 grh, \ 159 TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 160 ((const struct TALER_EXCHANGE_GetReservesOptionValue[]) \ 161 {__VA_ARGS__, TALER_EXCHANGE_get_reserves_option_end_ () } \ 162 )) 163 164 165 /** 166 * @brief Reserve summary response. 167 */ 168 struct TALER_EXCHANGE_GetReservesResponse 169 { 170 /** 171 * HTTP response data. 172 */ 173 struct TALER_EXCHANGE_HttpResponse hr; 174 175 /** 176 * Details depending on @e hr.http_status. 177 */ 178 union 179 { 180 /** 181 * Information returned on #MHD_HTTP_OK. 182 */ 183 struct 184 { 185 /** 186 * Current reserve balance. 187 */ 188 struct TALER_Amount balance; 189 190 /** 191 * payto://-URI of the last bank account that wired funds to the reserve. 192 * NULL if the reserve was funded via P2P merge (no bank origin). 193 */ 194 struct TALER_FullPayto last_origin; 195 196 } ok; 197 198 } details; 199 200 }; 201 202 203 #ifndef TALER_EXCHANGE_GET_RESERVES_RESULT_CLOSURE 204 /** 205 * Type of the closure used by 206 * the #TALER_EXCHANGE_GetReservesCallback. 207 */ 208 #define TALER_EXCHANGE_GET_RESERVES_RESULT_CLOSURE void 209 #endif /* TALER_EXCHANGE_GET_RESERVES_RESULT_CLOSURE */ 210 211 /** 212 * Type of the function that receives the result of a 213 * GET /reserves/$RESERVE_PUB request. 214 * 215 * @param cls closure 216 * @param result result returned by the HTTP server 217 */ 218 typedef void 219 (*TALER_EXCHANGE_GetReservesCallback)( 220 TALER_EXCHANGE_GET_RESERVES_RESULT_CLOSURE *cls, 221 const struct TALER_EXCHANGE_GetReservesResponse *result); 222 223 224 /** 225 * Start GET /reserves/$RESERVE_PUB operation. 226 * 227 * @param[in,out] grh operation to start 228 * @param cb function to call with the exchange's result 229 * @param cb_cls closure for @a cb 230 * @return status code, #TALER_EC_NONE on success 231 */ 232 enum TALER_ErrorCode 233 TALER_EXCHANGE_get_reserves_start ( 234 struct TALER_EXCHANGE_GetReservesHandle *grh, 235 TALER_EXCHANGE_GetReservesCallback cb, 236 TALER_EXCHANGE_GET_RESERVES_RESULT_CLOSURE *cb_cls); 237 238 239 /** 240 * Cancel GET /reserves/$RESERVE_PUB operation. This function must not be 241 * called by clients after the TALER_EXCHANGE_GetReservesCallback has been 242 * invoked (as in those cases it'll be called internally by the 243 * implementation already). 244 * 245 * @param[in] grh operation to cancel 246 */ 247 void 248 TALER_EXCHANGE_get_reserves_cancel ( 249 struct TALER_EXCHANGE_GetReservesHandle *grh); 250 251 252 #endif /* _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_H */