patch-private-units-UNIT.h (12288B)
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-units-UNIT.h 19 * @brief C interface for PATCH /private/units/$UNIT 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__PATCH_PRIVATE_UNITS_UNIT_H 23 #define _TALER_MERCHANT__PATCH_PRIVATE_UNITS_UNIT_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the PATCH /private/units/$UNIT request. 30 */ 31 enum TALER_MERCHANT_PatchPrivateUnitOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_END = 0, 37 38 /** 39 * Set the long name of the unit. 40 */ 41 TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_NAME_LONG, 42 43 /** 44 * Set the short name (symbol) of the unit. 45 */ 46 TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_NAME_SHORT, 47 48 /** 49 * Set internationalized long names (JSON). 50 */ 51 TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_NAME_LONG_I18N, 52 53 /** 54 * Set internationalized short names (JSON). 55 */ 56 TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_NAME_SHORT_I18N, 57 58 /** 59 * Set whether fractional quantities are allowed. 60 */ 61 TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_ALLOW_FRACTION, 62 63 /** 64 * Set precision level for fractions. 65 */ 66 TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_PRECISION_LEVEL, 67 68 /** 69 * Set active status of the unit. 70 */ 71 TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_ACTIVE 72 73 }; 74 75 76 /** 77 * Value for an option for the PATCH /private/units/$UNIT request. 78 */ 79 struct TALER_MERCHANT_PatchPrivateUnitOptionValue 80 { 81 82 /** 83 * Type of the option being set. 84 */ 85 enum TALER_MERCHANT_PatchPrivateUnitOption option; 86 87 /** 88 * Specific option value. 89 */ 90 union 91 { 92 93 /** 94 * Value if @e option is 95 * #TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_NAME_LONG. 96 */ 97 const char *unit_name_long; 98 99 /** 100 * Value if @e option is 101 * #TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_NAME_SHORT. 102 */ 103 const char *unit_name_short; 104 105 /** 106 * Value if @e option is 107 * #TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_NAME_LONG_I18N. 108 */ 109 const json_t *unit_name_long_i18n; 110 111 /** 112 * Value if @e option is 113 * #TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_NAME_SHORT_I18N. 114 */ 115 const json_t *unit_name_short_i18n; 116 117 /** 118 * Value if @e option is 119 * #TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_ALLOW_FRACTION. 120 */ 121 bool unit_allow_fraction; 122 123 /** 124 * Value if @e option is 125 * #TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_PRECISION_LEVEL. 126 */ 127 uint32_t unit_precision_level; 128 129 /** 130 * Value if @e option is 131 * #TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_ACTIVE. 132 */ 133 bool unit_active; 134 135 } details; 136 137 }; 138 139 140 /** 141 * Handle for a PATCH /private/units/$UNIT operation. 142 */ 143 struct TALER_MERCHANT_PatchPrivateUnitHandle; 144 145 146 /** 147 * Set up PATCH /private/units/$UNIT operation. 148 * Note that you must explicitly start the operation after 149 * possibly setting options. 150 * 151 * @param ctx the context 152 * @param url base URL of the merchant backend 153 * @param unit_id identifier of the unit to update 154 * @return handle to operation, NULL on error 155 */ 156 struct TALER_MERCHANT_PatchPrivateUnitHandle * 157 TALER_MERCHANT_patch_private_unit_create ( 158 struct GNUNET_CURL_Context *ctx, 159 const char *url, 160 const char *unit_id); 161 162 163 /** 164 * Terminate the list of the options. 165 * 166 * @return the terminating object of struct TALER_MERCHANT_PatchPrivateUnitOptionValue 167 */ 168 #define TALER_MERCHANT_patch_private_unit_option_end_() \ 169 (const struct TALER_MERCHANT_PatchPrivateUnitOptionValue) \ 170 { \ 171 .option = TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_END \ 172 } 173 174 /** 175 * Set the long name of the unit. 176 * 177 * @param n long name to set 178 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateUnitOptionValue 179 */ 180 #define TALER_MERCHANT_patch_private_unit_option_unit_name_long(n) \ 181 (const struct TALER_MERCHANT_PatchPrivateUnitOptionValue) \ 182 { \ 183 .option = TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_NAME_LONG, \ 184 .details.unit_name_long = (n) \ 185 } 186 187 /** 188 * Set the short name (symbol) of the unit. 189 * 190 * @param n short name to set 191 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateUnitOptionValue 192 */ 193 #define TALER_MERCHANT_patch_private_unit_option_unit_name_short(n) \ 194 (const struct TALER_MERCHANT_PatchPrivateUnitOptionValue) \ 195 { \ 196 .option = TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_NAME_SHORT, \ 197 .details.unit_name_short = (n) \ 198 } 199 200 /** 201 * Set internationalized long names. 202 * 203 * @param j JSON object with internationalized long names 204 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateUnitOptionValue 205 */ 206 #define TALER_MERCHANT_patch_private_unit_option_unit_name_long_i18n(j) \ 207 (const struct TALER_MERCHANT_PatchPrivateUnitOptionValue) \ 208 { \ 209 .option = TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_NAME_LONG_I18N \ 210 , \ 211 .details.unit_name_long_i18n = (j) \ 212 } 213 214 /** 215 * Set internationalized short names. 216 * 217 * @param j JSON object with internationalized short names 218 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateUnitOptionValue 219 */ 220 #define TALER_MERCHANT_patch_private_unit_option_unit_name_short_i18n(j) \ 221 (const struct TALER_MERCHANT_PatchPrivateUnitOptionValue) \ 222 { \ 223 .option = \ 224 TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_NAME_SHORT_I18N, \ 225 .details.unit_name_short_i18n = (j) \ 226 } 227 228 /** 229 * Set whether fractional quantities are allowed. 230 * 231 * @param a true if fractional quantities are allowed 232 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateUnitOptionValue 233 */ 234 #define TALER_MERCHANT_patch_private_unit_option_unit_allow_fraction(a) \ 235 (const struct TALER_MERCHANT_PatchPrivateUnitOptionValue) \ 236 { \ 237 .option = TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_ALLOW_FRACTION \ 238 , \ 239 .details.unit_allow_fraction = (a) \ 240 } 241 242 /** 243 * Set precision level for fractions. 244 * 245 * @param p precision level value 246 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateUnitOptionValue 247 */ 248 #define TALER_MERCHANT_patch_private_unit_option_unit_precision_level(p) \ 249 (const struct TALER_MERCHANT_PatchPrivateUnitOptionValue) \ 250 { \ 251 .option = \ 252 TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_PRECISION_LEVEL, \ 253 .details.unit_precision_level = (p) \ 254 } 255 256 /** 257 * Set active status of the unit. 258 * 259 * @param a true if the unit should be active 260 * @return representation of the option as a struct TALER_MERCHANT_PatchPrivateUnitOptionValue 261 */ 262 #define TALER_MERCHANT_patch_private_unit_option_unit_active(a) \ 263 (const struct TALER_MERCHANT_PatchPrivateUnitOptionValue) \ 264 { \ 265 .option = TALER_MERCHANT_PATCH_PRIVATE_UNIT_OPTION_UNIT_ACTIVE, \ 266 .details.unit_active = (a) \ 267 } 268 269 270 /** 271 * Set the requested options for the operation. 272 * 273 * If any option fail other options may be or may be not applied. 274 * 275 * @param uph the request to set the options for 276 * @param num_options length of the @a options array 277 * @param options an array of options 278 * @return #GNUNET_OK on success, 279 * #GNUNET_NO on failure, 280 * #GNUNET_SYSERR on internal error 281 */ 282 enum GNUNET_GenericReturnValue 283 TALER_MERCHANT_patch_private_unit_set_options_ ( 284 struct TALER_MERCHANT_PatchPrivateUnitHandle *uph, 285 unsigned int num_options, 286 const struct TALER_MERCHANT_PatchPrivateUnitOptionValue *options); 287 288 289 /** 290 * Set the requested options for the operation. 291 * 292 * If any option fail other options may be or may be not applied. 293 * 294 * It should be used with helpers that create required options, for example: 295 * 296 * TALER_MERCHANT_patch_private_unit_set_options ( 297 * uph, 298 * TALER_MERCHANT_patch_private_unit_option_unit_name_long ("Kilogram"), 299 * TALER_MERCHANT_patch_private_unit_option_unit_active (true)); 300 * 301 * @param uph the request to set the options for 302 * @param ... the list of the options, each option must be created 303 * by helpers TALER_MERCHANT_patch_private_unit_option_NAME(VALUE) 304 * @return #GNUNET_OK on success, 305 * #GNUNET_NO on failure, 306 * #GNUNET_SYSERR on internal error 307 */ 308 #define TALER_MERCHANT_patch_private_unit_set_options(uph,...) \ 309 TALER_MERCHANT_patch_private_unit_set_options_ ( \ 310 uph, \ 311 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 312 ((const struct TALER_MERCHANT_PatchPrivateUnitOptionValue[]) \ 313 {__VA_ARGS__, TALER_MERCHANT_patch_private_unit_option_end_ () } \ 314 )) 315 316 317 /** 318 * Response details for a PATCH /private/units/$UNIT request. 319 */ 320 struct TALER_MERCHANT_PatchPrivateUnitResponse 321 { 322 /** 323 * HTTP response details. 324 */ 325 struct TALER_MERCHANT_HttpResponse hr; 326 }; 327 328 329 #ifndef TALER_MERCHANT_PATCH_PRIVATE_UNIT_RESULT_CLOSURE 330 /** 331 * Type of the closure used by 332 * the #TALER_MERCHANT_PatchPrivateUnitCallback. 333 */ 334 #define TALER_MERCHANT_PATCH_PRIVATE_UNIT_RESULT_CLOSURE void 335 #endif /* TALER_MERCHANT_PATCH_PRIVATE_UNIT_RESULT_CLOSURE */ 336 337 /** 338 * Callback for a PATCH /private/units/$UNIT request. 339 * 340 * @param cls closure 341 * @param result response details 342 */ 343 typedef void 344 (*TALER_MERCHANT_PatchPrivateUnitCallback)( 345 TALER_MERCHANT_PATCH_PRIVATE_UNIT_RESULT_CLOSURE *cls, 346 const struct TALER_MERCHANT_PatchPrivateUnitResponse *result); 347 348 349 /** 350 * Start PATCH /private/units/$UNIT operation. 351 * 352 * @param[in,out] uph operation to start 353 * @param cb function to call with the result 354 * @param cb_cls closure for @a cb 355 * @return status code, #TALER_EC_NONE on success 356 */ 357 enum TALER_ErrorCode 358 TALER_MERCHANT_patch_private_unit_start ( 359 struct TALER_MERCHANT_PatchPrivateUnitHandle *uph, 360 TALER_MERCHANT_PatchPrivateUnitCallback cb, 361 TALER_MERCHANT_PATCH_PRIVATE_UNIT_RESULT_CLOSURE *cb_cls); 362 363 364 /** 365 * Cancel PATCH /private/units/$UNIT operation. 366 * This function must not be called by clients after the 367 * callback has been invoked. 368 * 369 * @param[in] uph operation to cancel 370 */ 371 void 372 TALER_MERCHANT_patch_private_unit_cancel ( 373 struct TALER_MERCHANT_PatchPrivateUnitHandle *uph); 374 375 376 #endif /* _TALER_MERCHANT__PATCH_PRIVATE_UNITS_UNIT_H */