anastasis_eufin_lib.h (6226B)
1 /* 2 This file is part of ANASTASIS 3 Copyright (C) 2021 Anastasis Systems SA 4 5 ANASTASIS 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 ANASTASIS 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 ANASTASIS; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file include/anastasis_eufin_lib.h 18 * @brief C interface to access the Anastasis facade of LibEuFin 19 * See https://docs.taler.net/TBD 20 * @author Christian Grothoff 21 */ 22 #ifndef ANASTASIS_EUFIN_LIB_H 23 #define ANASTASIS_EUFIN_LIB_H 24 25 #define GNU_TALER_ERROR_CODES_H 1 26 #include "anastasis_error_codes.h" 27 #include <jansson.h> 28 #include <gnunet/gnunet_curl_lib.h> 29 #include <taler/taler_util.h> 30 31 32 /** 33 * Authentication method types. 34 */ 35 enum ANASTASIS_EUFIN_AuthenticationMethod 36 { 37 38 /** 39 * No authentication. 40 */ 41 ANASTASIS_EUFIN_AUTH_NONE, 42 43 /** 44 * Basic authentication with cleartext username and password. 45 */ 46 ANASTASIS_EUFIN_AUTH_BASIC, 47 }; 48 49 50 /** 51 * Information used to authenticate to the bank. 52 */ 53 struct ANASTASIS_EUFIN_AuthenticationData 54 { 55 56 /** 57 * Base URL we use to talk to the wire gateway, 58 * which talks to the bank for us. 59 */ 60 char *wire_gateway_url; 61 62 /** 63 * Which authentication method should we use? 64 */ 65 enum ANASTASIS_EUFIN_AuthenticationMethod method; 66 67 /** 68 * Further details as per @e method. 69 */ 70 union 71 { 72 73 /** 74 * Details for #ANASTASIS_EUFIN_AUTH_BASIC. 75 */ 76 struct 77 { 78 /** 79 * Username to use. 80 */ 81 char *username; 82 83 /** 84 * Password to use. 85 */ 86 char *password; 87 } basic; 88 89 } details; 90 91 }; 92 93 94 /* ********************* /history/incoming *********************** */ 95 96 /** 97 * Handle for querying the bank for transactions 98 * made to the exchange. 99 */ 100 struct ANASTASIS_EUFIN_CreditHistoryHandle; 101 102 /** 103 * Details about a wire transfer to the exchange. 104 */ 105 struct ANASTASIS_EUFIN_CreditDetails 106 { 107 /** 108 * Amount that was transferred 109 */ 110 struct TALER_Amount amount; 111 112 /** 113 * Time of the the transfer 114 */ 115 struct GNUNET_TIME_Timestamp execution_date; 116 117 /** 118 * The wire transfer subject. 119 */ 120 const char *wire_subject; 121 122 /** 123 * payto://-URL of the source account that 124 * send the funds. 125 */ 126 const char *debit_account_uri; 127 128 /** 129 * payto://-URL of the target account that 130 * received the funds. 131 */ 132 const char *credit_account_uri; 133 }; 134 135 136 /** 137 * Callbacks of this type are used to serve the result of asking 138 * the bank for the credit transaction history. 139 * 140 * @param cls closure 141 * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request 142 * 0 if the bank's reply is bogus (fails to follow the protocol), 143 * #MHD_HTTP_NO_CONTENT if there are no more results; on success the 144 * last callback is always of this status (even if `abs(num_results)` were 145 * already returned). 146 * @param ec detailed error code 147 * @param serial_id monotonically increasing counter corresponding to the transaction 148 * @param details details about the wire transfer 149 * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration 150 */ 151 typedef enum GNUNET_GenericReturnValue 152 (*ANASTASIS_EUFIN_CreditHistoryCallback)( 153 void *cls, 154 unsigned int http_status, 155 enum TALER_ErrorCode ec, 156 uint64_t serial_id, 157 const struct ANASTASIS_EUFIN_CreditDetails *details); 158 159 160 /** 161 * Request the wire credit history of an exchange's bank account. 162 * 163 * @param ctx curl context for the event loop 164 * @param auth authentication data to use 165 * @param start_row from which row on do we want to get results, use UINT64_MAX for the latest; exclusive 166 * @param num_results how many results do we want; negative numbers to go into the past, 167 * positive numbers to go into the future starting at @a start_row; 168 * must not be zero. 169 * @param timeout how long the client is willing to wait for more results 170 * (only useful if @a num_results is positive) 171 * @param hres_cb the callback to call with the transaction history 172 * @param hres_cb_cls closure for the above callback 173 * @return NULL 174 * if the inputs are invalid (i.e. zero value for @e num_results). 175 * In this case, the callback is not called. 176 */ 177 struct ANASTASIS_EUFIN_CreditHistoryHandle * 178 ANASTASIS_EUFIN_credit_history ( 179 struct GNUNET_CURL_Context *ctx, 180 const struct ANASTASIS_EUFIN_AuthenticationData *auth, 181 uint64_t start_row, 182 int64_t num_results, 183 struct GNUNET_TIME_Relative timeout, 184 ANASTASIS_EUFIN_CreditHistoryCallback hres_cb, 185 void *hres_cb_cls); 186 187 188 /** 189 * Cancel an history request. This function cannot be used on a request 190 * handle if the last response (anything with a status code other than 191 * 200) is already served for it. 192 * 193 * @param hh the history request handle 194 */ 195 void 196 ANASTASIS_EUFIN_credit_history_cancel ( 197 struct ANASTASIS_EUFIN_CreditHistoryHandle *hh); 198 199 200 /* ******************** Convenience functions **************** */ 201 202 203 /** 204 * Convenience method for parsing configuration section with bank 205 * authentication data. 206 * 207 * @param cfg configuration to parse 208 * @param section the section with the configuration data 209 * @param[out] auth set to the configuration data found 210 * @return #GNUNET_OK on success 211 */ 212 int 213 ANASTASIS_EUFIN_auth_parse_cfg (const struct GNUNET_CONFIGURATION_Handle *cfg, 214 const char *section, 215 struct ANASTASIS_EUFIN_AuthenticationData *auth); 216 217 218 /** 219 * Free memory inside of @a auth (but not @a auth itself). 220 * Dual to #ANASTASIS_EUFIN_auth_parse_cfg(). 221 * 222 * @param auth authentication data to free 223 */ 224 void 225 ANASTASIS_EUFIN_auth_free (struct ANASTASIS_EUFIN_AuthenticationData *auth); 226 227 228 #endif /* _ANASTASIS_EUFIN_SERVICE_H */