get-private-statistics-amount-SLUG.h (9600B)
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 src/include/taler/merchant/get-private-statistics-amount-SLUG.h 19 * @brief C interface for the GET /private/statistics-amount/$SLUG endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__GET_PRIVATE_STATISTICS_AMOUNT_SLUG_H 23 #define _TALER_MERCHANT__GET_PRIVATE_STATISTICS_AMOUNT_SLUG_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the GET /private/statistics-amount/$SLUG request. 30 */ 31 enum TALER_MERCHANT_GetPrivateStatisticsAmountOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_GET_PRIVATE_STATISTICS_AMOUNT_OPTION_END = 0, 37 38 /** 39 * Aggregation mode to request (BUCKET, INTERVAL, or ANY). 40 */ 41 TALER_MERCHANT_GET_PRIVATE_STATISTICS_AMOUNT_OPTION_TYPE 42 43 }; 44 45 46 /** 47 * Value for an option for the GET /private/statistics-amount/$SLUG request. 48 */ 49 struct TALER_MERCHANT_GetPrivateStatisticsAmountOptionValue 50 { 51 52 /** 53 * Type of the option being set. 54 */ 55 enum TALER_MERCHANT_GetPrivateStatisticsAmountOption option; 56 57 /** 58 * Specific option value. 59 */ 60 union 61 { 62 63 /** 64 * Value if @e option is 65 * #TALER_MERCHANT_GET_PRIVATE_STATISTICS_AMOUNT_OPTION_TYPE. 66 */ 67 enum TALER_MERCHANT_StatisticsType type; 68 69 } details; 70 71 }; 72 73 74 /** 75 * Handle for a GET /private/statistics-amount/$SLUG request. 76 */ 77 struct TALER_MERCHANT_GetPrivateStatisticsAmountHandle; 78 79 80 /** 81 * Set up GET /private/statistics-amount/$SLUG operation. 82 * Note that you must explicitly start the operation after 83 * possibly setting options. 84 * 85 * @param ctx the context 86 * @param url base URL of the merchant backend 87 * @param slug statistics slug to retrieve 88 * @return handle to operation 89 */ 90 struct TALER_MERCHANT_GetPrivateStatisticsAmountHandle * 91 TALER_MERCHANT_get_private_statistics_amount_create ( 92 struct GNUNET_CURL_Context *ctx, 93 const char *url, 94 const char *slug); 95 96 97 /** 98 * Terminate the list of the options. 99 * 100 * @return the terminating object of struct TALER_MERCHANT_GetPrivateStatisticsAmountOptionValue 101 */ 102 #define TALER_MERCHANT_get_private_statistics_amount_option_end_() \ 103 (const struct TALER_MERCHANT_GetPrivateStatisticsAmountOptionValue) \ 104 { \ 105 .option = TALER_MERCHANT_GET_PRIVATE_STATISTICS_AMOUNT_OPTION_END \ 106 } 107 108 /** 109 * Set aggregation mode type. 110 * 111 * @param t aggregation mode to request 112 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateStatisticsAmountOptionValue 113 */ 114 #define TALER_MERCHANT_get_private_statistics_amount_option_type(t) \ 115 (const struct TALER_MERCHANT_GetPrivateStatisticsAmountOptionValue) \ 116 { \ 117 .option = TALER_MERCHANT_GET_PRIVATE_STATISTICS_AMOUNT_OPTION_TYPE, \ 118 .details.type = (t) \ 119 } 120 121 122 /** 123 * Set the requested options for the operation. 124 * 125 * If any option fail other options may be or may be not applied. 126 * 127 * @param sah the request to set the options for 128 * @param num_options length of the @a options array 129 * @param options an array of options 130 * @return #GNUNET_OK on success, 131 * #GNUNET_NO on failure, 132 * #GNUNET_SYSERR on internal error 133 */ 134 enum GNUNET_GenericReturnValue 135 TALER_MERCHANT_get_private_statistics_amount_set_options_ ( 136 struct TALER_MERCHANT_GetPrivateStatisticsAmountHandle *sah, 137 unsigned int num_options, 138 const struct TALER_MERCHANT_GetPrivateStatisticsAmountOptionValue *options); 139 140 141 /** 142 * Set the requested options for the operation. 143 * 144 * If any option fail other options may be or may be not applied. 145 * 146 * It should be used with helpers that create required options, for example: 147 * 148 * TALER_MERCHANT_get_private_statistics_amount_set_options ( 149 * sah, 150 * TALER_MERCHANT_get_private_statistics_amount_option_type ( 151 * TALER_MERCHANT_STATISTICS_TYPE_BUCKET)); 152 * 153 * @param sah the request to set the options for 154 * @param ... the list of the options, each option must be created 155 * by helpers TALER_MERCHANT_get_private_statistics_amount_option_NAME(VALUE) 156 * @return #GNUNET_OK on success, 157 * #GNUNET_NO on failure, 158 * #GNUNET_SYSERR on internal error 159 */ 160 #define TALER_MERCHANT_get_private_statistics_amount_set_options(sah,...) \ 161 TALER_MERCHANT_get_private_statistics_amount_set_options_ ( \ 162 sah, \ 163 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 164 ((const struct TALER_MERCHANT_GetPrivateStatisticsAmountOptionValue[]) \ 165 {__VA_ARGS__, \ 166 TALER_MERCHANT_get_private_statistics_amount_option_end_ () } \ 167 )) 168 169 170 /** 171 * Statistic amount aggregated by bucket. 172 */ 173 struct TALER_MERCHANT_GetPrivateStatisticsAmountByBucket 174 { 175 176 /** 177 * Start time of the bucket (inclusive). 178 */ 179 struct GNUNET_TIME_Timestamp start_time; 180 181 /** 182 * End time of the bucket (exclusive). 183 */ 184 struct GNUNET_TIME_Timestamp end_time; 185 186 /** 187 * Range of the bucket. 188 */ 189 const char *range; 190 191 /** 192 * Sum of all amounts falling under the given 193 * SLUG within this timeframe. 194 */ 195 const struct TALER_Amount *cumulative_amounts; 196 197 /** 198 * Length of array @a cumulative_amounts. 199 */ 200 unsigned int cumulative_amount_len; 201 202 }; 203 204 205 /** 206 * Statistic amount aggregated by interval. 207 */ 208 struct TALER_MERCHANT_GetPrivateStatisticsAmountByInterval 209 { 210 211 /** 212 * Start time of the interval (inclusive). 213 * The interval always ends at the response 214 * generation time. 215 */ 216 struct GNUNET_TIME_Timestamp start_time; 217 218 /** 219 * Sum of all amounts falling under the given 220 * SLUG within this timeframe. 221 */ 222 const struct TALER_Amount *cumulative_amounts; 223 224 /** 225 * Length of array @a cumulative_amounts. 226 */ 227 unsigned int cumulative_amount_len; 228 229 }; 230 231 232 /** 233 * Response details for a GET /private/statistics-amount/$SLUG request. 234 */ 235 struct TALER_MERCHANT_GetPrivateStatisticsAmountResponse 236 { 237 238 /** 239 * HTTP response details. 240 */ 241 struct TALER_MERCHANT_HttpResponse hr; 242 243 /** 244 * Details depending on the HTTP status code. 245 */ 246 union 247 { 248 249 /** 250 * Details on #MHD_HTTP_OK. 251 */ 252 struct 253 { 254 255 /** 256 * Number of bucket entries in @a buckets. 257 */ 258 unsigned int buckets_length; 259 260 /** 261 * Array of amount statistics per bucket. 262 */ 263 const struct TALER_MERCHANT_GetPrivateStatisticsAmountByBucket *buckets; 264 265 /** 266 * Description of the bucket aggregation scheme, or NULL. 267 */ 268 const char *buckets_description; 269 270 /** 271 * Number of interval entries in @a intervals. 272 */ 273 unsigned int intervals_length; 274 275 /** 276 * Array of amount statistics per time interval. 277 */ 278 const struct TALER_MERCHANT_GetPrivateStatisticsAmountByInterval * 279 intervals; 280 281 /** 282 * Description of the interval aggregation scheme, or NULL. 283 */ 284 const char *intervals_description; 285 286 } ok; 287 288 } details; 289 290 }; 291 292 293 #ifndef TALER_MERCHANT_GET_PRIVATE_STATISTICS_AMOUNT_RESULT_CLOSURE 294 /** 295 * Type of the closure used by 296 * the #TALER_MERCHANT_GetPrivateStatisticsAmountCallback. 297 */ 298 #define TALER_MERCHANT_GET_PRIVATE_STATISTICS_AMOUNT_RESULT_CLOSURE void 299 #endif /* TALER_MERCHANT_GET_PRIVATE_STATISTICS_AMOUNT_RESULT_CLOSURE */ 300 301 /** 302 * Callback for a GET /private/statistics-amount/$SLUG request. 303 * 304 * @param cls closure 305 * @param sagr response details 306 */ 307 typedef void 308 (*TALER_MERCHANT_GetPrivateStatisticsAmountCallback)( 309 TALER_MERCHANT_GET_PRIVATE_STATISTICS_AMOUNT_RESULT_CLOSURE *cls, 310 const struct TALER_MERCHANT_GetPrivateStatisticsAmountResponse *sagr); 311 312 313 /** 314 * Start GET /private/statistics-amount/$SLUG operation. 315 * 316 * @param[in,out] sah operation to start 317 * @param cb function to call with the merchant's result 318 * @param cb_cls closure for @a cb 319 * @return status code, #TALER_EC_NONE on success 320 */ 321 enum TALER_ErrorCode 322 TALER_MERCHANT_get_private_statistics_amount_start ( 323 struct TALER_MERCHANT_GetPrivateStatisticsAmountHandle *sah, 324 TALER_MERCHANT_GetPrivateStatisticsAmountCallback cb, 325 TALER_MERCHANT_GET_PRIVATE_STATISTICS_AMOUNT_RESULT_CLOSURE *cb_cls); 326 327 328 /** 329 * Cancel GET /private/statistics-amount/$SLUG operation. This function 330 * must not be called by clients after the 331 * TALER_MERCHANT_GetPrivateStatisticsAmountCallback has been invoked 332 * (as in those cases it'll be called internally by the implementation 333 * already). 334 * 335 * @param[in] sah operation to cancel 336 */ 337 void 338 TALER_MERCHANT_get_private_statistics_amount_cancel ( 339 struct TALER_MERCHANT_GetPrivateStatisticsAmountHandle *sah); 340 341 342 #endif /* _TALER_MERCHANT__GET_PRIVATE_STATISTICS_AMOUNT_SLUG_H */