post-templates-TEMPLATE_ID.h (7922B)
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-templates-TEMPLATE_ID.h 19 * @brief C interface for the POST /templates/$TEMPLATE_ID endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_TEMPLATES_TEMPLATE_ID_H 23 #define _TALER_MERCHANT__POST_TEMPLATES_TEMPLATE_ID_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options for the POST /templates/$TEMPLATE_ID request. 30 */ 31 enum TALER_MERCHANT_PostTemplatesOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_POST_TEMPLATES_OPTION_END = 0, 37 38 /** 39 * Order summary. 40 */ 41 TALER_MERCHANT_POST_TEMPLATES_OPTION_SUMMARY, 42 43 /** 44 * Total amount for the order. 45 */ 46 TALER_MERCHANT_POST_TEMPLATES_OPTION_AMOUNT, 47 48 /** 49 * Detailed contract customization (JSON). 50 */ 51 TALER_MERCHANT_POST_TEMPLATES_OPTION_DETAILS 52 53 }; 54 55 56 /** 57 * Value for an option for the POST /templates/$TEMPLATE_ID request. 58 */ 59 struct TALER_MERCHANT_PostTemplatesOptionValue 60 { 61 62 /** 63 * Type of the option being set. 64 */ 65 enum TALER_MERCHANT_PostTemplatesOption option; 66 67 /** 68 * Specific option value. 69 */ 70 union 71 { 72 73 /** 74 * Value if @e option is 75 * #TALER_MERCHANT_POST_TEMPLATES_OPTION_SUMMARY. 76 */ 77 const char *summary; 78 79 /** 80 * Value if @e option is 81 * #TALER_MERCHANT_POST_TEMPLATES_OPTION_AMOUNT. 82 */ 83 const struct TALER_Amount *amount; 84 85 /** 86 * Value if @e option is 87 * #TALER_MERCHANT_POST_TEMPLATES_OPTION_DETAILS. 88 */ 89 const json_t *details; 90 91 } details; 92 93 }; 94 95 96 /** 97 * Handle for a POST /templates/$TEMPLATE_ID request. 98 */ 99 struct TALER_MERCHANT_PostTemplatesHandle; 100 101 102 /** 103 * Response details for a POST /templates/$TEMPLATE_ID request. 104 */ 105 struct TALER_MERCHANT_PostTemplatesResponse 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 * Identifier of the created order. 127 */ 128 const char *order_id; 129 130 /** 131 * Claim token, or NULL. 132 */ 133 const struct TALER_ClaimTokenP *token; 134 135 /** 136 * Payment deadline. 137 */ 138 struct GNUNET_TIME_Timestamp pay_deadline; 139 140 } ok; 141 142 } details; 143 144 }; 145 146 147 /** 148 * Terminate the list of the options. 149 * 150 * @return the terminating object 151 */ 152 #define TALER_MERCHANT_post_templates_option_end_() \ 153 (const struct TALER_MERCHANT_PostTemplatesOptionValue) \ 154 { \ 155 .option = TALER_MERCHANT_POST_TEMPLATES_OPTION_END \ 156 } 157 158 /** 159 * Set order summary. 160 * 161 * @param s summary string 162 * @return representation of the option 163 */ 164 #define TALER_MERCHANT_post_templates_option_summary(s) \ 165 (const struct TALER_MERCHANT_PostTemplatesOptionValue) \ 166 { \ 167 .option = TALER_MERCHANT_POST_TEMPLATES_OPTION_SUMMARY, \ 168 .details.summary = (s) \ 169 } 170 171 /** 172 * Set total amount. 173 * 174 * @param a amount 175 * @return representation of the option 176 */ 177 #define TALER_MERCHANT_post_templates_option_amount(a) \ 178 (const struct TALER_MERCHANT_PostTemplatesOptionValue) \ 179 { \ 180 .option = TALER_MERCHANT_POST_TEMPLATES_OPTION_AMOUNT, \ 181 .details.amount = (a) \ 182 } 183 184 /** 185 * Set detailed contract customization. 186 * 187 * @param d details JSON object 188 * @return representation of the option 189 */ 190 #define TALER_MERCHANT_post_templates_option_details(d) \ 191 (const struct TALER_MERCHANT_PostTemplatesOptionValue) \ 192 { \ 193 .option = TALER_MERCHANT_POST_TEMPLATES_OPTION_DETAILS, \ 194 .details.details = (d) \ 195 } 196 197 198 /** 199 * Set the requested options for the operation. 200 * 201 * @param pth the request to set the options for 202 * @param num_options length of the @a options array 203 * @param options an array of options 204 * @return #GNUNET_OK on success, 205 * #GNUNET_NO on failure, 206 * #GNUNET_SYSERR on internal error 207 */ 208 enum GNUNET_GenericReturnValue 209 TALER_MERCHANT_post_templates_set_options_ ( 210 struct TALER_MERCHANT_PostTemplatesHandle *pth, 211 unsigned int num_options, 212 const struct TALER_MERCHANT_PostTemplatesOptionValue *options); 213 214 215 /** 216 * Set the requested options for the operation. 217 * 218 * @param pth the request to set the options for 219 * @param ... the list of the options 220 * @return #GNUNET_OK on success, 221 * #GNUNET_NO on failure, 222 * #GNUNET_SYSERR on internal error 223 */ 224 #define TALER_MERCHANT_post_templates_set_options(pth,...) \ 225 TALER_MERCHANT_post_templates_set_options_ ( \ 226 pth, \ 227 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 228 ((const struct TALER_MERCHANT_PostTemplatesOptionValue[]) \ 229 {__VA_ARGS__, TALER_MERCHANT_post_templates_option_end_ () } \ 230 )) 231 232 233 /** 234 * Set up POST /templates/$TEMPLATE_ID operation. 235 * Note that you must explicitly start the operation after 236 * possibly setting options. 237 * 238 * @param ctx the context 239 * @param url base URL of the merchant backend 240 * @param template_id identifier of the template to use 241 * @return handle to operation 242 */ 243 struct TALER_MERCHANT_PostTemplatesHandle * 244 TALER_MERCHANT_post_templates_create ( 245 struct GNUNET_CURL_Context *ctx, 246 const char *url, 247 const char *template_id); 248 249 250 #ifndef TALER_MERCHANT_POST_TEMPLATES_RESULT_CLOSURE 251 /** 252 * Type of the closure used by 253 * the #TALER_MERCHANT_PostTemplatesCallback. 254 */ 255 #define TALER_MERCHANT_POST_TEMPLATES_RESULT_CLOSURE void 256 #endif /* TALER_MERCHANT_POST_TEMPLATES_RESULT_CLOSURE */ 257 258 /** 259 * Callback for a POST /templates/$TEMPLATE_ID request. 260 * 261 * @param cls closure 262 * @param ptr response details 263 */ 264 typedef void 265 (*TALER_MERCHANT_PostTemplatesCallback)( 266 TALER_MERCHANT_POST_TEMPLATES_RESULT_CLOSURE *cls, 267 const struct TALER_MERCHANT_PostTemplatesResponse *ptr); 268 269 270 /** 271 * Start POST /templates/$TEMPLATE_ID operation. 272 * 273 * @param[in,out] pth operation to start 274 * @param cb function to call with the merchant's result 275 * @param cb_cls closure for @a cb 276 * @return status code, #TALER_EC_NONE on success 277 */ 278 enum TALER_ErrorCode 279 TALER_MERCHANT_post_templates_start ( 280 struct TALER_MERCHANT_PostTemplatesHandle *pth, 281 TALER_MERCHANT_PostTemplatesCallback cb, 282 TALER_MERCHANT_POST_TEMPLATES_RESULT_CLOSURE *cb_cls); 283 284 285 /** 286 * Cancel POST /templates/$TEMPLATE_ID operation. This function must not be 287 * called by clients after the TALER_MERCHANT_PostTemplatesCallback has 288 * been invoked (as in those cases it'll be called internally by the 289 * implementation already). 290 * 291 * @param[in] pth operation to cancel 292 */ 293 void 294 TALER_MERCHANT_post_templates_cancel ( 295 struct TALER_MERCHANT_PostTemplatesHandle *pth); 296 297 298 #endif /* _TALER_MERCHANT__POST_TEMPLATES_TEMPLATE_ID_H */