patch-private-webhooks-WEBHOOK_ID.h (8172B)
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-webhooks-WEBHOOK_ID.h 19 * @brief C interface for PATCH /private/webhooks/$WEBHOOK_ID 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__PATCH_PRIVATE_WEBHOOKS_WEBHOOK_ID_H 23 #define _TALER_MERCHANT__PATCH_PRIVATE_WEBHOOKS_WEBHOOK_ID_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the PATCH /private/webhooks/$WEBHOOK_ID request. 30 */ 31 enum TALER_MERCHANT_PatchPrivateWebhookOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_OPTION_END = 0, 37 38 /** 39 * Set the header template. 40 */ 41 TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_OPTION_HEADER_TEMPLATE, 42 43 /** 44 * Set the body template. 45 */ 46 TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_OPTION_BODY_TEMPLATE 47 48 }; 49 50 51 /** 52 * Value for an option for the PATCH /private/webhooks/$WEBHOOK_ID request. 53 */ 54 struct TALER_MERCHANT_PatchPrivateWebhookOptionValue 55 { 56 57 /** 58 * Type of the option being set. 59 */ 60 enum TALER_MERCHANT_PatchPrivateWebhookOption option; 61 62 /** 63 * Specific option value. 64 */ 65 union 66 { 67 68 /** 69 * Value if @e option is 70 * #TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_OPTION_HEADER_TEMPLATE. 71 */ 72 const char *header_template; 73 74 /** 75 * Value if @e option is 76 * #TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_OPTION_BODY_TEMPLATE. 77 */ 78 const char *body_template; 79 80 } details; 81 82 }; 83 84 85 /** 86 * Handle for a PATCH /private/webhooks/$WEBHOOK_ID operation. 87 */ 88 struct TALER_MERCHANT_PatchPrivateWebhookHandle; 89 90 91 /** 92 * Set up PATCH /private/webhooks/$WEBHOOK_ID operation. 93 * Note that you must explicitly start the operation after 94 * possibly setting options. 95 * 96 * @param ctx the context 97 * @param url base URL of the merchant backend 98 * @param webhook_id identifier of the webhook to update 99 * @param event_type new event type 100 * @param url_template new notification URL template 101 * @param http_method new HTTP method 102 * @return handle to operation, NULL on error 103 */ 104 struct TALER_MERCHANT_PatchPrivateWebhookHandle * 105 TALER_MERCHANT_patch_private_webhook_create ( 106 struct GNUNET_CURL_Context *ctx, 107 const char *url, 108 const char *webhook_id, 109 const char *event_type, 110 const char *url_template, 111 const char *http_method); 112 113 114 /** 115 * Terminate the list of the options. 116 * 117 * @return the terminating object of struct TALER_MERCHANT_PatchPrivateWebhookOptionValue 118 */ 119 #define TALER_MERCHANT_patch_private_webhook_option_end_() \ 120 (const struct TALER_MERCHANT_PatchPrivateWebhookOptionValue) \ 121 { \ 122 .option = TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_OPTION_END \ 123 } 124 125 /** 126 * Set header template. 127 * 128 * @param ht header template string to set 129 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateWebhookOptionValue 130 */ 131 #define TALER_MERCHANT_patch_private_webhook_option_header_template(ht) \ 132 (const struct TALER_MERCHANT_PatchPrivateWebhookOptionValue) \ 133 { \ 134 .option = \ 135 TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_OPTION_HEADER_TEMPLATE, \ 136 .details.header_template = (ht) \ 137 } 138 139 /** 140 * Set body template. 141 * 142 * @param bt body template string to set 143 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateWebhookOptionValue 144 */ 145 #define TALER_MERCHANT_patch_private_webhook_option_body_template(bt) \ 146 (const struct TALER_MERCHANT_PatchPrivateWebhookOptionValue) \ 147 { \ 148 .option = \ 149 TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_OPTION_BODY_TEMPLATE, \ 150 .details.body_template = (bt) \ 151 } 152 153 154 /** 155 * Set the requested options for the operation. 156 * 157 * If any option fail other options may be or may be not applied. 158 * 159 * @param wph the request to set the options for 160 * @param num_options length of the @a options array 161 * @param options an array of options 162 * @return #GNUNET_OK on success, 163 * #GNUNET_NO on failure, 164 * #GNUNET_SYSERR on internal error 165 */ 166 enum GNUNET_GenericReturnValue 167 TALER_MERCHANT_patch_private_webhook_set_options_ ( 168 struct TALER_MERCHANT_PatchPrivateWebhookHandle *wph, 169 unsigned int num_options, 170 const struct TALER_MERCHANT_PatchPrivateWebhookOptionValue *options); 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 * It should be used with helpers that create required options, for example: 179 * 180 * TALER_MERCHANT_patch_private_webhook_set_options ( 181 * wph, 182 * TALER_MERCHANT_patch_private_webhook_option_header_template ( 183 * "Content-Type: application/json")); 184 * 185 * @param wph the request to set the options for 186 * @param ... the list of the options, each option must be created 187 * by helpers TALER_MERCHANT_patch_private_webhook_option_NAME(VALUE) 188 * @return #GNUNET_OK on success, 189 * #GNUNET_NO on failure, 190 * #GNUNET_SYSERR on internal error 191 */ 192 #define TALER_MERCHANT_patch_private_webhook_set_options(wph,...) \ 193 TALER_MERCHANT_patch_private_webhook_set_options_ ( \ 194 wph, \ 195 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 196 ((const struct TALER_MERCHANT_PatchPrivateWebhookOptionValue[]) \ 197 {__VA_ARGS__, TALER_MERCHANT_patch_private_webhook_option_end_ () } \ 198 )) 199 200 201 /** 202 * Response details for a PATCH /private/webhooks/$WEBHOOK_ID request. 203 */ 204 struct TALER_MERCHANT_PatchPrivateWebhookResponse 205 { 206 /** 207 * HTTP response details. 208 */ 209 struct TALER_MERCHANT_HttpResponse hr; 210 }; 211 212 213 #ifndef TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_RESULT_CLOSURE 214 /** 215 * Type of the closure used by 216 * the #TALER_MERCHANT_PatchPrivateWebhookCallback. 217 */ 218 #define TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_RESULT_CLOSURE void 219 #endif /* TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_RESULT_CLOSURE */ 220 221 /** 222 * Callback for a PATCH /private/webhooks/$WEBHOOK_ID request. 223 * 224 * @param cls closure 225 * @param result response details 226 */ 227 typedef void 228 (*TALER_MERCHANT_PatchPrivateWebhookCallback)( 229 TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_RESULT_CLOSURE *cls, 230 const struct TALER_MERCHANT_PatchPrivateWebhookResponse *result); 231 232 233 /** 234 * Start PATCH /private/webhooks/$WEBHOOK_ID operation. 235 * 236 * @param[in,out] handle operation to start 237 * @param cb function to call with the result 238 * @param cb_cls closure for @a cb 239 * @return status code, #TALER_EC_NONE on success 240 */ 241 enum TALER_ErrorCode 242 TALER_MERCHANT_patch_private_webhook_start ( 243 struct TALER_MERCHANT_PatchPrivateWebhookHandle *handle, 244 TALER_MERCHANT_PatchPrivateWebhookCallback cb, 245 TALER_MERCHANT_PATCH_PRIVATE_WEBHOOK_RESULT_CLOSURE *cb_cls); 246 247 248 /** 249 * Cancel PATCH /private/webhooks/$WEBHOOK_ID operation. 250 * This function must not be called by clients after the 251 * callback has been invoked. 252 * 253 * @param[in] handle operation to cancel 254 */ 255 void 256 TALER_MERCHANT_patch_private_webhook_cancel ( 257 struct TALER_MERCHANT_PatchPrivateWebhookHandle *handle); 258 259 260 #endif /* _TALER_MERCHANT__PATCH_PRIVATE_WEBHOOKS_WEBHOOK_ID_H */