post-private-units.h (10025B)
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-units.h 19 * @brief C interface for the POST /private/units endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_PRIVATE_UNITS_H 23 #define _TALER_MERCHANT__POST_PRIVATE_UNITS_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options for the POST /private/units request. 30 */ 31 enum TALER_MERCHANT_PostPrivateUnitsOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_END = 0, 37 38 /** 39 * Internationalized long names (JSON). 40 */ 41 TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_NAME_LONG_I18N, 42 43 /** 44 * Internationalized short names (JSON). 45 */ 46 TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_NAME_SHORT_I18N, 47 48 /** 49 * Whether fractional quantities are allowed (bool). 50 * Default: false. 51 */ 52 TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_ALLOW_FRACTION, 53 54 /** 55 * Precision level for fractional quantities (uint32_t). 56 * Default: 0. 57 */ 58 TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_PRECISION_LEVEL, 59 60 /** 61 * Whether the unit is active (bool). 62 * Default: true. 63 */ 64 TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_ACTIVE 65 66 }; 67 68 69 /** 70 * Value for an option for the POST /private/units request. 71 */ 72 struct TALER_MERCHANT_PostPrivateUnitsOptionValue 73 { 74 75 /** 76 * Type of the option being set. 77 */ 78 enum TALER_MERCHANT_PostPrivateUnitsOption option; 79 80 /** 81 * Specific option value. 82 */ 83 union 84 { 85 86 /** 87 * Value if @e option is 88 * #TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_NAME_LONG_I18N. 89 */ 90 const json_t *unit_name_long_i18n; 91 92 /** 93 * Value if @e option is 94 * #TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_NAME_SHORT_I18N. 95 */ 96 const json_t *unit_name_short_i18n; 97 98 /** 99 * Value if @e option is 100 * #TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_ALLOW_FRACTION. 101 */ 102 bool unit_allow_fraction; 103 104 /** 105 * Value if @e option is 106 * #TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_PRECISION_LEVEL. 107 */ 108 uint32_t unit_precision_level; 109 110 /** 111 * Value if @e option is 112 * #TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_ACTIVE. 113 */ 114 bool unit_active; 115 116 } details; 117 118 }; 119 120 121 /** 122 * Handle for a POST /private/units request. 123 */ 124 struct TALER_MERCHANT_PostPrivateUnitsHandle; 125 126 127 /** 128 * Response details for a POST /private/units request. 129 */ 130 struct TALER_MERCHANT_PostPrivateUnitsResponse 131 { 132 133 /** 134 * HTTP response details. 135 */ 136 struct TALER_MERCHANT_HttpResponse hr; 137 138 }; 139 140 141 /** 142 * Terminate the list of the options. 143 * 144 * @return the terminating object 145 */ 146 #define TALER_MERCHANT_post_private_units_option_end_() \ 147 (const struct TALER_MERCHANT_PostPrivateUnitsOptionValue) \ 148 { \ 149 .option = TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_END \ 150 } 151 152 /** 153 * Set internationalized long names. 154 * 155 * @param j long names JSON object 156 * @return representation of the option 157 */ 158 #define TALER_MERCHANT_post_private_units_option_unit_name_long_i18n(j) \ 159 (const struct TALER_MERCHANT_PostPrivateUnitsOptionValue) \ 160 { \ 161 .option = TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_NAME_LONG_I18N \ 162 , \ 163 .details.unit_name_long_i18n = (j) \ 164 } 165 166 /** 167 * Set internationalized short names. 168 * 169 * @param j short names JSON object 170 * @return representation of the option 171 */ 172 #define TALER_MERCHANT_post_private_units_option_unit_name_short_i18n(j) \ 173 (const struct TALER_MERCHANT_PostPrivateUnitsOptionValue) \ 174 { \ 175 .option = \ 176 TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_NAME_SHORT_I18N, \ 177 .details.unit_name_short_i18n = (j) \ 178 } 179 180 181 /** 182 * Set whether fractional quantities are allowed. 183 * 184 * @param v true to allow fractions 185 * @return representation of the option 186 */ 187 #define TALER_MERCHANT_post_private_units_option_unit_allow_fraction(v) \ 188 (const struct TALER_MERCHANT_PostPrivateUnitsOptionValue) \ 189 { \ 190 .option = \ 191 TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_ALLOW_FRACTION, \ 192 .details.unit_allow_fraction = (v) \ 193 } 194 195 /** 196 * Set the precision level for fractional quantities. 197 * 198 * @param v precision level 199 * @return representation of the option 200 */ 201 #define TALER_MERCHANT_post_private_units_option_unit_precision_level(v) \ 202 (const struct TALER_MERCHANT_PostPrivateUnitsOptionValue) \ 203 { \ 204 .option = \ 205 TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_PRECISION_LEVEL, \ 206 .details.unit_precision_level = (v) \ 207 } 208 209 /** 210 * Set whether the unit is active. 211 * 212 * @param v true if active 213 * @return representation of the option 214 */ 215 #define TALER_MERCHANT_post_private_units_option_unit_active(v) \ 216 (const struct TALER_MERCHANT_PostPrivateUnitsOptionValue) \ 217 { \ 218 .option = \ 219 TALER_MERCHANT_POST_PRIVATE_UNITS_OPTION_UNIT_ACTIVE, \ 220 .details.unit_active = (v) \ 221 } 222 223 224 /** 225 * Set the requested options for the operation. 226 * 227 * @param ppuh the request to set the options for 228 * @param num_options length of the @a options array 229 * @param options an array of options 230 * @return #GNUNET_OK on success, 231 * #GNUNET_NO on failure, 232 * #GNUNET_SYSERR on internal error 233 */ 234 enum GNUNET_GenericReturnValue 235 TALER_MERCHANT_post_private_units_set_options_ ( 236 struct TALER_MERCHANT_PostPrivateUnitsHandle *ppuh, 237 unsigned int num_options, 238 const struct TALER_MERCHANT_PostPrivateUnitsOptionValue *options); 239 240 241 /** 242 * Set the requested options for the operation. 243 * 244 * @param ppuh the request to set the options for 245 * @param ... the list of the options 246 * @return #GNUNET_OK on success, 247 * #GNUNET_NO on failure, 248 * #GNUNET_SYSERR on internal error 249 */ 250 #define TALER_MERCHANT_post_private_units_set_options(ppuh,...) \ 251 TALER_MERCHANT_post_private_units_set_options_ ( \ 252 ppuh, \ 253 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 254 ((const struct TALER_MERCHANT_PostPrivateUnitsOptionValue[]) \ 255 {__VA_ARGS__, TALER_MERCHANT_post_private_units_option_end_ () } \ 256 )) 257 258 259 /** 260 * Set up POST /private/units operation. 261 * Note that you must explicitly start the operation after 262 * possibly setting options. 263 * 264 * @param ctx the context 265 * @param url base URL of the merchant backend 266 * @param unit_id identifier for the new unit 267 * @param unit_name_long long human-readable name 268 * @param unit_name_short short symbol for the unit 269 * @return handle to operation 270 */ 271 struct TALER_MERCHANT_PostPrivateUnitsHandle * 272 TALER_MERCHANT_post_private_units_create ( 273 struct GNUNET_CURL_Context *ctx, 274 const char *url, 275 const char *unit_id, 276 const char *unit_name_long, 277 const char *unit_name_short); 278 279 280 #ifndef TALER_MERCHANT_POST_PRIVATE_UNITS_RESULT_CLOSURE 281 /** 282 * Type of the closure used by 283 * the #TALER_MERCHANT_PostPrivateUnitsCallback. 284 */ 285 #define TALER_MERCHANT_POST_PRIVATE_UNITS_RESULT_CLOSURE void 286 #endif /* TALER_MERCHANT_POST_PRIVATE_UNITS_RESULT_CLOSURE */ 287 288 /** 289 * Callback for a POST /private/units request. 290 * 291 * @param cls closure 292 * @param pur response details 293 */ 294 typedef void 295 (*TALER_MERCHANT_PostPrivateUnitsCallback)( 296 TALER_MERCHANT_POST_PRIVATE_UNITS_RESULT_CLOSURE *cls, 297 const struct TALER_MERCHANT_PostPrivateUnitsResponse *pur); 298 299 300 /** 301 * Start POST /private/units operation. 302 * 303 * @param[in,out] ppuh operation to start 304 * @param cb function to call with the merchant's result 305 * @param cb_cls closure for @a cb 306 * @return status code, #TALER_EC_NONE on success 307 */ 308 enum TALER_ErrorCode 309 TALER_MERCHANT_post_private_units_start ( 310 struct TALER_MERCHANT_PostPrivateUnitsHandle *ppuh, 311 TALER_MERCHANT_PostPrivateUnitsCallback cb, 312 TALER_MERCHANT_POST_PRIVATE_UNITS_RESULT_CLOSURE *cb_cls); 313 314 315 /** 316 * Cancel POST /private/units operation. This function must not be 317 * called by clients after the TALER_MERCHANT_PostPrivateUnitsCallback 318 * has been invoked (as in those cases it'll be called internally by the 319 * implementation already). 320 * 321 * @param[in] ppuh operation to cancel 322 */ 323 void 324 TALER_MERCHANT_post_private_units_cancel ( 325 struct TALER_MERCHANT_PostPrivateUnitsHandle *ppuh); 326 327 328 #endif /* _TALER_MERCHANT__POST_PRIVATE_UNITS_H */