post-private-accounts.h (8974B)
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-accounts.h 19 * @brief C interface for the POST /private/accounts endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_PRIVATE_ACCOUNTS_H 23 #define _TALER_MERCHANT__POST_PRIVATE_ACCOUNTS_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options for the POST /private/accounts request. 30 */ 31 enum TALER_MERCHANT_PostPrivateAccountsOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_OPTION_END = 0, 37 38 /** 39 * URL of the credit facade. 40 */ 41 TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_OPTION_CREDIT_FACADE_URL, 42 43 /** 44 * Credentials for the credit facade (JSON). 45 */ 46 TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_OPTION_CREDIT_FACADE_CREDENTIALS, 47 48 /** 49 * Extra wire subject metadata (restricted text). 50 */ 51 TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_OPTION_EXTRA_WIRE_SUBJECT_METADATA 52 53 }; 54 55 56 /** 57 * Value for an option for the POST /private/accounts request. 58 */ 59 struct TALER_MERCHANT_PostPrivateAccountsOptionValue 60 { 61 62 /** 63 * Type of the option being set. 64 */ 65 enum TALER_MERCHANT_PostPrivateAccountsOption option; 66 67 /** 68 * Specific option value. 69 */ 70 union 71 { 72 73 /** 74 * Value if @e option is 75 * #TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_OPTION_CREDIT_FACADE_URL. 76 */ 77 const char *credit_facade_url; 78 79 /** 80 * Value if @e option is 81 * #TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_OPTION_CREDIT_FACADE_CREDENTIALS. 82 */ 83 const json_t *credit_facade_credentials; 84 85 /** 86 * Value if @e option is 87 * #TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_OPTION_EXTRA_WIRE_SUBJECT_METADATA. 88 */ 89 const char *extra_wire_subject_metadata; 90 91 } details; 92 93 }; 94 95 96 /** 97 * Handle for a POST /private/accounts request. 98 */ 99 struct TALER_MERCHANT_PostPrivateAccountsHandle; 100 101 102 /** 103 * Response details for a POST /private/accounts request. 104 */ 105 struct TALER_MERCHANT_PostPrivateAccountsResponse 106 { 107 108 /** 109 * HTTP response details. 110 */ 111 struct TALER_MERCHANT_HttpResponse hr; 112 113 /** 114 * Details depending on the HTTP status code. 115 */ 116 union 117 { 118 119 /** 120 * Details on #MHD_HTTP_OK. 121 */ 122 struct 123 { 124 125 /** 126 * Hash of the wire details for the newly created account. 127 */ 128 struct TALER_MerchantWireHashP h_wire; 129 130 /** 131 * Salt used in the wire hash computation. 132 */ 133 struct TALER_WireSaltP salt; 134 135 } ok; 136 137 /** 138 * Details on #MHD_HTTP_ACCEPTED. 139 */ 140 struct TALER_MERCHANT_MfaChallengeResponse accepted; 141 142 } details; 143 144 }; 145 146 147 /** 148 * Terminate the list of the options. 149 * 150 * @return the terminating object of struct TALER_MERCHANT_PostPrivateAccountsOptionValue 151 */ 152 #define TALER_MERCHANT_post_private_accounts_option_end_() \ 153 (const struct TALER_MERCHANT_PostPrivateAccountsOptionValue) \ 154 { \ 155 .option = TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_OPTION_END \ 156 } 157 158 /** 159 * Set credit facade URL. 160 * 161 * @param u credit facade URL 162 * @return representation of the option as a struct TALER_MERCHANT_PostPrivateAccountsOptionValue 163 */ 164 #define TALER_MERCHANT_post_private_accounts_option_credit_facade_url(u) \ 165 (const struct TALER_MERCHANT_PostPrivateAccountsOptionValue) \ 166 { \ 167 .option = \ 168 TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_OPTION_CREDIT_FACADE_URL, \ 169 .details.credit_facade_url = (u) \ 170 } 171 172 /** 173 * Set credit facade credentials. 174 * 175 * @param c credentials JSON object 176 * @return representation of the option as a struct TALER_MERCHANT_PostPrivateAccountsOptionValue 177 */ 178 #define TALER_MERCHANT_post_private_accounts_option_credit_facade_credentials(c) \ 179 (const struct TALER_MERCHANT_PostPrivateAccountsOptionValue) \ 180 { \ 181 .option = \ 182 TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_OPTION_CREDIT_FACADE_CREDENTIALS, \ 183 .details.credit_facade_credentials = (c) \ 184 } 185 186 /** 187 * Set extra wire subject metadata. 188 * 189 * @param m extra wire subject metadata (JSON) 190 * @return representation of the option as a struct TALER_MERCHANT_PostPrivateAccountsOptionValue 191 */ 192 #define TALER_MERCHANT_post_private_accounts_option_extra_wire_subject_metadata(m) \ 193 (const struct TALER_MERCHANT_PostPrivateAccountsOptionValue) \ 194 { \ 195 .option = \ 196 TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_OPTION_EXTRA_WIRE_SUBJECT_METADATA, \ 197 .details.extra_wire_subject_metadata = (m) \ 198 } 199 200 201 /** 202 * Set the requested options for the operation. 203 * 204 * @param ppah the request to set the options for 205 * @param num_options length of the @a options array 206 * @param options an array of options 207 * @return #GNUNET_OK on success, 208 * #GNUNET_NO on failure, 209 * #GNUNET_SYSERR on internal error 210 */ 211 enum GNUNET_GenericReturnValue 212 TALER_MERCHANT_post_private_accounts_set_options_ ( 213 struct TALER_MERCHANT_PostPrivateAccountsHandle *ppah, 214 unsigned int num_options, 215 const struct TALER_MERCHANT_PostPrivateAccountsOptionValue *options); 216 217 218 /** 219 * Set the requested options for the operation. 220 * 221 * @param ppah the request to set the options for 222 * @param ... the list of the options 223 * @return #GNUNET_OK on success, 224 * #GNUNET_NO on failure, 225 * #GNUNET_SYSERR on internal error 226 */ 227 #define TALER_MERCHANT_post_private_accounts_set_options(ppah,...) \ 228 TALER_MERCHANT_post_private_accounts_set_options_ ( \ 229 ppah, \ 230 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 231 ((const struct TALER_MERCHANT_PostPrivateAccountsOptionValue[]) \ 232 {__VA_ARGS__, TALER_MERCHANT_post_private_accounts_option_end_ () } \ 233 )) 234 235 236 /** 237 * Set up POST /private/accounts operation. 238 * Note that you must explicitly start the operation after 239 * possibly setting options. 240 * 241 * @param ctx the context 242 * @param url base URL of the merchant backend 243 * @param payto_uri payto URI of the account to add 244 * @return handle to operation 245 */ 246 struct TALER_MERCHANT_PostPrivateAccountsHandle * 247 TALER_MERCHANT_post_private_accounts_create ( 248 struct GNUNET_CURL_Context *ctx, 249 const char *url, 250 struct TALER_FullPayto payto_uri); 251 252 253 #ifndef TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_RESULT_CLOSURE 254 /** 255 * Type of the closure used by 256 * the #TALER_MERCHANT_PostPrivateAccountsCallback. 257 */ 258 #define TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_RESULT_CLOSURE void 259 #endif /* TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_RESULT_CLOSURE */ 260 261 /** 262 * Callback for a POST /private/accounts request. 263 * 264 * @param cls closure 265 * @param apr response details 266 */ 267 typedef void 268 (*TALER_MERCHANT_PostPrivateAccountsCallback)( 269 TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_RESULT_CLOSURE *cls, 270 const struct TALER_MERCHANT_PostPrivateAccountsResponse *apr); 271 272 273 /** 274 * Start POST /private/accounts operation. 275 * 276 * @param[in,out] ppah operation to start 277 * @param cb function to call with the merchant's result 278 * @param cb_cls closure for @a cb 279 * @return status code, #TALER_EC_NONE on success 280 */ 281 enum TALER_ErrorCode 282 TALER_MERCHANT_post_private_accounts_start ( 283 struct TALER_MERCHANT_PostPrivateAccountsHandle *ppah, 284 TALER_MERCHANT_PostPrivateAccountsCallback cb, 285 TALER_MERCHANT_POST_PRIVATE_ACCOUNTS_RESULT_CLOSURE *cb_cls); 286 287 288 /** 289 * Cancel POST /private/accounts operation. This function must not be 290 * called by clients after the TALER_MERCHANT_PostPrivateAccountsCallback 291 * has been invoked (as in those cases it'll be called internally by the 292 * implementation already). 293 * 294 * @param[in] ppah operation to cancel 295 */ 296 void 297 TALER_MERCHANT_post_private_accounts_cancel ( 298 struct TALER_MERCHANT_PostPrivateAccountsHandle *ppah); 299 300 301 #endif /* _TALER_MERCHANT__POST_PRIVATE_ACCOUNTS_H */