post-private-donau.h (5916B)
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/post-private-donau.h 19 * @brief C interface for the POST /private/donau endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_PRIVATE_DONAU_H 23 #define _TALER_MERCHANT__POST_PRIVATE_DONAU_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Donau charity structure for POST /private/donau. 30 */ 31 struct TALER_MERCHANT_Charity 32 { 33 34 /** 35 * Base URL of the Donau/charity service. 36 */ 37 const char *charity_url; 38 39 /** 40 * Charity identifier at the Donau service. 41 */ 42 uint64_t charity_id; 43 44 }; 45 46 47 /** 48 * Possible options for the POST /private/donau request. 49 */ 50 enum TALER_MERCHANT_PostPrivateDonauOption 51 { 52 /** 53 * End of list of options. 54 */ 55 TALER_MERCHANT_POST_PRIVATE_DONAU_OPTION_END = 0, 56 57 }; 58 59 60 /** 61 * Value for an option for the POST /private/donau request. 62 */ 63 struct TALER_MERCHANT_PostPrivateDonauOptionValue 64 { 65 66 /** 67 * Type of the option being set. 68 */ 69 enum TALER_MERCHANT_PostPrivateDonauOption option; 70 71 /** 72 * Specific option value. 73 */ 74 union 75 { 76 77 } details; 78 79 }; 80 81 82 /** 83 * Handle for a POST /private/donau request. 84 */ 85 struct TALER_MERCHANT_PostPrivateDonauHandle; 86 87 88 /** 89 * Response details for a POST /private/donau request. 90 */ 91 struct TALER_MERCHANT_PostPrivateDonauResponse 92 { 93 94 /** 95 * HTTP response details. 96 */ 97 struct TALER_MERCHANT_HttpResponse hr; 98 99 /** 100 * Details depending on the HTTP status code. 101 */ 102 union 103 { 104 /** 105 * Details on #MHD_HTTP_ACCEPTED. 106 */ 107 struct TALER_MERCHANT_MfaChallengeResponse accepted; 108 } details; 109 110 }; 111 112 113 /** 114 * Terminate the list of the options. 115 * 116 * @return the terminating object 117 */ 118 #define TALER_MERCHANT_post_private_donau_option_end_() \ 119 (const struct TALER_MERCHANT_PostPrivateDonauOptionValue) \ 120 { \ 121 .option = TALER_MERCHANT_POST_PRIVATE_DONAU_OPTION_END \ 122 } 123 124 /** 125 * Set the requested options for the operation. 126 * 127 * @param ppdh the request to set the options for 128 * @param num_options length of the @a options array 129 * @param options an array of options 130 * @return #GNUNET_OK on success, 131 * #GNUNET_NO on failure, 132 * #GNUNET_SYSERR on internal error 133 */ 134 enum GNUNET_GenericReturnValue 135 TALER_MERCHANT_post_private_donau_set_options_ ( 136 struct TALER_MERCHANT_PostPrivateDonauHandle *ppdh, 137 unsigned int num_options, 138 const struct TALER_MERCHANT_PostPrivateDonauOptionValue *options); 139 140 141 /** 142 * Set the requested options for the operation. 143 * 144 * @param ppdh the request to set the options for 145 * @param ... the list of the options 146 * @return #GNUNET_OK on success, 147 * #GNUNET_NO on failure, 148 * #GNUNET_SYSERR on internal error 149 */ 150 #define TALER_MERCHANT_post_private_donau_set_options(ppdh,...) \ 151 TALER_MERCHANT_post_private_donau_set_options_ ( \ 152 ppdh, \ 153 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 154 ((const struct TALER_MERCHANT_PostPrivateDonauOptionValue[]) \ 155 {__VA_ARGS__, TALER_MERCHANT_post_private_donau_option_end_ () } \ 156 )) 157 158 159 /** 160 * Set up POST /private/donau operation. 161 * Note that you must explicitly start the operation after 162 * possibly setting options. 163 * 164 * @param ctx the context 165 * @param url base URL of the merchant backend 166 * @param charity charity information to register 167 * @return handle to operation 168 */ 169 struct TALER_MERCHANT_PostPrivateDonauHandle * 170 TALER_MERCHANT_post_private_donau_create ( 171 struct GNUNET_CURL_Context *ctx, 172 const char *url, 173 const struct TALER_MERCHANT_Charity *charity); 174 175 176 #ifndef TALER_MERCHANT_POST_PRIVATE_DONAU_RESULT_CLOSURE 177 /** 178 * Type of the closure used by 179 * the #TALER_MERCHANT_PostPrivateDonauCallback. 180 */ 181 #define TALER_MERCHANT_POST_PRIVATE_DONAU_RESULT_CLOSURE void 182 #endif /* TALER_MERCHANT_POST_PRIVATE_DONAU_RESULT_CLOSURE */ 183 184 /** 185 * Callback for a POST /private/donau request. 186 * 187 * @param cls closure 188 * @param pdr response details 189 */ 190 typedef void 191 (*TALER_MERCHANT_PostPrivateDonauCallback)( 192 TALER_MERCHANT_POST_PRIVATE_DONAU_RESULT_CLOSURE *cls, 193 const struct TALER_MERCHANT_PostPrivateDonauResponse *pdr); 194 195 196 /** 197 * Start POST /private/donau operation. 198 * 199 * @param[in,out] ppdh operation to start 200 * @param cb function to call with the merchant's result 201 * @param cb_cls closure for @a cb 202 * @return status code, #TALER_EC_NONE on success 203 */ 204 enum TALER_ErrorCode 205 TALER_MERCHANT_post_private_donau_start ( 206 struct TALER_MERCHANT_PostPrivateDonauHandle *ppdh, 207 TALER_MERCHANT_PostPrivateDonauCallback cb, 208 TALER_MERCHANT_POST_PRIVATE_DONAU_RESULT_CLOSURE *cb_cls); 209 210 211 /** 212 * Cancel POST /private/donau operation. This function must not be 213 * called by clients after the TALER_MERCHANT_PostPrivateDonauCallback 214 * has been invoked (as in those cases it'll be called internally by the 215 * implementation already). 216 * 217 * @param[in] ppdh operation to cancel 218 */ 219 void 220 TALER_MERCHANT_post_private_donau_cancel ( 221 struct TALER_MERCHANT_PostPrivateDonauHandle *ppdh); 222 223 224 #endif /* _TALER_MERCHANT__POST_PRIVATE_DONAU_H */