patch-private-accounts-H_WIRE.h (9118B)
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/patch-private-accounts-H_WIRE.h 19 * @brief C interface for PATCH /private/accounts/$H_WIRE 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__PATCH_PRIVATE_ACCOUNTS_H_WIRE_H 23 #define _TALER_MERCHANT__PATCH_PRIVATE_ACCOUNTS_H_WIRE_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the PATCH /private/accounts/$H_WIRE request. 30 */ 31 enum TALER_MERCHANT_PatchPrivateAccountOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_OPTION_END = 0, 37 38 /** 39 * Set the credit facade URL. 40 */ 41 TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_OPTION_CREDIT_FACADE_URL, 42 43 /** 44 * Set the credit facade credentials (JSON). 45 */ 46 TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_OPTION_CREDIT_FACADE_CREDENTIALS, 47 48 /** 49 * Set the extra wire subject metadata (restricted text). 50 */ 51 TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_OPTION_EXTRA_WIRE_SUBJECT_METADATA 52 53 }; 54 55 56 /** 57 * Value for an option for the PATCH /private/accounts/$H_WIRE request. 58 */ 59 struct TALER_MERCHANT_PatchPrivateAccountOptionValue 60 { 61 62 /** 63 * Type of the option being set. 64 */ 65 enum TALER_MERCHANT_PatchPrivateAccountOption option; 66 67 /** 68 * Specific option value. 69 */ 70 union 71 { 72 73 /** 74 * Value if @e option is 75 * #TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_OPTION_CREDIT_FACADE_URL. 76 */ 77 const char *credit_facade_url; 78 79 /** 80 * Value if @e option is 81 * #TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_OPTION_CREDIT_FACADE_CREDENTIALS. 82 */ 83 const json_t *credit_facade_credentials; 84 85 /** 86 * Value if @e option is 87 * #TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_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 PATCH /private/accounts/$H_WIRE operation. 98 */ 99 struct TALER_MERCHANT_PatchPrivateAccountHandle; 100 101 102 /** 103 * Set up PATCH /private/accounts/$H_WIRE operation. 104 * Note that you must explicitly start the operation after 105 * possibly setting options. 106 * 107 * @param ctx the context 108 * @param url base URL of the merchant backend 109 * @param h_wire hash of the wire details identifying the account 110 * @return handle to operation, NULL on error 111 */ 112 struct TALER_MERCHANT_PatchPrivateAccountHandle * 113 TALER_MERCHANT_patch_private_account_create ( 114 struct GNUNET_CURL_Context *ctx, 115 const char *url, 116 const struct TALER_MerchantWireHashP *h_wire); 117 118 119 /** 120 * Terminate the list of the options. 121 * 122 * @return the terminating object of struct TALER_MERCHANT_PatchPrivateAccountOptionValue 123 */ 124 #define TALER_MERCHANT_patch_private_account_option_end_() \ 125 (const struct TALER_MERCHANT_PatchPrivateAccountOptionValue) \ 126 { \ 127 .option = TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_OPTION_END \ 128 } 129 130 /** 131 * Set credit facade URL. 132 * 133 * @param u credit facade URL to set 134 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateAccountOptionValue 135 */ 136 #define TALER_MERCHANT_patch_private_account_option_credit_facade_url(u) \ 137 (const struct TALER_MERCHANT_PatchPrivateAccountOptionValue) \ 138 { \ 139 .option = \ 140 TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_OPTION_CREDIT_FACADE_URL, \ 141 .details.credit_facade_url = (u) \ 142 } 143 144 /** 145 * Set credit facade credentials. 146 * 147 * @param c credit facade credentials (JSON) to set 148 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateAccountOptionValue 149 */ 150 #define TALER_MERCHANT_patch_private_account_option_credit_facade_credentials(c) \ 151 (const struct TALER_MERCHANT_PatchPrivateAccountOptionValue) \ 152 { \ 153 .option = \ 154 TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_OPTION_CREDIT_FACADE_CREDENTIALS, \ 155 .details.credit_facade_credentials = (c) \ 156 } 157 158 /** 159 * Set extra wire subject metadata. 160 * 161 * @param m extra wire subject metadata (JSON) to set 162 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateAccountOptionValue 163 */ 164 #define TALER_MERCHANT_patch_private_account_option_extra_wire_subject_metadata(m) \ 165 (const struct TALER_MERCHANT_PatchPrivateAccountOptionValue) \ 166 { \ 167 .option = \ 168 TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_OPTION_EXTRA_WIRE_SUBJECT_METADATA, \ 169 .details.extra_wire_subject_metadata = (m) \ 170 } 171 172 173 /** 174 * Set the requested options for the operation. 175 * 176 * If any option fail other options may be or may be not applied. 177 * 178 * @param pah the request to set the options for 179 * @param num_options length of the @a options array 180 * @param options an array of options 181 * @return #GNUNET_OK on success, 182 * #GNUNET_NO on failure, 183 * #GNUNET_SYSERR on internal error 184 */ 185 enum GNUNET_GenericReturnValue 186 TALER_MERCHANT_patch_private_account_set_options_ ( 187 struct TALER_MERCHANT_PatchPrivateAccountHandle *pah, 188 unsigned int num_options, 189 const struct TALER_MERCHANT_PatchPrivateAccountOptionValue *options); 190 191 192 /** 193 * Set the requested options for the operation. 194 * 195 * If any option fail other options may be or may be not applied. 196 * 197 * It should be used with helpers that create required options, for example: 198 * 199 * TALER_MERCHANT_patch_private_account_set_options ( 200 * pah, 201 * TALER_MERCHANT_patch_private_account_option_credit_facade_url ( 202 * "https://example.com/facade")); 203 * 204 * @param pah the request to set the options for 205 * @param ... the list of the options, each option must be created 206 * by helpers TALER_MERCHANT_patch_private_account_option_NAME(VALUE) 207 * @return #GNUNET_OK on success, 208 * #GNUNET_NO on failure, 209 * #GNUNET_SYSERR on internal error 210 */ 211 #define TALER_MERCHANT_patch_private_account_set_options(pah,...) \ 212 TALER_MERCHANT_patch_private_account_set_options_ ( \ 213 pah, \ 214 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 215 ((const struct TALER_MERCHANT_PatchPrivateAccountOptionValue[]) \ 216 {__VA_ARGS__, TALER_MERCHANT_patch_private_account_option_end_ () } \ 217 )) 218 219 220 /** 221 * Response details for a PATCH /private/accounts/$H_WIRE request. 222 */ 223 struct TALER_MERCHANT_PatchPrivateAccountResponse 224 { 225 /** 226 * HTTP response details. 227 */ 228 struct TALER_MERCHANT_HttpResponse hr; 229 }; 230 231 232 #ifndef TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_RESULT_CLOSURE 233 /** 234 * Type of the closure used by 235 * the #TALER_MERCHANT_PatchPrivateAccountCallback. 236 */ 237 #define TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_RESULT_CLOSURE void 238 #endif /* TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_RESULT_CLOSURE */ 239 240 /** 241 * Callback for a PATCH /private/accounts/$H_WIRE request. 242 * 243 * @param cls closure 244 * @param result response details 245 */ 246 typedef void 247 (*TALER_MERCHANT_PatchPrivateAccountCallback)( 248 TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_RESULT_CLOSURE *cls, 249 const struct TALER_MERCHANT_PatchPrivateAccountResponse *result); 250 251 252 /** 253 * Start PATCH /private/accounts/$H_WIRE operation. 254 * 255 * @param[in,out] pah operation to start 256 * @param cb function to call with the result 257 * @param cb_cls closure for @a cb 258 * @return status code, #TALER_EC_NONE on success 259 */ 260 enum TALER_ErrorCode 261 TALER_MERCHANT_patch_private_account_start ( 262 struct TALER_MERCHANT_PatchPrivateAccountHandle *pah, 263 TALER_MERCHANT_PatchPrivateAccountCallback cb, 264 TALER_MERCHANT_PATCH_PRIVATE_ACCOUNT_RESULT_CLOSURE *cb_cls); 265 266 267 /** 268 * Cancel PATCH /private/accounts/$H_WIRE operation. 269 * This function must not be called by clients after the 270 * callback has been invoked. 271 * 272 * @param[in] pah operation to cancel 273 */ 274 void 275 TALER_MERCHANT_patch_private_account_cancel ( 276 struct TALER_MERCHANT_PatchPrivateAccountHandle *pah); 277 278 279 #endif /* _TALER_MERCHANT__PATCH_PRIVATE_ACCOUNTS_H_WIRE_H */