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