/*
  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 Affero General Public License as published by the Free Software
  Foundation; either version 3, 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 Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 */
/**
 * @file include/taler/exchange/post-blinding-prepare.h
 * @brief C interface for POST /blinding-prepare
 * @author Christian Grothoff
 */
#ifndef _TALER_EXCHANGE__POST_BLINDING_PREPARE_H
#define _TALER_EXCHANGE__POST_BLINDING_PREPARE_H

#include <taler/exchange/common.h>

/**
 * Handle for an operation to POST /blinding-prepare.
 */
struct TALER_EXCHANGE_PostBlindingPrepareHandle;


/**
 * Set up POST /blinding-prepare operation.
 * Note that you must explicitly start the operation after setup.
 *
 * This API is typically used by a wallet in preparation for a withdraw or
 * melt of coins that require additional input from the exchange for blinding,
 * such as for Clause-Schnorr signatures.
 *
 * @param curl_ctx The curl context
 * @param exchange_url The base url of the exchange
 * @param seed The blinding master seed for the batch
 * @param for_melt True if this preparation is for melting/refresh;
 *        for withdraw otherwise
 * @param num Number of elements in @e nonce_keys
 * @param nonce_keys Array of @e num denomination information and indices of
 *        the coins as they will appear in the subsequent operation
 * @return handle to operation, NULL if an argument was invalid
 */
struct TALER_EXCHANGE_PostBlindingPrepareHandle *
TALER_EXCHANGE_post_blinding_prepare_create (
  struct GNUNET_CURL_Context *curl_ctx,
  const char *exchange_url,
  const struct TALER_BlindingMasterSeedP *seed,
  bool for_melt,
  size_t num,
  const struct TALER_EXCHANGE_NonceKey nonce_keys[static num]);


/**
 * Set up POST /blinding-prepare operation in preparation of a /withdraw.
 *
 * @param curl_ctx The curl context
 * @param exchange_url The base url of the exchange
 * @param seed The blinding master seed for the batch
 * @param num Number of elements in @e nonce_keys
 * @param nonce_keys Array of @e num denomination information and indices
 * @return handle to operation, NULL if an argument was invalid
 */
#define TALER_EXCHANGE_post_blinding_prepare_for_withdraw_create( \
          curl_ctx, \
          exchange_url, \
          seed, \
          num, \
          nonce_keys) TALER_EXCHANGE_post_blinding_prepare_create ( \
          (curl_ctx), \
          (exchange_url), \
          (seed), \
          false, \
          (num), \
          (nonce_keys))

/**
 * Set up POST /blinding-prepare operation in preparation of a /melt.
 *
 * @param curl_ctx The curl context
 * @param exchange_url The base url of the exchange
 * @param seed The blinding master seed for the batch
 * @param num Number of elements in @e nonce_keys
 * @param nonce_keys Array of @e num denomination information and indices
 * @return handle to operation, NULL if an argument was invalid
 */
#define TALER_EXCHANGE_post_blinding_prepare_for_melt_create( \
          curl_ctx, \
          exchange_url, \
          seed, \
          num, \
          nonce_keys) TALER_EXCHANGE_post_blinding_prepare_create ( \
          (curl_ctx), \
          (exchange_url), \
          (seed), \
          true, \
          (num), \
          (nonce_keys))


/**
 * Response from the exchange for a POST /blinding-prepare request.
 */
struct TALER_EXCHANGE_PostBlindingPrepareResponse
{
  /**
   * The HTTP Response object
   */
  struct TALER_EXCHANGE_HttpResponse hr;

  /**
   * Details of the response, depending on the http status
   */
  union
  {
    /**
     * Details if the status is #MHD_HTTP_OK.
     */
    struct
    {
      /**
       * Number of entries in @e blinding_values, etc.
       */
      size_t num_blinding_values;

      /**
       * Array @a num withdraw values form the exchange.
       */
      const struct TALER_ExchangeBlindingValues *blinding_values;

    } ok;

    struct
    {
      /* TODO: maybe add details for status #MHD_HTTP_GONE */
    } gone;
  } details;
};


#ifndef TALER_EXCHANGE_POST_BLINDING_PREPARE_RESULT_CLOSURE
/**
 * Type of the closure used by
 * the #TALER_EXCHANGE_PostBlindingPrepareCallback.
 */
#define TALER_EXCHANGE_POST_BLINDING_PREPARE_RESULT_CLOSURE void
#endif /* TALER_EXCHANGE_POST_BLINDING_PREPARE_RESULT_CLOSURE */

/**
 * Type of the function that receives the result of a
 * POST /blinding-prepare request.
 *
 * @param cls closure
 * @param result result returned by the HTTP server
 */
typedef void
(*TALER_EXCHANGE_PostBlindingPrepareCallback)(
  TALER_EXCHANGE_POST_BLINDING_PREPARE_RESULT_CLOSURE *cls,
  const struct TALER_EXCHANGE_PostBlindingPrepareResponse *result);


/**
 * Start POST /blinding-prepare operation.
 *
 * @param[in,out] pbph operation to start
 * @param cb function to call with the exchange's result
 * @param cb_cls closure for @a cb
 * @return status code, #TALER_EC_NONE on success
 */
enum TALER_ErrorCode
TALER_EXCHANGE_post_blinding_prepare_start (
  struct TALER_EXCHANGE_PostBlindingPrepareHandle *pbph,
  TALER_EXCHANGE_PostBlindingPrepareCallback cb,
  TALER_EXCHANGE_POST_BLINDING_PREPARE_RESULT_CLOSURE *cb_cls);


/**
 * Cancel POST /blinding-prepare operation.  This function must not be called
 * by clients after the TALER_EXCHANGE_PostBlindingPrepareCallback has been
 * invoked (as in those cases it'll be called internally by the implementation
 * already).
 *
 * @param[in] pbph operation to cancel
 */
void
TALER_EXCHANGE_post_blinding_prepare_cancel (
  struct TALER_EXCHANGE_PostBlindingPrepareHandle *pbph);


#endif /* _TALER_EXCHANGE__POST_BLINDING_PREPARE_H */
