/*
  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-melt.h
 * @brief C interface for POST /melt
 * @author Christian Grothoff
 */
#ifndef _TALER_EXCHANGE__POST_MELT_H
#define _TALER_EXCHANGE__POST_MELT_H

#include <taler/exchange/common.h>

/**
 * Handle for an operation to POST /melt.
 */
struct TALER_EXCHANGE_PostMeltHandle;


/**
 * Set up POST /melt operation.
 * Note that you must explicitly start the operation after setup.
 *
 * This API is typically used by a wallet.  Note that to ensure that
 * no money is lost in case of hardware failures, the provided
 * argument @a melt_input should be committed to persistent storage
 * prior to calling this function.
 *
 * @param ctx curl context
 * @param url exchange base URL
 * @param keys exchange keys
 * @param rms the fresh seed that defines the refresh operation
 * @param melt_input the refresh data specifying the characteristics of the operation
 * @return handle to operation, NULL on error
 */
struct TALER_EXCHANGE_PostMeltHandle *
TALER_EXCHANGE_post_melt_create (
  struct GNUNET_CURL_Context *ctx,
  const char *url,
  struct TALER_EXCHANGE_Keys *keys,
  const struct TALER_PublicRefreshMasterSeedP *rms,
  const struct TALER_EXCHANGE_MeltInput *melt_input);


/**
 * Response returned to a POST /melt request.
 */
struct TALER_EXCHANGE_PostMeltResponse
{
  /**
   * Full HTTP response details.
   */
  struct TALER_EXCHANGE_HttpResponse hr;

  /**
   * Parsed response details, variant depending on the
   * @e hr.http_status.
   */
  union
  {
    /**
     * Results for status #MHD_HTTP_OK.
     */
    struct
    {
      /**
       * Length of the @a melt_blinding_values array with the exchange values
       * and blinding keys we are using.
       */
      unsigned int num_melt_blinding_values;

      /**
       * Information returned per coin.
       */
      const struct TALER_ExchangeBlindingValues *melt_blinding_values;

      /**
       * The blinding seed that was used to get the blinding values.
       * Might be NULL.  This is a value computed by the client
       * library and not actually part of the response of the
       * server. It is returned here for convenience.
       */
      const struct TALER_BlindingMasterSeedP *blinding_seed;

      /**
       * Key used by the exchange to sign the response.
       */
      struct TALER_ExchangePublicKeyP sign_key;

      /**
       * Gamma value chosen by the exchange.
       */
      uint32_t noreveal_index;
    } ok;

  } details;
};


#ifndef TALER_EXCHANGE_POST_MELT_RESULT_CLOSURE
/**
 * Type of the closure used by
 * the #TALER_EXCHANGE_PostMeltCallback.
 */
#define TALER_EXCHANGE_POST_MELT_RESULT_CLOSURE void
#endif /* TALER_EXCHANGE_POST_MELT_RESULT_CLOSURE */

/**
 * Type of the function that receives the result of a
 * POST /melt request.
 *
 * If successful, the @a noreveal_index in the result should be committed
 * to disk prior to proceeding TALER_EXCHANGE_reveal_melt().
 *
 * @param cls closure
 * @param result result returned by the HTTP server
 */
typedef void
(*TALER_EXCHANGE_PostMeltCallback)(
  TALER_EXCHANGE_POST_MELT_RESULT_CLOSURE *cls,
  const struct TALER_EXCHANGE_PostMeltResponse *result);


/**
 * Start POST /melt operation.
 *
 * @param[in,out] pmh 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_melt_start (
  struct TALER_EXCHANGE_PostMeltHandle *pmh,
  TALER_EXCHANGE_PostMeltCallback cb,
  TALER_EXCHANGE_POST_MELT_RESULT_CLOSURE *cb_cls);


/**
 * Cancel POST /melt operation.  This function must not be called by clients
 * after the TALER_EXCHANGE_PostMeltCallback has been invoked (as in those
 * cases it'll be called internally by the implementation already).
 *
 * @param[in] pmh operation to cancel
 */
void
TALER_EXCHANGE_post_melt_cancel (
  struct TALER_EXCHANGE_PostMeltHandle *pmh);


#endif /* _TALER_EXCHANGE__POST_MELT_H */
