get-private-donau.h (4619B)
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-donau.h 19 * @brief C interface for the GET /private/donau endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__GET_PRIVATE_DONAU_H 23 #define _TALER_MERCHANT__GET_PRIVATE_DONAU_H 24 25 #include <taler/merchant/common.h> 26 #include <donau/donau_service.h> 27 28 29 /** 30 * Handle for a GET /private/donau request. 31 */ 32 struct TALER_MERCHANT_GetPrivateDonauHandle; 33 34 35 /** 36 * Individual Donau instance details. 37 */ 38 struct TALER_MERCHANT_GetPrivateDonauDonauInstanceEntry 39 { 40 /** 41 * Serial number of the Donau instance in merchant database. 42 */ 43 uint64_t donau_instance_serial; 44 45 /** 46 * The URL of the Donau service. 47 */ 48 const char *donau_url; 49 50 /** 51 * Name of the charity associated with the Donau instance. 52 */ 53 const char *charity_name; 54 55 /** 56 * Public key of the charity. 57 */ 58 struct DONAU_CharityPublicKeyP charity_pub_key; 59 60 /** 61 * ID of the charity on Donau. 62 */ 63 uint64_t charity_id; 64 65 /** 66 * Maximum donation amount per year allowed for the charity. 67 */ 68 struct TALER_Amount charity_max_per_year; 69 70 /** 71 * Total donations received by the charity in the current year. 72 */ 73 struct TALER_Amount charity_receipts_to_date; 74 75 /** 76 * The current year being tracked for donations. 77 */ 78 int64_t current_year; 79 80 /** 81 * Additional key information related to the Donau instance. 82 */ 83 const struct DONAU_Keys *donau_keys; 84 }; 85 86 87 /** 88 * Response details for a GET /private/donau request. 89 */ 90 struct TALER_MERCHANT_GetPrivateDonauResponse 91 { 92 93 /** 94 * HTTP response details. 95 */ 96 struct TALER_MERCHANT_HttpResponse hr; 97 98 /** 99 * Details depending on the HTTP status code. 100 */ 101 union 102 { 103 104 /** 105 * Details on #MHD_HTTP_OK. 106 */ 107 struct 108 { 109 110 /** 111 * Number of Donau instances in @a donau_instances. 112 */ 113 unsigned int donau_instances_length; 114 115 /** 116 * Array of Donau instance entries. 117 */ 118 const struct TALER_MERCHANT_GetPrivateDonauDonauInstanceEntry * 119 donau_instances; 120 121 } ok; 122 123 } details; 124 125 }; 126 127 128 /** 129 * Set up GET /private/donau operation. 130 * Note that you must explicitly start the operation after 131 * possibly setting options. 132 * 133 * @param ctx the context 134 * @param url base URL of the merchant backend 135 * @return handle to operation 136 */ 137 struct TALER_MERCHANT_GetPrivateDonauHandle * 138 TALER_MERCHANT_get_private_donau_create ( 139 struct GNUNET_CURL_Context *ctx, 140 const char *url); 141 142 143 #ifndef TALER_MERCHANT_GET_PRIVATE_DONAU_RESULT_CLOSURE 144 /** 145 * Type of the closure used by 146 * the #TALER_MERCHANT_GetPrivateDonauCallback. 147 */ 148 #define TALER_MERCHANT_GET_PRIVATE_DONAU_RESULT_CLOSURE void 149 #endif /* TALER_MERCHANT_GET_PRIVATE_DONAU_RESULT_CLOSURE */ 150 151 /** 152 * Callback for a GET /private/donau request. 153 * 154 * @param cls closure 155 * @param dgr response details 156 */ 157 typedef void 158 (*TALER_MERCHANT_GetPrivateDonauCallback)( 159 TALER_MERCHANT_GET_PRIVATE_DONAU_RESULT_CLOSURE *cls, 160 const struct TALER_MERCHANT_GetPrivateDonauResponse *dgr); 161 162 163 /** 164 * Start GET /private/donau operation. 165 * 166 * @param[in,out] gpdh operation to start 167 * @param cb function to call with the merchant's result 168 * @param cb_cls closure for @a cb 169 * @return status code, #TALER_EC_NONE on success 170 */ 171 enum TALER_ErrorCode 172 TALER_MERCHANT_get_private_donau_start ( 173 struct TALER_MERCHANT_GetPrivateDonauHandle *gpdh, 174 TALER_MERCHANT_GetPrivateDonauCallback cb, 175 TALER_MERCHANT_GET_PRIVATE_DONAU_RESULT_CLOSURE *cb_cls); 176 177 178 /** 179 * Cancel GET /private/donau operation. This function must not be 180 * called by clients after the TALER_MERCHANT_GetPrivateDonauCallback 181 * has been invoked (as in those cases it'll be called internally by the 182 * implementation already). 183 * 184 * @param[in] gpdh operation to cancel 185 */ 186 void 187 TALER_MERCHANT_get_private_donau_cancel ( 188 struct TALER_MERCHANT_GetPrivateDonauHandle *gpdh); 189 190 191 #endif /* _TALER_MERCHANT__GET_PRIVATE_DONAU_H */