post-private-tokenfamilies.h (8191B)
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-tokenfamilies.h 19 * @brief C interface for the POST /private/tokenfamilies endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_PRIVATE_TOKENFAMILIES_H 23 #define _TALER_MERCHANT__POST_PRIVATE_TOKENFAMILIES_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options for the POST /private/tokenfamilies request. 30 */ 31 enum TALER_MERCHANT_PostPrivateTokenfamiliesOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_OPTION_END = 0, 37 38 /** 39 * Internationalized descriptions (JSON). 40 */ 41 TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_OPTION_DESCRIPTION_I18N, 42 43 /** 44 * Extra data (JSON). 45 */ 46 TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_OPTION_EXTRA_DATA 47 48 }; 49 50 51 /** 52 * Value for an option for the POST /private/tokenfamilies request. 53 */ 54 struct TALER_MERCHANT_PostPrivateTokenfamiliesOptionValue 55 { 56 57 /** 58 * Type of the option being set. 59 */ 60 enum TALER_MERCHANT_PostPrivateTokenfamiliesOption option; 61 62 /** 63 * Specific option value. 64 */ 65 union 66 { 67 68 /** 69 * Value if @e option is 70 * #TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_OPTION_DESCRIPTION_I18N. 71 */ 72 const json_t *description_i18n; 73 74 /** 75 * Value if @e option is 76 * #TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_OPTION_EXTRA_DATA. 77 */ 78 const json_t *extra_data; 79 80 } details; 81 82 }; 83 84 85 /** 86 * Handle for a POST /private/tokenfamilies request. 87 */ 88 struct TALER_MERCHANT_PostPrivateTokenfamiliesHandle; 89 90 91 /** 92 * Response details for a POST /private/tokenfamilies request. 93 */ 94 struct TALER_MERCHANT_PostPrivateTokenfamiliesResponse 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_tokenfamilies_option_end_() \ 111 (const struct TALER_MERCHANT_PostPrivateTokenfamiliesOptionValue) \ 112 { \ 113 .option = TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_OPTION_END \ 114 } 115 116 /** 117 * Set internationalized descriptions. 118 * 119 * @param d descriptions JSON object 120 * @return representation of the option 121 */ 122 #define TALER_MERCHANT_post_private_tokenfamilies_option_description_i18n(d) \ 123 (const struct TALER_MERCHANT_PostPrivateTokenfamiliesOptionValue) \ 124 { \ 125 .option = \ 126 TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_OPTION_DESCRIPTION_I18N, \ 127 .details.description_i18n = (d) \ 128 } 129 130 /** 131 * Set extra data. 132 * 133 * @param e extra data JSON object 134 * @return representation of the option 135 */ 136 #define TALER_MERCHANT_post_private_tokenfamilies_option_extra_data(e) \ 137 (const struct TALER_MERCHANT_PostPrivateTokenfamiliesOptionValue) \ 138 { \ 139 .option = TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_OPTION_EXTRA_DATA, \ 140 .details.extra_data = (e) \ 141 } 142 143 144 /** 145 * Set the requested options for the operation. 146 * 147 * @param ptfh the request to set the options for 148 * @param num_options length of the @a options array 149 * @param options an array of options 150 * @return #GNUNET_OK on success, 151 * #GNUNET_NO on failure, 152 * #GNUNET_SYSERR on internal error 153 */ 154 enum GNUNET_GenericReturnValue 155 TALER_MERCHANT_post_private_tokenfamilies_set_options_ ( 156 struct TALER_MERCHANT_PostPrivateTokenfamiliesHandle *ptfh, 157 unsigned int num_options, 158 const struct TALER_MERCHANT_PostPrivateTokenfamiliesOptionValue *options); 159 160 161 /** 162 * Set the requested options for the operation. 163 * 164 * @param ptfh the request to set the options for 165 * @param ... the list of the options 166 * @return #GNUNET_OK on success, 167 * #GNUNET_NO on failure, 168 * #GNUNET_SYSERR on internal error 169 */ 170 #define TALER_MERCHANT_post_private_tokenfamilies_set_options(ptfh,...) \ 171 TALER_MERCHANT_post_private_tokenfamilies_set_options_ ( \ 172 ptfh, \ 173 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 174 ((const struct TALER_MERCHANT_PostPrivateTokenfamiliesOptionValue[]) \ 175 {__VA_ARGS__, TALER_MERCHANT_post_private_tokenfamilies_option_end_ \ 176 () } \ 177 )) 178 179 180 /** 181 * Set up POST /private/tokenfamilies 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 slug URL-safe slug identifier for the new token family 188 * @param name human-readable name 189 * @param description human-readable description 190 * @param valid_after start of validity period 191 * @param valid_before end of validity period 192 * @param duration duration of individual token validity 193 * @param validity_granularity granularity for validity alignment 194 * @param start_offset offset from purchase to start of validity 195 * @param kind kind of token family ("subscription" or "discount") 196 * @return handle to operation 197 */ 198 struct TALER_MERCHANT_PostPrivateTokenfamiliesHandle * 199 TALER_MERCHANT_post_private_tokenfamilies_create ( 200 struct GNUNET_CURL_Context *ctx, 201 const char *url, 202 const char *slug, 203 const char *name, 204 const char *description, 205 struct GNUNET_TIME_Timestamp valid_after, 206 struct GNUNET_TIME_Timestamp valid_before, 207 struct GNUNET_TIME_Relative duration, 208 struct GNUNET_TIME_Relative validity_granularity, 209 struct GNUNET_TIME_Relative start_offset, 210 const char *kind); 211 212 213 #ifndef TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_RESULT_CLOSURE 214 /** 215 * Type of the closure used by 216 * the #TALER_MERCHANT_PostPrivateTokenfamiliesCallback. 217 */ 218 #define TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_RESULT_CLOSURE void 219 #endif /* TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_RESULT_CLOSURE */ 220 221 /** 222 * Callback for a POST /private/tokenfamilies request. 223 * 224 * @param cls closure 225 * @param tfr response details 226 */ 227 typedef void 228 (*TALER_MERCHANT_PostPrivateTokenfamiliesCallback)( 229 TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_RESULT_CLOSURE *cls, 230 const struct TALER_MERCHANT_PostPrivateTokenfamiliesResponse *tfr); 231 232 233 /** 234 * Start POST /private/tokenfamilies operation. 235 * 236 * @param[in,out] ptfh operation to start 237 * @param cb function to call with the merchant's 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_post_private_tokenfamilies_start ( 243 struct TALER_MERCHANT_PostPrivateTokenfamiliesHandle *ptfh, 244 TALER_MERCHANT_PostPrivateTokenfamiliesCallback cb, 245 TALER_MERCHANT_POST_PRIVATE_TOKENFAMILIES_RESULT_CLOSURE *cb_cls); 246 247 248 /** 249 * Cancel POST /private/tokenfamilies operation. This function must not be 250 * called by clients after the 251 * TALER_MERCHANT_PostPrivateTokenfamiliesCallback has been invoked (as in 252 * those cases it'll be called internally by the implementation already). 253 * 254 * @param[in] ptfh operation to cancel 255 */ 256 void 257 TALER_MERCHANT_post_private_tokenfamilies_cancel ( 258 struct TALER_MERCHANT_PostPrivateTokenfamiliesHandle *ptfh); 259 260 261 #endif /* _TALER_MERCHANT__POST_PRIVATE_TOKENFAMILIES_H */