merchant

get-private-products-PRODUCT_ID.h (6117B)

---

 /*
   This file is part of TALER
   Copyright (C) 2014-2026 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Lesser General Public License as published by the Free Software
   Foundation; either version 2.1, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
 
   You should have received a copy of the GNU Lesser General Public License along with
   TALER; see the file COPYING.LGPL.  If not, see
   <http://www.gnu.org/licenses/>
 */
 /**
  * @file include/taler/taler-merchant/get-private-products-PRODUCT_ID.h
  * @brief C interface for GET /private/products/$PRODUCT_ID of the merchant backend
  * @author Christian Grothoff
  */
 #ifndef _TALER_MERCHANT__GET_PRIVATE_PRODUCTS_PRODUCT_ID_H
 #define _TALER_MERCHANT__GET_PRIVATE_PRODUCTS_PRODUCT_ID_H
 
 #include <taler/taler-merchant/common.h>
 
 
 /**
  * Handle for a GET /private/products/$PRODUCT_ID request.
  */
 struct TALER_MERCHANT_GetPrivateProductHandle;
 
 
 /**
  * Response details for a GET /private/products/$PRODUCT_ID request.
  */
 struct TALER_MERCHANT_GetPrivateProductResponse
 {
 
   /**
    * HTTP response details.
    */
   struct TALER_MERCHANT_HttpResponse hr;
 
   /**
    * Details depending on the HTTP status code.
    */
   union
   {
 
     /**
      * Details on #MHD_HTTP_OK.
      */
     struct
     {
 
       /**
        * Human-readable product name.
        */
       const char *product_name;
 
       /**
        * Human-readable product description.
        */
       const char *description;
 
       /**
        * Internationalized descriptions (JSON object), or NULL.
        */
       const json_t *description_i18n;
 
       /**
        * Unit of measurement for this product.
        */
       const char *unit;
 
       /**
        * Number of prices in @a unit_price.
        */
       size_t unit_price_len;
 
       /**
        * Array of unit prices (for different payment options).
        */
       const struct TALER_Amount *unit_price;
 
       /**
        * Single unit price (first element of @a unit_price, for backwards compatibility).
        */
       struct TALER_Amount price;
 
       /**
        * Base64-encoded product image, or empty string.
        */
       const char *image;
 
       /**
        * Tax information (JSON array), or NULL.
        */
       const json_t *taxes;
 
       /**
        * Total available stock (-1 for unlimited).
        */
       int64_t total_stock;
 
       /**
        * Total stock in fractional unit representation.
        * Stock level encoded as a decimal string. Preferred source of truth for fractional stock.
        */
       const char *unit_total_stock;
 
       /**
        * Whether fractional quantities are allowed.
        */
       bool unit_allow_fraction;
 
       /**
        * Precision level for fractional quantities.
        */
       uint32_t unit_precision_level;
 
       /**
        * Total number of units sold.
        */
       uint64_t total_sold;
 
       /**
        * Total number of units lost/expired.
        */
       uint64_t total_lost;
 
       /**
        * Storage location (JSON), or NULL.
        */
       const json_t *location;
 
       /**
        * Expected time of next restock (may be zero if unknown).
        */
       struct GNUNET_TIME_Timestamp next_restock;
 
       /**
        * Number of categories in @a categories.
        */
       unsigned int categories_len;
 
       /**
        * Array of category IDs this product belongs to.
        */
       const uint64_t *categories;
 
       /**
        * Product group ID (0 if not set).
        */
       uint64_t product_group_id;
 
       /**
        * Money pot ID (0 if not set).
        */
       uint64_t money_pot_id;
 
       /**
        * Whether the price is net (excluding taxes).
        */
       bool price_is_net;
 
       /**
        * Minimum age required to purchase this product (0 if not set).
        */
       uint16_t minimum_age;
 
     } ok;
 
   } details;
 
 };
 
 
 /**
  * Set up GET /private/products/$PRODUCT_ID operation.
  * Note that you must explicitly start the operation after
  * possibly setting options.
  *
  * @param ctx the context
  * @param url base URL of the merchant backend
  * @param product_id identifier of the product to retrieve
  * @return handle to operation
  */
 struct TALER_MERCHANT_GetPrivateProductHandle *
 TALER_MERCHANT_get_private_product_create (
   struct GNUNET_CURL_Context *ctx,
   const char *url,
   const char *product_id);
 
 
 #ifndef TALER_MERCHANT_GET_PRIVATE_PRODUCT_RESULT_CLOSURE
 /**
  * Type of the closure used by
  * the #TALER_MERCHANT_GetPrivateProductCallback.
  */
 #define TALER_MERCHANT_GET_PRIVATE_PRODUCT_RESULT_CLOSURE void
 #endif /* TALER_MERCHANT_GET_PRIVATE_PRODUCT_RESULT_CLOSURE */
 
 /**
  * Callback for a GET /private/products/$PRODUCT_ID request.
  *
  * @param cls closure
  * @param pgr response details
  */
 typedef void
 (*TALER_MERCHANT_GetPrivateProductCallback)(
   TALER_MERCHANT_GET_PRIVATE_PRODUCT_RESULT_CLOSURE *cls,
   const struct TALER_MERCHANT_GetPrivateProductResponse *pgr);
 
 
 /**
  * Start GET /private/products/$PRODUCT_ID operation.
  *
  * @param[in,out] gpp operation to start
  * @param cb function to call with the merchant's result
  * @param cb_cls closure for @a cb
  * @return status code, #TALER_EC_NONE on success
  */
 enum TALER_ErrorCode
 TALER_MERCHANT_get_private_product_start (
   struct TALER_MERCHANT_GetPrivateProductHandle *gpp,
   TALER_MERCHANT_GetPrivateProductCallback cb,
   TALER_MERCHANT_GET_PRIVATE_PRODUCT_RESULT_CLOSURE *cb_cls);
 
 
 /**
  * Cancel GET /private/products/$PRODUCT_ID operation.  This function
  * must not be called by clients after the
  * TALER_MERCHANT_GetPrivateProductCallback has been invoked
  * (as in those cases it'll be called internally by the
  * implementation already).
  *
  * @param[in] gpp operation to cancel
  */
 void
 TALER_MERCHANT_get_private_product_cancel (
   struct TALER_MERCHANT_GetPrivateProductHandle *gpp);
 
 
 #endif /* _TALER_MERCHANT__GET_PRIVATE_PRODUCTS_PRODUCT_ID_H */