patch-private-templates-TEMPLATE_ID.h (6873B)
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 include/taler/taler-merchant/patch-private-templates-TEMPLATE_ID.h 19 * @brief C interface for PATCH /private/templates/$TEMPLATE_ID 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__PATCH_PRIVATE_TEMPLATES_TEMPLATE_ID_H 23 #define _TALER_MERCHANT__PATCH_PRIVATE_TEMPLATES_TEMPLATE_ID_H 24 25 #include <taler/taler-merchant/common.h> 26 27 28 /** 29 * Possible options for the PATCH /private/templates/$TEMPLATE_ID request. 30 */ 31 enum TALER_MERCHANT_PatchPrivateTemplateOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_PATCH_PRIVATE_TEMPLATE_OPTION_END = 0, 37 38 /** 39 * Editable defaults (JSON object) for the template. 40 */ 41 TALER_MERCHANT_PATCH_PRIVATE_TEMPLATE_OPTION_EDITABLE_DEFAULTS 42 43 }; 44 45 46 /** 47 * Value for an option for the PATCH /private/templates/$TEMPLATE_ID request. 48 */ 49 struct TALER_MERCHANT_PatchPrivateTemplateOptionValue 50 { 51 52 /** 53 * Type of the option being set. 54 */ 55 enum TALER_MERCHANT_PatchPrivateTemplateOption option; 56 57 /** 58 * Specific option value. 59 */ 60 union 61 { 62 63 /** 64 * Value if @e option is 65 * #TALER_MERCHANT_PATCH_PRIVATE_TEMPLATE_OPTION_EDITABLE_DEFAULTS. 66 */ 67 const json_t *editable_defaults; 68 69 } details; 70 71 }; 72 73 74 /** 75 * Handle for a PATCH /private/templates/$TEMPLATE_ID operation. 76 */ 77 struct TALER_MERCHANT_PatchPrivateTemplateHandle; 78 79 80 /** 81 * Set up PATCH /private/templates/$TEMPLATE_ID operation. 82 * Note that you must explicitly start the operation after 83 * possibly setting options. 84 * 85 * @param ctx the context 86 * @param url base URL of the merchant backend 87 * @param template_id identifier of the template to update 88 * @param template_description new human-readable description 89 * @param otp_id new OTP device ID, or NULL to remove association 90 * @param template_contract new template contract (JSON) 91 * @return handle to operation, NULL on error 92 */ 93 struct TALER_MERCHANT_PatchPrivateTemplateHandle * 94 TALER_MERCHANT_patch_private_template_create ( 95 struct GNUNET_CURL_Context *ctx, 96 const char *url, 97 const char *template_id, 98 const char *template_description, 99 const char *otp_id, 100 json_t *template_contract); 101 102 103 /** 104 * Terminate the list of the options. 105 * 106 * @return the terminating object 107 */ 108 #define TALER_MERCHANT_patch_private_template_option_end_() \ 109 (const struct TALER_MERCHANT_PatchPrivateTemplateOptionValue) \ 110 { \ 111 .option = TALER_MERCHANT_PATCH_PRIVATE_TEMPLATE_OPTION_END \ 112 } 113 114 /** 115 * Set editable defaults. 116 * 117 * @param ed editable defaults (JSON object) 118 * @return representation of the option 119 */ 120 #define TALER_MERCHANT_patch_private_template_option_editable_defaults(ed) \ 121 (const struct TALER_MERCHANT_PatchPrivateTemplateOptionValue) \ 122 { \ 123 .option = \ 124 TALER_MERCHANT_PATCH_PRIVATE_TEMPLATE_OPTION_EDITABLE_DEFAULTS, \ 125 .details.editable_defaults = (ed) \ 126 } 127 128 129 /** 130 * Set the requested options for the operation. 131 * 132 * @param tph the request to set the options for 133 * @param num_options length of the @a options array 134 * @param options an array of options 135 * @return #GNUNET_OK on success, 136 * #GNUNET_NO on failure, 137 * #GNUNET_SYSERR on internal error 138 */ 139 enum GNUNET_GenericReturnValue 140 TALER_MERCHANT_patch_private_template_set_options_ ( 141 struct TALER_MERCHANT_PatchPrivateTemplateHandle *tph, 142 unsigned int num_options, 143 const struct TALER_MERCHANT_PatchPrivateTemplateOptionValue *options); 144 145 146 /** 147 * Set the requested options for the operation. 148 * 149 * @param tph the request to set the options for 150 * @param ... the list of the options 151 * @return #GNUNET_OK on success, 152 * #GNUNET_NO on failure, 153 * #GNUNET_SYSERR on internal error 154 */ 155 #define TALER_MERCHANT_patch_private_template_set_options(tph,...) \ 156 TALER_MERCHANT_patch_private_template_set_options_ ( \ 157 tph, \ 158 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 159 ((const struct TALER_MERCHANT_PatchPrivateTemplateOptionValue[]) \ 160 {__VA_ARGS__, TALER_MERCHANT_patch_private_template_option_end_ () } \ 161 )) 162 163 164 /** 165 * Response details for a PATCH /private/templates/$TEMPLATE_ID request. 166 */ 167 struct TALER_MERCHANT_PatchPrivateTemplateResponse 168 { 169 /** 170 * HTTP response details. 171 */ 172 struct TALER_MERCHANT_HttpResponse hr; 173 }; 174 175 176 #ifndef TALER_MERCHANT_PATCH_PRIVATE_TEMPLATE_RESULT_CLOSURE 177 /** 178 * Type of the closure used by 179 * the #TALER_MERCHANT_PatchPrivateTemplateCallback. 180 */ 181 #define TALER_MERCHANT_PATCH_PRIVATE_TEMPLATE_RESULT_CLOSURE void 182 #endif /* TALER_MERCHANT_PATCH_PRIVATE_TEMPLATE_RESULT_CLOSURE */ 183 184 /** 185 * Callback for a PATCH /private/templates/$TEMPLATE_ID request. 186 * 187 * @param cls closure 188 * @param result response details 189 */ 190 typedef void 191 (*TALER_MERCHANT_PatchPrivateTemplateCallback)( 192 TALER_MERCHANT_PATCH_PRIVATE_TEMPLATE_RESULT_CLOSURE *cls, 193 const struct TALER_MERCHANT_PatchPrivateTemplateResponse *result); 194 195 196 /** 197 * Start PATCH /private/templates/$TEMPLATE_ID operation. 198 * 199 * @param[in,out] handle operation to start 200 * @param cb function to call with the 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_patch_private_template_start ( 206 struct TALER_MERCHANT_PatchPrivateTemplateHandle *handle, 207 TALER_MERCHANT_PatchPrivateTemplateCallback cb, 208 TALER_MERCHANT_PATCH_PRIVATE_TEMPLATE_RESULT_CLOSURE *cb_cls); 209 210 211 /** 212 * Cancel PATCH /private/templates/$TEMPLATE_ID operation. 213 * This function must not be called by clients after the 214 * callback has been invoked. 215 * 216 * @param[in] handle operation to cancel 217 */ 218 void 219 TALER_MERCHANT_patch_private_template_cancel ( 220 struct TALER_MERCHANT_PatchPrivateTemplateHandle *handle); 221 222 223 #endif /* _TALER_MERCHANT__PATCH_PRIVATE_TEMPLATES_TEMPLATE_ID_H */