aml_legitimizations_get.h (11480B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2025 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/aml_legitimizations_get.h 18 * @brief C interface for the GET /aml/$OFFICER_PUB/legitimizations endpoint 19 * @author Christian Grothoff 20 */ 21 #ifndef _TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_H 22 #define _TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_H 23 24 #include <taler/taler-exchange/common.h> 25 26 /** 27 * Possible options we can set for the GET legitimizations request. 28 */ 29 enum TALER_EXCHANGE_AmlLegitimizationsGetOption 30 { 31 /** 32 * End of list of options. 33 */ 34 TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_END = 0, 35 36 /** 37 * Return at most N values, default is -20 to return 38 * the last 20 entries before start. Negative values 39 * to return before limit, positive to return after limit. 40 */ 41 TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_LIMIT, 42 43 /** 44 * Row number threshold, defaults to INT64_MAX, namely 45 * the biggest row id possible in the database. 46 */ 47 TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_OFFSET, 48 49 /** 50 * Filter by account using a normalized payto URI hash. 51 */ 52 TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_H_PAYTO, 53 54 /** 55 * If set to #TALER_EXCHANGE_YNA_YES, only return active 56 * results, #TALER_EXCHANGE_YNA_NO, only return inactive 57 * results, #TALER_EXCHANGE_YNA_ALL, to return all 58 * decisions. Default is all. 59 */ 60 TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_ACTIVE 61 62 }; 63 64 65 /** 66 * Possible options we can set for the GET legitimizations request. 67 */ 68 struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue 69 { 70 71 /** 72 * Type of the option being set. 73 */ 74 enum TALER_EXCHANGE_AmlLegitimizationsGetOption option; 75 76 /** 77 * Specific option value. 78 */ 79 union 80 { 81 82 /** 83 * Value of if @e option is TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_LIMIT. 84 */ 85 int64_t limit; 86 87 /** 88 * Value of if @e option is TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_OFFSET. 89 * Note that in practice the maximum value is INT64_MAX, even though 90 * this value is unsigned. 91 */ 92 uint64_t offset; 93 94 /** 95 * Value of if @e option is TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_H_PAYTO. 96 */ 97 const struct TALER_NormalizedPaytoHashP *h_payto; 98 99 /** 100 * Value of if @e option is TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_ACTIVE. 101 */ 102 enum TALER_EXCHANGE_YesNoAll active; 103 104 } details; 105 106 }; 107 108 109 /** 110 * Handle for an operation to GET /aml/$OFFICER_PUB/legitimizations. 111 */ 112 struct TALER_EXCHANGE_AmlLegitimizationsGetHandle; 113 114 115 /** 116 * Set up GET /aml/$OPUB/legitimizations operation. 117 * Note that you must explicitly start the operation after 118 * possibly setting options. 119 * 120 * @param ctx the context 121 * @param url base URL of the exchange 122 * @param officer_priv private key of the officer 123 * @return handle to operation 124 */ 125 struct TALER_EXCHANGE_AmlLegitimizationsGetHandle * 126 TALER_EXCHANGE_aml_legitimizations_get_create ( 127 struct GNUNET_CURL_Context *ctx, 128 const char *url, 129 const struct TALER_AmlOfficerPrivateKeyP *officer_priv); 130 131 132 /** 133 * Terminate the list of the options. 134 * 135 * @return the terminating object of struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue 136 */ 137 #define TALER_EXCHANGE_aml_legitimizations_get_option_end_() \ 138 (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \ 139 { \ 140 .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_END \ 141 } 142 143 /** 144 * Set limit @a l on the number of results to return. 145 * 146 * @param l limit on the number of results to return 147 * @return representation of the option as a struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue 148 */ 149 #define TALER_EXCHANGE_aml_legitimizations_get_option_limit(l) \ 150 (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \ 151 { \ 152 .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_LIMIT, \ 153 .details.limit = (l) \ 154 } 155 156 157 /** 158 * Set row offset from which to return results. 159 * 160 * @param o offset to use 161 * @return representation of the option as a struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue 162 */ 163 #define TALER_EXCHANGE_aml_legitimizations_get_option_offset(o) \ 164 (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \ 165 { \ 166 .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_OFFSET, \ 167 .details.offset = (o) \ 168 } 169 170 171 /** 172 * Set filter on which account to filter legitimization measures by. 173 * 174 * @param p normalized payto URI hash of the account to filter by 175 * @return representation of the option as a struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue 176 */ 177 #define TALER_EXCHANGE_aml_legitimizations_get_option_h_payto(p) \ 178 (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \ 179 { \ 180 .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_H_PAYTO, \ 181 .details.h_payto = (p) \ 182 } 183 184 /** 185 * Set filter on active (or inactive) results. 186 * 187 * @param a activity filter to use 188 * @return representation of the option as a struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue 189 */ 190 #define TALER_EXCHANGE_aml_legitimizations_get_option_active(a) \ 191 (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \ 192 { \ 193 .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_ACTIVE, \ 194 .details.active = (a) \ 195 } 196 197 198 /** 199 * Set the requested options for the operation. 200 * 201 * If any option fail other options may be or may be not applied. 202 * 203 * @param algh the request to set the options for 204 * @param num_options length of the @a options array 205 * @param options array of options, each option must be created 206 * by helpers TALER_EXCHANGE_aml_legitimizations_get_option_NAME(VALUE) 207 * @return #GNUNET_OK on success, 208 * #GNUNET_NO on failure, 209 * #GNUNET_SYSERR on internal error 210 */ 211 enum GNUNET_GenericReturnValue 212 TALER_EXCHANGE_aml_legitimizations_get_set_options_ ( 213 struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh, 214 unsigned int num_options, 215 const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue *options); 216 217 218 /** 219 * Set the requested options for the operation. 220 * 221 * If any option fail other options may be or may be not applied. 222 * 223 * It should be used with helpers that creates required options, for example: 224 * 225 * TALER_EXCHANGE_aml_legitimizations_get_set_options ( 226 * algh, 227 * TALER_EXCHANGE_aml_legitimizations_get_option_h_payto_(&h_payto)); 228 * 229 * @param algh the request to set the options for 230 * @param ... the list of the options, each option must be created 231 * by helpers TALER_EXCHANGE_aml_legitimizations_get_option_NAME(VALUE) 232 * @return #GNUNET_OK on success, 233 * #GNUNET_NO on failure, 234 * #GNUNET_SYSERR on internal error 235 */ 236 #define TALER_EXCHANGE_aml_legitimizations_get_set_options(algh,...) \ 237 TALER_EXCHANGE_aml_legitimizations_get_set_options_ ( \ 238 algh, \ 239 TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 240 ((const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue[]) \ 241 {__VA_ARGS__, TALER_EXCHANGE_aml_legitimizations_get_option_end_ () } \ 242 )) 243 244 245 /** 246 * Entry in the set of legitimization measures that are returned 247 * by the server in a single request. 248 */ 249 struct TALER_EXCHANGE_AmlLegitimizationsGetMeasureDetails 250 { 251 /** 252 * Hash of the normalized payto:// URI of the account the 253 * measure applies to. 254 */ 255 struct TALER_NormalizedPaytoHashP h_payto; 256 257 /** 258 * Row ID of the measure in the exchange database. 259 */ 260 uint64_t rowid; 261 262 /** 263 * When was the measure started / triggered? 264 */ 265 struct GNUNET_TIME_Timestamp start_time; 266 267 /** 268 * Object with the legitimization measures that are to be applied. 269 */ 270 const json_t *measures; 271 272 /** 273 * Was this measure finished by the customer? (or obsoleted 274 * by a subsequent other measure taken)? 275 */ 276 bool is_finished; 277 }; 278 279 /** 280 * Information returned from the exchange for a 281 * GET /aml/$OFFICER_PUB/legitimizations request. 282 */ 283 struct TALER_EXCHANGE_AmlLegitimizationsGetResult 284 { 285 /** 286 * HTTP response data 287 */ 288 struct TALER_EXCHANGE_HttpResponse hr; 289 290 /** 291 * Details depending on the HTTP status code. 292 */ 293 union 294 { 295 296 /** 297 * Details on #MHD_HTTP_OK. 298 */ 299 struct 300 { 301 /** 302 * Length of the @e measures array. 303 */ 304 size_t measures_length; 305 306 /** 307 * Legitimization measures. 308 */ 309 const struct TALER_EXCHANGE_AmlLegitimizationsGetMeasureDetails *measures; 310 311 } ok; 312 313 } details; 314 }; 315 316 317 #ifndef TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE 318 /** 319 * Type of the closure used by 320 * the #TALER_EXCHANGE_AmlLegitimizationsGetCallback. 321 */ 322 #define TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE void 323 #endif 324 325 /** 326 * Type of the function that receives the result of a 327 * GET /aml/$OFFICER_PUB/legitimizations request. 328 * 329 * @param cls closure 330 * @param result result returned by the HTTP server 331 */ 332 typedef void 333 (*TALER_EXCHANGE_AmlLegitimizationsGetCallback)( 334 TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE *cls, 335 const struct TALER_EXCHANGE_AmlLegitimizationsGetResult *result); 336 337 338 /** 339 * Start GET /aml/$OPUB/legitimizations operation. 340 * 341 * @param[in,out] algh operation to start 342 * @param cb function to call with the exchange's result 343 * @param cb_cls closure for @a cb 344 * @return status code 345 */ 346 enum TALER_EXCHANGE_AmlLegitimizationsGetStartError 347 { 348 /** 349 * Success. 350 */ 351 TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_OK = 0, 352 /** 353 * Only allowed to be started once. 354 */ 355 TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_E_AGAIN = 1, 356 /** 357 * Internal logic failure. 358 */ 359 TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_E_INTERNAL = 2, 360 } 361 TALER_EXCHANGE_aml_legitimizations_get_start ( 362 struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh, 363 TALER_EXCHANGE_AmlLegitimizationsGetCallback cb, 364 TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE * cb_cls); 365 366 367 /** 368 * Cancel GET /aml/$OPUB/legitimizations operation. 369 * 370 * @param[in] algh operation to cancel 371 */ 372 void 373 TALER_EXCHANGE_aml_legitimizations_get_cancel ( 374 struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh); 375 376 377 #endif