get-private-products.h (12293B)
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/get-private-products.h 19 * @brief C interface for the GET /private/products endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__GET_PRIVATE_PRODUCTS_H 23 #define _TALER_MERCHANT__GET_PRIVATE_PRODUCTS_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the GET /private/products request. 30 */ 31 enum TALER_MERCHANT_GetPrivateProductsOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_END = 0, 37 38 /** 39 * Return at most N values. Negative for descending by row ID, 40 * positive for ascending by row ID. Default is 20. 41 * @since protocol v12. 42 */ 43 TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_LIMIT, 44 45 /** 46 * Starting product_serial_id for pagination. 47 * @since protocol v12. 48 */ 49 TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_OFFSET, 50 51 /** 52 * Filter by category name (case-insensitive substring match). 53 * @since protocol v23. 54 */ 55 TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_CATEGORY_FILTER, 56 57 /** 58 * Filter by product name (case-insensitive substring match). 59 * @since protocol v23. 60 */ 61 TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_NAME_FILTER, 62 63 /** 64 * Filter by product description (case-insensitive substring match). 65 * @since protocol v23. 66 */ 67 TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_DESCRIPTION_FILTER, 68 69 /** 70 * Filter by product group serial. 71 * @since protocol v25. 72 */ 73 TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_PRODUCT_GROUP_SERIAL 74 75 }; 76 77 78 /** 79 * Value for an option for the GET /private/products request. 80 */ 81 struct TALER_MERCHANT_GetPrivateProductsOptionValue 82 { 83 84 /** 85 * Type of the option being set. 86 */ 87 enum TALER_MERCHANT_GetPrivateProductsOption option; 88 89 /** 90 * Specific option value. 91 */ 92 union 93 { 94 95 /** 96 * Value if @e option is 97 * #TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_LIMIT. 98 */ 99 int64_t limit; 100 101 /** 102 * Value if @e option is 103 * #TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_OFFSET. 104 */ 105 uint64_t offset; 106 107 /** 108 * Value if @e option is 109 * #TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_CATEGORY_FILTER. 110 */ 111 const char *category_filter; 112 113 /** 114 * Value if @e option is 115 * #TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_NAME_FILTER. 116 */ 117 const char *name_filter; 118 119 /** 120 * Value if @e option is 121 * #TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_DESCRIPTION_FILTER. 122 */ 123 const char *description_filter; 124 125 /** 126 * Value if @e option is 127 * #TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_PRODUCT_GROUP_SERIAL. 128 */ 129 uint64_t product_group_serial; 130 131 } details; 132 133 }; 134 135 136 /** 137 * Handle for a GET /private/products request. 138 */ 139 struct TALER_MERCHANT_GetPrivateProductsHandle; 140 141 142 /** 143 * Inventory entry for the GET /private/products response. 144 */ 145 struct TALER_MERCHANT_GetPrivateProductsInventoryEntry 146 { 147 148 /** 149 * Identifier of the product. 150 */ 151 const char *product_id; 152 153 /** 154 * Serial ID of the product. 155 */ 156 uint64_t product_serial; 157 158 }; 159 160 161 /** 162 * Response details for a GET /private/products request. 163 */ 164 struct TALER_MERCHANT_GetPrivateProductsResponse 165 { 166 167 /** 168 * HTTP response details. 169 */ 170 struct TALER_MERCHANT_HttpResponse hr; 171 172 /** 173 * Details depending on the HTTP status code. 174 */ 175 union 176 { 177 178 /** 179 * Details on #MHD_HTTP_OK. 180 */ 181 struct 182 { 183 184 /** 185 * Number of products in @a products. 186 */ 187 unsigned int products_length; 188 189 /** 190 * Array of product entries. 191 */ 192 const struct TALER_MERCHANT_GetPrivateProductsInventoryEntry *products; 193 194 } ok; 195 196 } details; 197 198 }; 199 200 201 /** 202 * Set up GET /private/products operation. 203 * Note that you must explicitly start the operation after 204 * possibly setting options. 205 * 206 * @param ctx the context 207 * @param url base URL of the merchant backend 208 * @return handle to operation 209 */ 210 struct TALER_MERCHANT_GetPrivateProductsHandle * 211 TALER_MERCHANT_get_private_products_create ( 212 struct GNUNET_CURL_Context *ctx, 213 const char *url); 214 215 216 /** 217 * Terminate the list of the options. 218 * 219 * @return the terminating object of struct TALER_MERCHANT_GetPrivateProductsOptionValue 220 */ 221 #define TALER_MERCHANT_get_private_products_option_end_() \ 222 (const struct TALER_MERCHANT_GetPrivateProductsOptionValue) \ 223 { \ 224 .option = TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_END \ 225 } 226 227 /** 228 * Set limit on the number of results to return. 229 * 230 * @param l limit on the number of results to return 231 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateProductsOptionValue 232 */ 233 #define TALER_MERCHANT_get_private_products_option_limit(l) \ 234 (const struct TALER_MERCHANT_GetPrivateProductsOptionValue) \ 235 { \ 236 .option = TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_LIMIT, \ 237 .details.limit = (l) \ 238 } 239 240 /** 241 * Set row offset from which to return results. 242 * 243 * @param o offset to use 244 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateProductsOptionValue 245 */ 246 #define TALER_MERCHANT_get_private_products_option_offset(o) \ 247 (const struct TALER_MERCHANT_GetPrivateProductsOptionValue) \ 248 { \ 249 .option = TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_OFFSET, \ 250 .details.offset = (o) \ 251 } 252 253 /** 254 * Set category name filter (case-insensitive substring match). 255 * 256 * @param f category filter string 257 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateProductsOptionValue 258 */ 259 #define TALER_MERCHANT_get_private_products_option_category_filter(f) \ 260 (const struct TALER_MERCHANT_GetPrivateProductsOptionValue) \ 261 { \ 262 .option = TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_CATEGORY_FILTER, \ 263 .details.category_filter = (f) \ 264 } 265 266 /** 267 * Set product name filter (case-insensitive substring match). 268 * 269 * @param f name filter string 270 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateProductsOptionValue 271 */ 272 #define TALER_MERCHANT_get_private_products_option_name_filter(f) \ 273 (const struct TALER_MERCHANT_GetPrivateProductsOptionValue) \ 274 { \ 275 .option = TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_NAME_FILTER, \ 276 .details.name_filter = (f) \ 277 } 278 279 /** 280 * Set product description filter (case-insensitive substring match). 281 * 282 * @param f description filter string 283 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateProductsOptionValue 284 */ 285 #define TALER_MERCHANT_get_private_products_option_description_filter(f) \ 286 (const struct TALER_MERCHANT_GetPrivateProductsOptionValue) \ 287 { \ 288 .option = TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_DESCRIPTION_FILTER, \ 289 .details.description_filter = (f) \ 290 } 291 292 /** 293 * Set product group serial filter. 294 * 295 * @param s product group serial to filter by 296 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateProductsOptionValue 297 */ 298 #define TALER_MERCHANT_get_private_products_option_product_group_serial(s) \ 299 (const struct TALER_MERCHANT_GetPrivateProductsOptionValue) \ 300 { \ 301 .option = TALER_MERCHANT_GET_PRIVATE_PRODUCTS_OPTION_PRODUCT_GROUP_SERIAL, \ 302 .details.product_group_serial = (s) \ 303 } 304 305 306 /** 307 * Set the requested options for the operation. 308 * 309 * If any option fail other options may be or may be not applied. 310 * 311 * @param gpph the request to set the options for 312 * @param num_options length of the @a options array 313 * @param options an array of options 314 * @return #GNUNET_OK on success, 315 * #GNUNET_NO on failure, 316 * #GNUNET_SYSERR on internal error 317 */ 318 enum GNUNET_GenericReturnValue 319 TALER_MERCHANT_get_private_products_set_options_ ( 320 struct TALER_MERCHANT_GetPrivateProductsHandle *gpph, 321 unsigned int num_options, 322 const struct TALER_MERCHANT_GetPrivateProductsOptionValue *options); 323 324 325 /** 326 * Set the requested options for the operation. 327 * 328 * If any option fail other options may be or may be not applied. 329 * 330 * It should be used with helpers that create required options, for example: 331 * 332 * TALER_MERCHANT_get_private_products_set_options ( 333 * gpph, 334 * TALER_MERCHANT_get_private_products_option_limit (20), 335 * TALER_MERCHANT_get_private_products_option_name_filter ("widget")); 336 * 337 * @param gpph the request to set the options for 338 * @param ... the list of the options, each option must be created 339 * by helpers TALER_MERCHANT_get_private_products_option_NAME(VALUE) 340 * @return #GNUNET_OK on success, 341 * #GNUNET_NO on failure, 342 * #GNUNET_SYSERR on internal error 343 */ 344 #define TALER_MERCHANT_get_private_products_set_options(gpph,...) \ 345 TALER_MERCHANT_get_private_products_set_options_ ( \ 346 gpph, \ 347 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 348 ((const struct TALER_MERCHANT_GetPrivateProductsOptionValue[]) \ 349 {__VA_ARGS__, TALER_MERCHANT_get_private_products_option_end_ () } \ 350 )) 351 352 353 #ifndef TALER_MERCHANT_GET_PRIVATE_PRODUCTS_RESULT_CLOSURE 354 /** 355 * Type of the closure used by 356 * the #TALER_MERCHANT_GetPrivateProductsCallback. 357 */ 358 #define TALER_MERCHANT_GET_PRIVATE_PRODUCTS_RESULT_CLOSURE void 359 #endif /* TALER_MERCHANT_GET_PRIVATE_PRODUCTS_RESULT_CLOSURE */ 360 361 /** 362 * Callback for a GET /private/products request. 363 * 364 * @param cls closure 365 * @param pgr response details 366 */ 367 typedef void 368 (*TALER_MERCHANT_GetPrivateProductsCallback)( 369 TALER_MERCHANT_GET_PRIVATE_PRODUCTS_RESULT_CLOSURE *cls, 370 const struct TALER_MERCHANT_GetPrivateProductsResponse *pgr); 371 372 373 /** 374 * Start GET /private/products operation. 375 * 376 * @param[in,out] gpph operation to start 377 * @param cb function to call with the merchant's result 378 * @param cb_cls closure for @a cb 379 * @return status code, #TALER_EC_NONE on success 380 */ 381 enum TALER_ErrorCode 382 TALER_MERCHANT_get_private_products_start ( 383 struct TALER_MERCHANT_GetPrivateProductsHandle *gpph, 384 TALER_MERCHANT_GetPrivateProductsCallback cb, 385 TALER_MERCHANT_GET_PRIVATE_PRODUCTS_RESULT_CLOSURE *cb_cls); 386 387 388 /** 389 * Cancel GET /private/products operation. This function must not be 390 * called by clients after the TALER_MERCHANT_GetPrivateProductsCallback 391 * has been invoked (as in those cases it'll be called internally by the 392 * implementation already). 393 * 394 * @param[in] gpph operation to cancel 395 */ 396 void 397 TALER_MERCHANT_get_private_products_cancel ( 398 struct TALER_MERCHANT_GetPrivateProductsHandle *gpph); 399 400 401 #endif /* _TALER_MERCHANT__GET_PRIVATE_PRODUCTS_H */