get-private-transfers.h (12610B)
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-transfers.h 19 * @brief C interface for the GET /private/transfers endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__GET_PRIVATE_TRANSFERS_H 23 #define _TALER_MERCHANT__GET_PRIVATE_TRANSFERS_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the GET /private/transfers request. 30 */ 31 enum TALER_MERCHANT_GetPrivateTransfersOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_END = 0, 37 38 /** 39 * Filter by payto URI. 40 */ 41 TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_PAYTO_URI, 42 43 /** 44 * Filter for transfers before this time. 45 */ 46 TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_BEFORE, 47 48 /** 49 * Filter for transfers after this time. 50 */ 51 TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_AFTER, 52 53 /** 54 * Return at most N values. Negative values 55 * to return in descending order, positive for ascending. 56 * Default is -20. 57 */ 58 TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_LIMIT, 59 60 /** 61 * Starting transfer_serial_id for pagination. 62 */ 63 TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_OFFSET, 64 65 /** 66 * Filter by verification/expected status. 67 */ 68 TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_EXPECTED 69 70 }; 71 72 73 /** 74 * Value for an option for the GET /private/transfers request. 75 */ 76 struct TALER_MERCHANT_GetPrivateTransfersOptionValue 77 { 78 79 /** 80 * Type of the option being set. 81 */ 82 enum TALER_MERCHANT_GetPrivateTransfersOption option; 83 84 /** 85 * Specific option value. 86 */ 87 union 88 { 89 90 /** 91 * Value if @e option is 92 * #TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_PAYTO_URI. 93 */ 94 struct TALER_FullPayto payto_uri; 95 96 /** 97 * Value if @e option is 98 * #TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_BEFORE. 99 */ 100 struct GNUNET_TIME_Timestamp before; 101 102 /** 103 * Value if @e option is 104 * #TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_AFTER. 105 */ 106 struct GNUNET_TIME_Timestamp after; 107 108 /** 109 * Value if @e option is 110 * #TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_LIMIT. 111 */ 112 int64_t limit; 113 114 /** 115 * Value if @e option is 116 * #TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_OFFSET. 117 */ 118 uint64_t offset; 119 120 /** 121 * Value if @e option is 122 * #TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_EXPECTED. 123 */ 124 enum TALER_EXCHANGE_YesNoAll expected; 125 126 } details; 127 128 }; 129 130 131 /** 132 * Handle for a GET /private/transfers request. 133 */ 134 struct TALER_MERCHANT_GetPrivateTransfersHandle; 135 136 137 /** 138 * Set up GET /private/transfers operation. 139 * Note that you must explicitly start the operation after 140 * possibly setting options. 141 * 142 * @param ctx the context 143 * @param url base URL of the merchant backend 144 * @return handle to operation 145 */ 146 struct TALER_MERCHANT_GetPrivateTransfersHandle * 147 TALER_MERCHANT_get_private_transfers_create ( 148 struct GNUNET_CURL_Context *ctx, 149 const char *url); 150 151 152 /** 153 * Terminate the list of the options. 154 * 155 * @return the terminating object of struct TALER_MERCHANT_GetPrivateTransfersOptionValue 156 */ 157 #define TALER_MERCHANT_get_private_transfers_option_end_() \ 158 (const struct TALER_MERCHANT_GetPrivateTransfersOptionValue) \ 159 { \ 160 .option = TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_END \ 161 } 162 163 /** 164 * Set payto URI filter. 165 * 166 * @param p payto URI to filter by 167 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateTransfersOptionValue 168 */ 169 #define TALER_MERCHANT_get_private_transfers_option_payto_uri(p) \ 170 (const struct TALER_MERCHANT_GetPrivateTransfersOptionValue) \ 171 { \ 172 .option = TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_PAYTO_URI, \ 173 .details.payto_uri = (p) \ 174 } 175 176 /** 177 * Set filter for transfers before the given timestamp. 178 * 179 * @param t timestamp threshold 180 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateTransfersOptionValue 181 */ 182 #define TALER_MERCHANT_get_private_transfers_option_before(t) \ 183 (const struct TALER_MERCHANT_GetPrivateTransfersOptionValue) \ 184 { \ 185 .option = TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_BEFORE, \ 186 .details.before = (t) \ 187 } 188 189 /** 190 * Set filter for transfers after the given timestamp. 191 * 192 * @param t timestamp threshold 193 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateTransfersOptionValue 194 */ 195 #define TALER_MERCHANT_get_private_transfers_option_after(t) \ 196 (const struct TALER_MERCHANT_GetPrivateTransfersOptionValue) \ 197 { \ 198 .option = TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_AFTER, \ 199 .details.after = (t) \ 200 } 201 202 /** 203 * Set limit on the number of results to return. 204 * 205 * @param l limit on the number of results to return 206 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateTransfersOptionValue 207 */ 208 #define TALER_MERCHANT_get_private_transfers_option_limit(l) \ 209 (const struct TALER_MERCHANT_GetPrivateTransfersOptionValue) \ 210 { \ 211 .option = TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_LIMIT, \ 212 .details.limit = (l) \ 213 } 214 215 /** 216 * Set row offset from which to return results. 217 * 218 * @param o offset to use 219 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateTransfersOptionValue 220 */ 221 #define TALER_MERCHANT_get_private_transfers_option_offset(o) \ 222 (const struct TALER_MERCHANT_GetPrivateTransfersOptionValue) \ 223 { \ 224 .option = TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_OFFSET, \ 225 .details.offset = (o) \ 226 } 227 228 /** 229 * Set filter on expected/verified status. 230 * 231 * @param e expected filter to use 232 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateTransfersOptionValue 233 */ 234 #define TALER_MERCHANT_get_private_transfers_option_expected(e) \ 235 (const struct TALER_MERCHANT_GetPrivateTransfersOptionValue) \ 236 { \ 237 .option = TALER_MERCHANT_GET_PRIVATE_TRANSFERS_OPTION_EXPECTED, \ 238 .details.expected = (e) \ 239 } 240 241 242 /** 243 * Set the requested options for the operation. 244 * 245 * If any option fail other options may be or may be not applied. 246 * 247 * @param gth the request to set the options for 248 * @param num_options length of the @a options array 249 * @param options an array of options 250 * @return #GNUNET_OK on success, 251 * #GNUNET_NO on failure, 252 * #GNUNET_SYSERR on internal error 253 */ 254 enum GNUNET_GenericReturnValue 255 TALER_MERCHANT_get_private_transfers_set_options_ ( 256 struct TALER_MERCHANT_GetPrivateTransfersHandle *gth, 257 unsigned int num_options, 258 const struct TALER_MERCHANT_GetPrivateTransfersOptionValue *options); 259 260 261 /** 262 * Set the requested options for the operation. 263 * 264 * If any option fail other options may be or may be not applied. 265 * 266 * It should be used with helpers that create required options, for example: 267 * 268 * TALER_MERCHANT_get_private_transfers_set_options ( 269 * gth, 270 * TALER_MERCHANT_get_private_transfers_option_limit (-20), 271 * TALER_MERCHANT_get_private_transfers_option_expected ( 272 * TALER_EXCHANGE_YNA_YES)); 273 * 274 * @param gth the request to set the options for 275 * @param ... the list of the options, each option must be created 276 * by helpers TALER_MERCHANT_get_private_transfers_option_NAME(VALUE) 277 * @return #GNUNET_OK on success, 278 * #GNUNET_NO on failure, 279 * #GNUNET_SYSERR on internal error 280 */ 281 #define TALER_MERCHANT_get_private_transfers_set_options(gth,...) \ 282 TALER_MERCHANT_get_private_transfers_set_options_ ( \ 283 gth, \ 284 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 285 ((const struct TALER_MERCHANT_GetPrivateTransfersOptionValue[]) \ 286 {__VA_ARGS__, TALER_MERCHANT_get_private_transfers_option_end_ () } \ 287 )) 288 289 290 /** 291 * Transfer data entry. 292 */ 293 struct TALER_MERCHANT_GetPrivateTransfersTransferData 294 { 295 296 /** 297 * Total amount wired by the exchange (without wire fee). 298 */ 299 struct TALER_Amount credit_amount; 300 301 /** 302 * Wire transfer identifier used. 303 */ 304 struct TALER_WireTransferIdentifierRawP wtid; 305 306 /** 307 * URI of the target account. 308 */ 309 struct TALER_FullPayto payto_uri; 310 311 /** 312 * URL of the exchange that made the transfer. 313 */ 314 const char *exchange_url; 315 316 /** 317 * Serial number of the credit operation in the merchant backend. 318 */ 319 uint64_t transfer_serial_id; 320 321 /** 322 * Time of the wire transfer, based on when we received 323 * a confirmation for the wire transfer. 324 */ 325 struct GNUNET_TIME_Timestamp execution_time; 326 327 /** 328 * Serial number of the expected transfer in the merchant backend, 329 * or 0 if not known. 330 */ 331 uint64_t expected_transfer_serial_id; 332 333 /** 334 * True if this wire transfer was expected. 335 */ 336 bool expected; 337 338 }; 339 340 341 /** 342 * Response details for a GET /private/transfers request. 343 */ 344 struct TALER_MERCHANT_GetPrivateTransfersResponse 345 { 346 347 /** 348 * HTTP response details. 349 */ 350 struct TALER_MERCHANT_HttpResponse hr; 351 352 /** 353 * Details depending on the HTTP status code. 354 */ 355 union 356 { 357 358 /** 359 * Details on #MHD_HTTP_OK. 360 */ 361 struct 362 { 363 364 /** 365 * Number of transfers in @a transfers. 366 */ 367 unsigned int transfers_length; 368 369 /** 370 * Array of transfer data entries. 371 */ 372 const struct TALER_MERCHANT_GetPrivateTransfersTransferData *transfers; 373 374 } ok; 375 376 } details; 377 378 }; 379 380 381 #ifndef TALER_MERCHANT_GET_PRIVATE_TRANSFERS_RESULT_CLOSURE 382 /** 383 * Type of the closure used by 384 * the #TALER_MERCHANT_GetPrivateTransfersCallback. 385 */ 386 #define TALER_MERCHANT_GET_PRIVATE_TRANSFERS_RESULT_CLOSURE void 387 #endif /* TALER_MERCHANT_GET_PRIVATE_TRANSFERS_RESULT_CLOSURE */ 388 389 /** 390 * Callback for a GET /private/transfers request. 391 * 392 * @param cls closure 393 * @param gtr response details 394 */ 395 typedef void 396 (*TALER_MERCHANT_GetPrivateTransfersCallback)( 397 TALER_MERCHANT_GET_PRIVATE_TRANSFERS_RESULT_CLOSURE *cls, 398 const struct TALER_MERCHANT_GetPrivateTransfersResponse *gtr); 399 400 401 /** 402 * Start GET /private/transfers operation. 403 * 404 * @param[in,out] gth operation to start 405 * @param cb function to call with the merchant's result 406 * @param cb_cls closure for @a cb 407 * @return status code, #TALER_EC_NONE on success 408 */ 409 enum TALER_ErrorCode 410 TALER_MERCHANT_get_private_transfers_start ( 411 struct TALER_MERCHANT_GetPrivateTransfersHandle *gth, 412 TALER_MERCHANT_GetPrivateTransfersCallback cb, 413 TALER_MERCHANT_GET_PRIVATE_TRANSFERS_RESULT_CLOSURE *cb_cls); 414 415 416 /** 417 * Cancel GET /private/transfers operation. This function must not be 418 * called by clients after the TALER_MERCHANT_GetPrivateTransfersCallback 419 * has been invoked (as in those cases it'll be called internally by 420 * the implementation already). 421 * 422 * @param[in] gth operation to cancel 423 */ 424 void 425 TALER_MERCHANT_get_private_transfers_cancel ( 426 struct TALER_MERCHANT_GetPrivateTransfersHandle *gth); 427 428 429 #endif /* _TALER_MERCHANT__GET_PRIVATE_TRANSFERS_H */