get-aml-OFFICER_PUB-attributes-H_NORMALIZED_PAYTO.h (9577B)
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-aml-OFFICER_PUB-attributes-H_NORMALIZED_PAYTO.h 18 * @brief C interface for the GET /aml/$OFFICER_PUB/attributes/$H_NORMALIZED_PAYTO endpoint 19 * @author Christian Grothoff 20 */ 21 #ifndef _TALER_EXCHANGE__GET_AML_OFFICER_PUB_ATTRIBUTES_H_NORMALIZED_PAYTO_H 22 #define _TALER_EXCHANGE__GET_AML_OFFICER_PUB_ATTRIBUTES_H_NORMALIZED_PAYTO_H 23 24 #include <taler/taler-exchange/common.h> 25 26 /** 27 * Possible options we can set for the GET attributes request. 28 */ 29 enum TALER_EXCHANGE_GetAmlAttributesOption 30 { 31 /** 32 * End of list of options. 33 */ 34 TALER_EXCHANGE_GET_AML_ATTRIBUTES_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_GET_AML_ATTRIBUTES_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_GET_AML_ATTRIBUTES_OPTION_OFFSET 48 49 }; 50 51 52 /** 53 * Possible options we can set for the GET attributes request. 54 */ 55 struct TALER_EXCHANGE_GetAmlAttributesOptionValue 56 { 57 58 /** 59 * Type of the option being set. 60 */ 61 enum TALER_EXCHANGE_GetAmlAttributesOption option; 62 63 /** 64 * Specific option value. 65 */ 66 union 67 { 68 69 /** 70 * Value of if @e option is TALER_EXCHANGE_GET_AML_ATTRIBUTES_OPTION_LIMIT. 71 */ 72 int64_t limit; 73 74 /** 75 * Value of if @e option is TALER_EXCHANGE_GET_AML_ATTRIBUTES_OPTION_OFFSET. 76 * Note that in practice the maximum value is INT64_MAX, even though 77 * this value is unsigned. 78 */ 79 uint64_t offset; 80 81 } details; 82 83 }; 84 85 86 /** 87 * Handle for an operation to GET /aml/$OFFICER_PUB/attributes/$H_NORMALIZED_PAYTO. 88 */ 89 struct TALER_EXCHANGE_GetAmlAttributesHandle; 90 91 92 /** 93 * Set up GET /aml/$OPUB/attributes/$H_NORMALIZED_PAYTO operation. 94 * Note that you must explicitly start the operation after 95 * possibly setting options. 96 * 97 * @param ctx the context 98 * @param url base URL of the exchange 99 * @param officer_priv private key of the officer 100 * @param h_payto normalized payto URI hash of the account to get attributes for 101 * @return handle to operation 102 */ 103 struct TALER_EXCHANGE_GetAmlAttributesHandle * 104 TALER_EXCHANGE_get_aml_attributes_create ( 105 struct GNUNET_CURL_Context *ctx, 106 const char *url, 107 const struct TALER_AmlOfficerPrivateKeyP *officer_priv, 108 const struct TALER_NormalizedPaytoHashP *h_payto); 109 110 111 /** 112 * Terminate the list of the options. 113 * 114 * @return the terminating object of struct TALER_EXCHANGE_GetAmlAttributesOptionValue 115 */ 116 #define TALER_EXCHANGE_get_aml_attributes_option_end_() \ 117 (const struct TALER_EXCHANGE_GetAmlAttributesOptionValue) \ 118 { \ 119 .option = TALER_EXCHANGE_GET_AML_ATTRIBUTES_OPTION_END \ 120 } 121 122 /** 123 * Set limit @a l on the number of results to return. 124 * 125 * @param l limit on the number of results to return 126 * @return representation of the option as a struct TALER_EXCHANGE_GetAmlAttributesOptionValue 127 */ 128 #define TALER_EXCHANGE_get_aml_attributes_option_limit(l) \ 129 (const struct TALER_EXCHANGE_GetAmlAttributesOptionValue) \ 130 { \ 131 .option = TALER_EXCHANGE_GET_AML_ATTRIBUTES_OPTION_LIMIT, \ 132 .details.limit = (l) \ 133 } 134 135 136 /** 137 * Set row offset from which to return results. 138 * 139 * @param o offset to use 140 * @return representation of the option as a struct TALER_EXCHANGE_GetAmlAttributesOptionValue 141 */ 142 #define TALER_EXCHANGE_get_aml_attributes_option_offset(o) \ 143 (const struct TALER_EXCHANGE_GetAmlAttributesOptionValue) \ 144 { \ 145 .option = TALER_EXCHANGE_GET_AML_ATTRIBUTES_OPTION_OFFSET, \ 146 .details.offset = (o) \ 147 } 148 149 150 /** 151 * Set the requested options for the operation. 152 * 153 * If any option fail other options may be or may be not applied. 154 * 155 * @param aagh the request to set the options for 156 * @param num_options length of the @a options array 157 * @param options an array of options 158 * @return ::TALER_EC_NONE on success, 159 * error code otherwise 160 * @return #GNUNET_OK on success, 161 * #GNUNET_NO on failure, 162 * #GNUNET_SYSERR on internal error 163 */ 164 enum GNUNET_GenericReturnValue 165 TALER_EXCHANGE_get_aml_attributes_set_options_ ( 166 struct TALER_EXCHANGE_GetAmlAttributesHandle *aagh, 167 unsigned int num_options, 168 const struct TALER_EXCHANGE_GetAmlAttributesOptionValue *options); 169 170 171 /** 172 * Set the requested options for the operation. 173 * 174 * If any option fail other options may be or may be not applied. 175 * 176 * It should be used with helpers that creates required options, for example: 177 * 178 * TALER_EXCHANGE_get_aml_attributes_set_options ( 179 * aagh, 180 * TALER_EXCHANGE_get_aml_attributes_option_limit_(10)); 181 * 182 * @param aagh the request to set the options for 183 * @param ... the list of the options, each option must be created 184 * by helpers TALER_EXCHANGE_get_aml_attributes_option_NAME(VALUE) 185 * @return ::TALER_EC_NONE on success, 186 * error code otherwise 187 */ 188 #define TALER_EXCHANGE_get_aml_attributes_set_options(aagh,...) \ 189 TALER_EXCHANGE_get_aml_attributes_set_options_ ( \ 190 aagh, \ 191 TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 192 ((const struct TALER_EXCHANGE_GetAmlAttributesOptionValue[]) \ 193 {__VA_ARGS__, TALER_EXCHANGE_get_aml_attributes_option_end_ () } \ 194 )) 195 196 197 /** 198 * Entry in the set of KYC attribute collection events that are returned 199 * by the server in a single request. 200 */ 201 struct TALER_EXCHANGE_GetAmlAttributesCollectionEvent 202 { 203 /** 204 * Row ID of the record. Used to filter by offset. 205 */ 206 uint64_t rowid; 207 208 /** 209 * True if the attributes were filed by an AML officer, 210 * false if provided directly by the customer. 211 */ 212 bool by_aml_officer; 213 214 /** 215 * The collected KYC data. NULL if the attribute data could not 216 * be decrypted (internal error of the exchange, likely the 217 * attribute key was changed). 218 */ 219 const json_t *attributes; 220 221 /** 222 * Time when the KYC data was collected. 223 */ 224 struct GNUNET_TIME_Timestamp collection_time; 225 }; 226 227 /** 228 * Information returned from the exchange for a 229 * GET /aml/$OFFICER_PUB/attributes/$H_NORMALIZED_PAYTO request. 230 */ 231 struct TALER_EXCHANGE_GetAmlAttributesResponse 232 { 233 /** 234 * HTTP response data 235 */ 236 struct TALER_EXCHANGE_HttpResponse hr; 237 238 /** 239 * Details depending on the HTTP status code. 240 */ 241 union 242 { 243 244 /** 245 * Details on #MHD_HTTP_OK. 246 */ 247 struct 248 { 249 /** 250 * Length of the @e details array. 251 */ 252 size_t details_length; 253 254 /** 255 * Matching KYC attribute history of the account. 256 */ 257 const struct TALER_EXCHANGE_GetAmlAttributesCollectionEvent *details; 258 259 } ok; 260 261 /** 262 * Details on #MHD_HTTP_NOT_IMPLEMENTED (501). 263 * Returned when the requested output format (e.g. application/pdf) 264 * is not supported by this exchange backend. 265 */ 266 struct 267 { 268 /* no additional details */ 269 } not_implemented; 270 271 } details; 272 }; 273 274 275 #ifndef TALER_EXCHANGE_GET_AML_ATTRIBUTES_RESULT_CLOSURE 276 /** 277 * Type of the closure used by 278 * the #TALER_EXCHANGE_GetAmlAttributesCallback. 279 */ 280 #define TALER_EXCHANGE_GET_AML_ATTRIBUTES_RESULT_CLOSURE void 281 #endif \ 282 /* _TALER_EXCHANGE_GET_AML_OFFICER_PUB_ATTRIBUTES_H_NORMALIZED_PAYTO_H */ 283 284 /** 285 * Type of the function that receives the result of a 286 * GET /aml/$OFFICER_PUB/attributes/$H_NORMALIZED_PAYTO request. 287 * 288 * @param cls closure 289 * @param result result returned by the HTTP server 290 */ 291 typedef void 292 (*TALER_EXCHANGE_GetAmlAttributesCallback)( 293 TALER_EXCHANGE_GET_AML_ATTRIBUTES_RESULT_CLOSURE *cls, 294 const struct TALER_EXCHANGE_GetAmlAttributesResponse *result); 295 296 297 /** 298 * Start GET /aml/$OPUB/attributes/$H_NORMALIZED_PAYTO operation. 299 * 300 * @param[in,out] aagh operation to start 301 * @param cb function to call with the exchange's result 302 * @param cb_cls closure for @a cb 303 * @return status code 304 */ 305 enum TALER_ErrorCode 306 TALER_EXCHANGE_get_aml_attributes_start ( 307 struct TALER_EXCHANGE_GetAmlAttributesHandle *aagh, 308 TALER_EXCHANGE_GetAmlAttributesCallback cb, 309 TALER_EXCHANGE_GET_AML_ATTRIBUTES_RESULT_CLOSURE *cb_cls); 310 311 312 /** 313 * Cancel GET /aml/$OPUB/attributes/$H_NORMALIZED_PAYTO operation. 314 * 315 * @param[in] aagh operation to cancel 316 */ 317 void 318 TALER_EXCHANGE_get_aml_attributes_cancel ( 319 struct TALER_EXCHANGE_GetAmlAttributesHandle *aagh); 320 321 322 #endif 323 /* _TALER_EXCHANGE__GET_AML_OFFICER_PUB_ATTRIBUTES_H_NORMALIZED_PAYTO_H */