post-private-templates.h (7453B)
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-templates.h 19 * @brief C interface for the POST /private/templates endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_PRIVATE_TEMPLATES_H 23 #define _TALER_MERCHANT__POST_PRIVATE_TEMPLATES_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options for the POST /private/templates request. 30 */ 31 enum TALER_MERCHANT_PostPrivateTemplatesOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_POST_PRIVATE_TEMPLATES_OPTION_END = 0, 37 38 /** 39 * OTP device ID to associate with the template. 40 */ 41 TALER_MERCHANT_POST_PRIVATE_TEMPLATES_OPTION_OTP_ID, 42 43 /** 44 * Editable defaults (JSON object) for the template. 45 */ 46 TALER_MERCHANT_POST_PRIVATE_TEMPLATES_OPTION_EDITABLE_DEFAULTS 47 48 }; 49 50 51 /** 52 * Value for an option for the POST /private/templates request. 53 */ 54 struct TALER_MERCHANT_PostPrivateTemplatesOptionValue 55 { 56 57 /** 58 * Type of the option being set. 59 */ 60 enum TALER_MERCHANT_PostPrivateTemplatesOption option; 61 62 /** 63 * Specific option value. 64 */ 65 union 66 { 67 68 /** 69 * Value if @e option is 70 * #TALER_MERCHANT_POST_PRIVATE_TEMPLATES_OPTION_OTP_ID. 71 */ 72 const char *otp_id; 73 74 /** 75 * Value if @e option is 76 * #TALER_MERCHANT_POST_PRIVATE_TEMPLATES_OPTION_EDITABLE_DEFAULTS. 77 */ 78 const json_t *editable_defaults; 79 80 } details; 81 82 }; 83 84 85 /** 86 * Handle for a POST /private/templates request. 87 */ 88 struct TALER_MERCHANT_PostPrivateTemplatesHandle; 89 90 91 /** 92 * Response details for a POST /private/templates request. 93 */ 94 struct TALER_MERCHANT_PostPrivateTemplatesResponse 95 { 96 97 /** 98 * HTTP response details. 99 */ 100 struct TALER_MERCHANT_HttpResponse hr; 101 102 }; 103 104 105 /** 106 * Terminate the list of the options. 107 * 108 * @return the terminating object 109 */ 110 #define TALER_MERCHANT_post_private_templates_option_end_() \ 111 (const struct TALER_MERCHANT_PostPrivateTemplatesOptionValue) \ 112 { \ 113 .option = TALER_MERCHANT_POST_PRIVATE_TEMPLATES_OPTION_END \ 114 } 115 116 /** 117 * Set OTP device ID. 118 * 119 * @param o OTP device ID 120 * @return representation of the option 121 */ 122 #define TALER_MERCHANT_post_private_templates_option_otp_id(o) \ 123 (const struct TALER_MERCHANT_PostPrivateTemplatesOptionValue) \ 124 { \ 125 .option = TALER_MERCHANT_POST_PRIVATE_TEMPLATES_OPTION_OTP_ID, \ 126 .details.otp_id = (o) \ 127 } 128 129 130 /** 131 * Set editable defaults. 132 * 133 * @param ed editable defaults (JSON object) 134 * @return representation of the option 135 */ 136 #define TALER_MERCHANT_post_private_templates_option_editable_defaults(ed) \ 137 (const struct TALER_MERCHANT_PostPrivateTemplatesOptionValue) \ 138 { \ 139 .option = \ 140 TALER_MERCHANT_POST_PRIVATE_TEMPLATES_OPTION_EDITABLE_DEFAULTS, \ 141 .details.editable_defaults = (ed) \ 142 } 143 144 145 /** 146 * Set the requested options for the operation. 147 * 148 * @param ppth the request to set the options for 149 * @param num_options length of the @a options array 150 * @param options an array of options 151 * @return #GNUNET_OK on success, 152 * #GNUNET_NO on failure, 153 * #GNUNET_SYSERR on internal error 154 */ 155 enum GNUNET_GenericReturnValue 156 TALER_MERCHANT_post_private_templates_set_options_ ( 157 struct TALER_MERCHANT_PostPrivateTemplatesHandle *ppth, 158 unsigned int num_options, 159 const struct TALER_MERCHANT_PostPrivateTemplatesOptionValue *options); 160 161 162 /** 163 * Set the requested options for the operation. 164 * 165 * @param ppth the request to set the options for 166 * @param ... the list of the options 167 * @return #GNUNET_OK on success, 168 * #GNUNET_NO on failure, 169 * #GNUNET_SYSERR on internal error 170 */ 171 #define TALER_MERCHANT_post_private_templates_set_options(ppth,...) \ 172 TALER_MERCHANT_post_private_templates_set_options_ ( \ 173 ppth, \ 174 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 175 ((const struct TALER_MERCHANT_PostPrivateTemplatesOptionValue[]) \ 176 {__VA_ARGS__, TALER_MERCHANT_post_private_templates_option_end_ () } \ 177 )) 178 179 180 /** 181 * Set up POST /private/templates operation. 182 * Note that you must explicitly start the operation after 183 * possibly setting options. 184 * 185 * @param ctx the context 186 * @param url base URL of the merchant backend 187 * @param template_id identifier for the new template 188 * @param template_description human-readable description 189 * @param template_contract template contract (JSON) 190 * @return handle to operation 191 */ 192 struct TALER_MERCHANT_PostPrivateTemplatesHandle * 193 TALER_MERCHANT_post_private_templates_create ( 194 struct GNUNET_CURL_Context *ctx, 195 const char *url, 196 const char *template_id, 197 const char *template_description, 198 const json_t *template_contract); 199 200 201 #ifndef TALER_MERCHANT_POST_PRIVATE_TEMPLATES_RESULT_CLOSURE 202 /** 203 * Type of the closure used by 204 * the #TALER_MERCHANT_PostPrivateTemplatesCallback. 205 */ 206 #define TALER_MERCHANT_POST_PRIVATE_TEMPLATES_RESULT_CLOSURE void 207 #endif /* TALER_MERCHANT_POST_PRIVATE_TEMPLATES_RESULT_CLOSURE */ 208 209 /** 210 * Callback for a POST /private/templates request. 211 * 212 * @param cls closure 213 * @param ptr response details 214 */ 215 typedef void 216 (*TALER_MERCHANT_PostPrivateTemplatesCallback)( 217 TALER_MERCHANT_POST_PRIVATE_TEMPLATES_RESULT_CLOSURE *cls, 218 const struct TALER_MERCHANT_PostPrivateTemplatesResponse *ptr); 219 220 221 /** 222 * Start POST /private/templates operation. 223 * 224 * @param[in,out] ppth operation to start 225 * @param cb function to call with the merchant's result 226 * @param cb_cls closure for @a cb 227 * @return status code, #TALER_EC_NONE on success 228 */ 229 enum TALER_ErrorCode 230 TALER_MERCHANT_post_private_templates_start ( 231 struct TALER_MERCHANT_PostPrivateTemplatesHandle *ppth, 232 TALER_MERCHANT_PostPrivateTemplatesCallback cb, 233 TALER_MERCHANT_POST_PRIVATE_TEMPLATES_RESULT_CLOSURE *cb_cls); 234 235 236 /** 237 * Cancel POST /private/templates operation. This function must not be 238 * called by clients after the TALER_MERCHANT_PostPrivateTemplatesCallback 239 * has been invoked (as in those cases it'll be called internally by the 240 * implementation already). 241 * 242 * @param[in] ppth operation to cancel 243 */ 244 void 245 TALER_MERCHANT_post_private_templates_cancel ( 246 struct TALER_MERCHANT_PostPrivateTemplatesHandle *ppth); 247 248 249 #endif /* _TALER_MERCHANT__POST_PRIVATE_TEMPLATES_H */