get-reserves-RESERVE_PUB-history.h (8539B)
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/taler-exchange/get-reserves-RESERVE_PUB-history.h 18 * @brief C interface for GET /reserves/$RESERVE_PUB/history 19 * @author Christian Grothoff 20 */ 21 #ifndef _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_HISTORY_H 22 #define _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_HISTORY_H 23 24 #include <taler/taler-exchange/common.h> 25 #include <taler/taler-exchange/get-reserves-RESERVE_PUB.h> 26 27 /** 28 * Possible options we can set for the GET reserves history request. 29 */ 30 enum TALER_EXCHANGE_GetReservesHistoryOption 31 { 32 /** 33 * End of list of options. 34 */ 35 TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_END = 0, 36 37 /** 38 * Only return entries with offset strictly greater than this value. 39 * Defaults to 0 (return all entries). 40 * The offset corresponds to the etag / last entry offset from a 41 * previous response. 42 */ 43 TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_START_OFF 44 45 }; 46 47 48 /** 49 * Value for an option for the GET reserves history request. 50 */ 51 struct TALER_EXCHANGE_GetReservesHistoryOptionValue 52 { 53 /** 54 * Type of the option being set. 55 */ 56 enum TALER_EXCHANGE_GetReservesHistoryOption option; 57 58 /** 59 * Specific option value. 60 */ 61 union 62 { 63 /** 64 * Value if @e option is TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_START_OFF. 65 */ 66 uint64_t start_off; 67 68 } details; 69 70 }; 71 72 73 /** 74 * Handle for an operation to GET /reserves/$RESERVE_PUB/history. 75 */ 76 struct TALER_EXCHANGE_GetReservesHistoryHandle; 77 78 79 /** 80 * Set up GET /reserves/$RESERVE_PUB/history operation. 81 * Note that you must explicitly start the operation after 82 * possibly setting options. 83 * 84 * @param ctx the context 85 * @param url base URL of the exchange 86 * @param keys exchange keys for signature verification 87 * @param reserve_priv private key of the reserve to inspect 88 * @return handle to operation 89 */ 90 struct TALER_EXCHANGE_GetReservesHistoryHandle * 91 TALER_EXCHANGE_get_reserves_history_create ( 92 struct GNUNET_CURL_Context *ctx, 93 const char *url, 94 struct TALER_EXCHANGE_Keys *keys, 95 const struct TALER_ReservePrivateKeyP *reserve_priv); 96 97 98 /** 99 * Terminate the list of options. 100 * 101 * @return the terminating object of struct TALER_EXCHANGE_GetReservesHistoryOptionValue 102 */ 103 #define TALER_EXCHANGE_get_reserves_history_option_end_() \ 104 (const struct TALER_EXCHANGE_GetReservesHistoryOptionValue) \ 105 { \ 106 .option = TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_END \ 107 } 108 109 /** 110 * Set starting offset for partial history fetch. 111 * 112 * @param o offset: only return entries with offset > this value. 113 * Use the etag value from a previous response. 114 * @return representation of the option as a struct TALER_EXCHANGE_GetReservesHistoryOptionValue 115 */ 116 #define TALER_EXCHANGE_get_reserves_history_option_start_off(o) \ 117 (const struct TALER_EXCHANGE_GetReservesHistoryOptionValue) \ 118 { \ 119 .option = TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_START_OFF, \ 120 .details.start_off = (o) \ 121 } 122 123 124 /** 125 * Set the requested options for the operation. 126 * 127 * If any option fails, other options may or may not be applied. 128 * 129 * @param grhh the request to set the options for 130 * @param num_options length of the @a options array 131 * @param options an array of options 132 * @return #GNUNET_OK on success, 133 * #GNUNET_NO on failure, 134 * #GNUNET_SYSERR on internal error 135 */ 136 enum GNUNET_GenericReturnValue 137 TALER_EXCHANGE_get_reserves_history_set_options_ ( 138 struct TALER_EXCHANGE_GetReservesHistoryHandle *grhh, 139 unsigned int num_options, 140 const struct TALER_EXCHANGE_GetReservesHistoryOptionValue *options); 141 142 143 /** 144 * Set the requested options for the operation. 145 * 146 * If any option fails, other options may or may not be applied. 147 * 148 * It should be used with helpers that create required options, for example: 149 * 150 * TALER_EXCHANGE_get_reserves_history_set_options ( 151 * grhh, 152 * TALER_EXCHANGE_get_reserves_history_option_start_off (last_etag)); 153 * 154 * @param grhh the request to set the options for 155 * @param ... the list of options, each created by a 156 * TALER_EXCHANGE_get_reserves_history_option_NAME(VALUE) helper 157 * @return #GNUNET_OK on success, 158 * #GNUNET_NO on failure, 159 * #GNUNET_SYSERR on internal error 160 */ 161 #define TALER_EXCHANGE_get_reserves_history_set_options(grhh,...) \ 162 TALER_EXCHANGE_get_reserves_history_set_options_ ( \ 163 grhh, \ 164 TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 165 ((const struct TALER_EXCHANGE_GetReservesHistoryOptionValue[]) \ 166 {__VA_ARGS__, \ 167 TALER_EXCHANGE_get_reserves_history_option_end_ () } \ 168 )) 169 170 171 /** 172 * @brief Reserve history response. 173 */ 174 struct TALER_EXCHANGE_GetReservesHistoryResponse 175 { 176 /** 177 * HTTP response data. 178 */ 179 struct TALER_EXCHANGE_HttpResponse hr; 180 181 /** 182 * Details depending on @e hr.http_status. 183 */ 184 union 185 { 186 /** 187 * Information returned on #MHD_HTTP_OK. 188 */ 189 struct 190 { 191 /** 192 * Current reserve balance. May differ from total_in - total_out 193 * if the history is truncated. 194 */ 195 struct TALER_Amount balance; 196 197 /** 198 * Total of all inbound transactions in @e history. 199 */ 200 struct TALER_Amount total_in; 201 202 /** 203 * Total of all outbound transactions in @e history. 204 */ 205 struct TALER_Amount total_out; 206 207 /** 208 * Current etag / last entry offset in the history. 209 * Use this as the start_off option for incremental fetches. 210 * Offsets are not necessarily contiguous. 211 */ 212 uint64_t etag; 213 214 /** 215 * Reserve transaction history. 216 */ 217 const struct TALER_EXCHANGE_ReserveHistoryEntry *history; 218 219 /** 220 * Length of the @e history array. 221 */ 222 size_t history_len; 223 224 } ok; 225 226 } details; 227 228 }; 229 230 231 #ifndef TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE 232 /** 233 * Type of the closure used by 234 * the #TALER_EXCHANGE_GetReservesHistoryCallback. 235 */ 236 #define TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE void 237 #endif /* TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE */ 238 239 /** 240 * Type of the function that receives the result of a 241 * GET /reserves/$RESERVE_PUB/history request. 242 * 243 * @param cls closure 244 * @param result result returned by the HTTP server 245 */ 246 typedef void 247 (*TALER_EXCHANGE_GetReservesHistoryCallback)( 248 TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE *cls, 249 const struct TALER_EXCHANGE_GetReservesHistoryResponse *result); 250 251 252 /** 253 * Start GET /reserves/$RESERVE_PUB/history operation. 254 * 255 * @param[in,out] grhh operation to start 256 * @param cb function to call with the exchange's result 257 * @param cb_cls closure for @a cb 258 * @return status code, #TALER_EC_NONE on success 259 */ 260 enum TALER_ErrorCode 261 TALER_EXCHANGE_get_reserves_history_start ( 262 struct TALER_EXCHANGE_GetReservesHistoryHandle *grhh, 263 TALER_EXCHANGE_GetReservesHistoryCallback cb, 264 TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE *cb_cls); 265 266 267 /** 268 * Cancel GET /reserves/$RESERVE_PUB/history operation. This function must 269 * not be called by clients after the TALER_EXCHANGE_GetReservesHistoryCallback 270 * has been invoked (as in those cases it'll be called internally by the 271 * implementation already). 272 * 273 * @param[in] grhh operation to cancel 274 */ 275 void 276 TALER_EXCHANGE_get_reserves_history_cancel ( 277 struct TALER_EXCHANGE_GetReservesHistoryHandle *grhh); 278 279 280 #endif /* _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_HISTORY_H */