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