get-config.h (6852B)
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-config.h 19 * @brief C interface for the GET /config endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__GET_CONFIG_H 23 #define _TALER_MERCHANT__GET_CONFIG_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Version compatibility status for the merchant backend. 30 */ 31 enum TALER_MERCHANT_GetConfigVersionCompatibility 32 { 33 /** 34 * The client and server are at the same version. 35 */ 36 TALER_MERCHANT_GET_CONFIG_VC_MATCH = 0, 37 38 /** 39 * The server is running a newer API version. 40 */ 41 TALER_MERCHANT_GET_CONFIG_VC_NEWER = 1, 42 43 /** 44 * The server is running an older API version. 45 */ 46 TALER_MERCHANT_GET_CONFIG_VC_OLDER = 2, 47 48 /** 49 * The versions are incompatible. 50 */ 51 TALER_MERCHANT_GET_CONFIG_VC_INCOMPATIBLE = 4, 52 53 /** 54 * A protocol error occurred. 55 */ 56 TALER_MERCHANT_GET_CONFIG_VC_PROTOCOL_ERROR = 8 57 }; 58 59 60 /** 61 * Information about an exchange as returned in the config response. 62 */ 63 struct TALER_MERCHANT_GetConfigExchangeInfo 64 { 65 66 /** 67 * Base URL of the exchange. 68 */ 69 const char *base_url; 70 71 /** 72 * Currency served by this exchange. 73 */ 74 const char *currency; 75 76 /** 77 * Master public key of the exchange. 78 */ 79 struct TALER_MasterPublicKeyP master_pub; 80 81 }; 82 83 84 /** 85 * Handle for a GET /config request. 86 */ 87 struct TALER_MERCHANT_GetConfigHandle; 88 89 90 /** 91 * Response details for a GET /config request. 92 */ 93 struct TALER_MERCHANT_GetConfigResponse 94 { 95 96 /** 97 * HTTP response details. 98 */ 99 struct TALER_MERCHANT_HttpResponse hr; 100 101 /** 102 * Details depending on the HTTP status code. 103 */ 104 union 105 { 106 107 /** 108 * Details on #MHD_HTTP_OK. 109 */ 110 struct 111 { 112 113 /** 114 * API version string. 115 */ 116 const char *version; 117 118 /** 119 * Currency used by this merchant backend. 120 */ 121 const char *currency; 122 123 /** 124 * Compatibility status with the client library. 125 */ 126 enum TALER_MERCHANT_GetConfigVersionCompatibility compat; 127 128 /** 129 * Number of exchanges in @a exchanges. 130 */ 131 unsigned int num_exchanges; 132 133 /** 134 * Array of exchange configurations. 135 */ 136 const struct TALER_MERCHANT_GetConfigExchangeInfo *exchanges; 137 138 /** 139 * Number of currency specifications in @a cspecs. 140 */ 141 unsigned int num_cspecs; 142 143 /** 144 * Array of currency specifications. 145 */ 146 const struct TALER_CurrencySpecification *cspecs; 147 148 /** 149 * Currency information returned by the backend. 150 */ 151 struct 152 { 153 /** 154 * Currency string. 155 */ 156 const char *currency; 157 158 /** 159 * Version string. 160 */ 161 const char *version; 162 } ci; 163 164 /** 165 * Implementation identifier (e.g. 166 * "urn:net:taler:specs:taler-merchant:c-reference"). 167 * NULL if not provided. 168 */ 169 const char *implementation; 170 171 /** 172 * Whether the backend supports self-provisioning. 173 */ 174 bool have_self_provisioning; 175 176 /** 177 * Whether the backend was compiled with Donau support. 178 */ 179 bool have_donau; 180 181 /** 182 * Allowed payment target types (as a string). 183 * NULL if not provided. 184 */ 185 const char *payment_target_types; 186 187 /** 188 * Payment target regex (as a string). 189 * NULL if not provided. 190 */ 191 const char *payment_target_regex; 192 193 /** 194 * Mandatory TAN channels (JSON array of strings). 195 * NULL if not provided. 196 */ 197 const json_t *mandatory_tan_channels; 198 199 /** 200 * Default pay delay. 201 */ 202 struct GNUNET_TIME_Relative default_pay_delay; 203 204 /** 205 * Default refund delay. 206 */ 207 struct GNUNET_TIME_Relative default_refund_delay; 208 209 /** 210 * Default wire transfer delay. 211 */ 212 struct GNUNET_TIME_Relative default_wire_transfer_delay; 213 214 /** 215 * Default persona. 216 */ 217 const char *default_persona; 218 219 /** 220 * Report generators (JSON array of strings). 221 * NULL if not provided. 222 * // FIXME: split up into array of strings? 223 */ 224 const json_t *report_generators; 225 226 /** 227 * Phone regex for validation. 228 * NULL if not provided. 229 */ 230 const char *phone_regex; 231 232 /** 233 * SPA configuration options (JSON object). 234 * NULL if not provided. 235 */ 236 const json_t *spa_options; 237 238 } ok; 239 240 } details; 241 242 }; 243 244 245 /** 246 * Set up GET /config operation. 247 * Note that you must explicitly start the operation after 248 * possibly setting options. 249 * 250 * @param ctx the context 251 * @param url base URL of the merchant backend 252 * @return handle to operation 253 */ 254 struct TALER_MERCHANT_GetConfigHandle * 255 TALER_MERCHANT_get_config_create ( 256 struct GNUNET_CURL_Context *ctx, 257 const char *url); 258 259 260 #ifndef TALER_MERCHANT_GET_CONFIG_RESULT_CLOSURE 261 /** 262 * Type of the closure used by 263 * the #TALER_MERCHANT_GetConfigCallback. 264 */ 265 #define TALER_MERCHANT_GET_CONFIG_RESULT_CLOSURE void 266 #endif /* TALER_MERCHANT_GET_CONFIG_RESULT_CLOSURE */ 267 268 /** 269 * Callback for a GET /config request. 270 * 271 * @param cls closure 272 * @param cr response details 273 */ 274 typedef void 275 (*TALER_MERCHANT_GetConfigCallback)( 276 TALER_MERCHANT_GET_CONFIG_RESULT_CLOSURE *cls, 277 const struct TALER_MERCHANT_GetConfigResponse *cr); 278 279 280 /** 281 * Start GET /config operation. 282 * 283 * @param[in,out] gch operation to start 284 * @param cb function to call with the merchant's result 285 * @param cb_cls closure for @a cb 286 * @return status code, #TALER_EC_NONE on success 287 */ 288 enum TALER_ErrorCode 289 TALER_MERCHANT_get_config_start ( 290 struct TALER_MERCHANT_GetConfigHandle *gch, 291 TALER_MERCHANT_GetConfigCallback cb, 292 TALER_MERCHANT_GET_CONFIG_RESULT_CLOSURE *cb_cls); 293 294 295 /** 296 * Cancel GET /config operation. This function must not be called 297 * by clients after the TALER_MERCHANT_GetConfigCallback has been 298 * invoked (as in those cases it'll be called internally by the 299 * implementation already). 300 * 301 * @param[in] gch operation to cancel 302 */ 303 void 304 TALER_MERCHANT_get_config_cancel ( 305 struct TALER_MERCHANT_GetConfigHandle *gch); 306 307 308 #endif /* _TALER_MERCHANT__GET_CONFIG_H */