get-private-statistics-counter-SLUG.h (9461B)
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-counter-SLUG.h 19 * @brief C interface for the GET /private/statistics-counter/$SLUG endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__GET_PRIVATE_STATISTICS_COUNTER_SLUG_H 23 #define _TALER_MERCHANT__GET_PRIVATE_STATISTICS_COUNTER_SLUG_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the GET /private/statistics-counter/$SLUG request. 30 */ 31 enum TALER_MERCHANT_GetPrivateStatisticsCounterOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_GET_PRIVATE_STATISTICS_COUNTER_OPTION_END = 0, 37 38 /** 39 * Aggregation mode to request (BUCKET, INTERVAL, or ANY). 40 */ 41 TALER_MERCHANT_GET_PRIVATE_STATISTICS_COUNTER_OPTION_TYPE 42 43 }; 44 45 46 /** 47 * Value for an option for the GET /private/statistics-counter/$SLUG request. 48 */ 49 struct TALER_MERCHANT_GetPrivateStatisticsCounterOptionValue 50 { 51 52 /** 53 * Type of the option being set. 54 */ 55 enum TALER_MERCHANT_GetPrivateStatisticsCounterOption 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_COUNTER_OPTION_TYPE. 66 */ 67 enum TALER_MERCHANT_StatisticsType type; 68 69 } details; 70 71 }; 72 73 74 /** 75 * Handle for a GET /private/statistics-counter/$SLUG request. 76 */ 77 struct TALER_MERCHANT_GetPrivateStatisticsCounterHandle; 78 79 80 /** 81 * Set up GET /private/statistics-counter/$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_GetPrivateStatisticsCounterHandle * 91 TALER_MERCHANT_get_private_statistics_counter_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_GetPrivateStatisticsCounterOptionValue 101 */ 102 #define TALER_MERCHANT_get_private_statistics_counter_option_end_() \ 103 (const struct TALER_MERCHANT_GetPrivateStatisticsCounterOptionValue) \ 104 { \ 105 .option = TALER_MERCHANT_GET_PRIVATE_STATISTICS_COUNTER_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_GetPrivateStatisticsCounterOptionValue 113 */ 114 #define TALER_MERCHANT_get_private_statistics_counter_option_type(t) \ 115 (const struct TALER_MERCHANT_GetPrivateStatisticsCounterOptionValue) \ 116 { \ 117 .option = TALER_MERCHANT_GET_PRIVATE_STATISTICS_COUNTER_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 sch 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_counter_set_options_ ( 136 struct TALER_MERCHANT_GetPrivateStatisticsCounterHandle *sch, 137 unsigned int num_options, 138 const struct TALER_MERCHANT_GetPrivateStatisticsCounterOptionValue *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_counter_set_options ( 149 * sch, 150 * TALER_MERCHANT_get_private_statistics_counter_option_type ( 151 * TALER_MERCHANT_STATISTICS_TYPE_INTERVAL)); 152 * 153 * @param sch 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_counter_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_counter_set_options(sch,...) \ 161 TALER_MERCHANT_get_private_statistics_counter_set_options_ ( \ 162 sch, \ 163 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 164 ((const struct TALER_MERCHANT_GetPrivateStatisticsCounterOptionValue[] \ 165 ) \ 166 {__VA_ARGS__, \ 167 TALER_MERCHANT_get_private_statistics_counter_option_end_ () } \ 168 )) 169 170 171 /** 172 * Statistic counter aggregated by bucket. 173 */ 174 struct TALER_MERCHANT_GetPrivateStatisticsCounterByBucket 175 { 176 177 /** 178 * Start time of the bucket (inclusive). 179 */ 180 struct GNUNET_TIME_Timestamp start_time; 181 182 /** 183 * End time of the bucket (exclusive). 184 */ 185 struct GNUNET_TIME_Timestamp end_time; 186 187 /** 188 * Range of the bucket. 189 */ 190 const char *range; 191 192 /** 193 * Sum of all counters falling under the given 194 * SLUG within this timeframe. 195 */ 196 uint64_t cumulative_counter; 197 198 }; 199 200 201 /** 202 * Statistic counter aggregated by interval. 203 */ 204 struct TALER_MERCHANT_GetPrivateStatisticsCounterByInterval 205 { 206 207 /** 208 * Start time of the interval (inclusive). 209 * The interval always ends at the response 210 * generation time. 211 */ 212 struct GNUNET_TIME_Timestamp start_time; 213 214 /** 215 * Sum of all counters falling under the given 216 * SLUG within this timeframe. 217 */ 218 uint64_t cumulative_counter; 219 220 }; 221 222 223 /** 224 * Response details for a GET /private/statistics-counter/$SLUG request. 225 */ 226 struct TALER_MERCHANT_GetPrivateStatisticsCounterResponse 227 { 228 229 /** 230 * HTTP response details. 231 */ 232 struct TALER_MERCHANT_HttpResponse hr; 233 234 /** 235 * Details depending on the HTTP status code. 236 */ 237 union 238 { 239 240 /** 241 * Details on #MHD_HTTP_OK. 242 */ 243 struct 244 { 245 246 /** 247 * Number of bucket entries in @a buckets. 248 */ 249 unsigned int buckets_length; 250 251 /** 252 * Array of counter statistics per bucket. 253 */ 254 const struct TALER_MERCHANT_GetPrivateStatisticsCounterByBucket *buckets; 255 256 /** 257 * Description of the bucket aggregation scheme, or NULL. 258 */ 259 const char *buckets_description; 260 261 /** 262 * Number of interval entries in @a intervals. 263 */ 264 unsigned int intervals_length; 265 266 /** 267 * Array of counter statistics per time interval. 268 */ 269 const struct TALER_MERCHANT_GetPrivateStatisticsCounterByInterval * 270 intervals; 271 272 /** 273 * Description of the interval aggregation scheme, or NULL. 274 */ 275 const char *intervals_description; 276 277 } ok; 278 279 } details; 280 281 }; 282 283 284 #ifndef TALER_MERCHANT_GET_PRIVATE_STATISTICS_COUNTER_RESULT_CLOSURE 285 /** 286 * Type of the closure used by 287 * the #TALER_MERCHANT_GetPrivateStatisticsCounterCallback. 288 */ 289 #define TALER_MERCHANT_GET_PRIVATE_STATISTICS_COUNTER_RESULT_CLOSURE void 290 #endif /* TALER_MERCHANT_GET_PRIVATE_STATISTICS_COUNTER_RESULT_CLOSURE */ 291 292 /** 293 * Callback for a GET /private/statistics-counter/$SLUG request. 294 * 295 * @param cls closure 296 * @param scgr response details 297 */ 298 typedef void 299 (*TALER_MERCHANT_GetPrivateStatisticsCounterCallback)( 300 TALER_MERCHANT_GET_PRIVATE_STATISTICS_COUNTER_RESULT_CLOSURE *cls, 301 const struct TALER_MERCHANT_GetPrivateStatisticsCounterResponse *scgr); 302 303 304 /** 305 * Start GET /private/statistics-counter/$SLUG operation. 306 * 307 * @param[in,out] sch operation to start 308 * @param cb function to call with the merchant's result 309 * @param cb_cls closure for @a cb 310 * @return status code, #TALER_EC_NONE on success 311 */ 312 enum TALER_ErrorCode 313 TALER_MERCHANT_get_private_statistics_counter_start ( 314 struct TALER_MERCHANT_GetPrivateStatisticsCounterHandle *sch, 315 TALER_MERCHANT_GetPrivateStatisticsCounterCallback cb, 316 TALER_MERCHANT_GET_PRIVATE_STATISTICS_COUNTER_RESULT_CLOSURE *cb_cls); 317 318 319 /** 320 * Cancel GET /private/statistics-counter/$SLUG operation. This function 321 * must not be called by clients after the 322 * TALER_MERCHANT_GetPrivateStatisticsCounterCallback has been invoked 323 * (as in those cases it'll be called internally by the implementation 324 * already). 325 * 326 * @param[in] sch operation to cancel 327 */ 328 void 329 TALER_MERCHANT_get_private_statistics_counter_cancel ( 330 struct TALER_MERCHANT_GetPrivateStatisticsCounterHandle *sch); 331 332 333 #endif /* _TALER_MERCHANT__GET_PRIVATE_STATISTICS_COUNTER_SLUG_H */