/*
   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/delete-purses-PURSE_PUB.h
 * @brief C interface for DELETE /purses/$PURSE_PUB
 * @author Christian Grothoff
 */
#ifndef _TALER_EXCHANGE__DELETE_PURSES_PURSE_PUB_H
#define _TALER_EXCHANGE__DELETE_PURSES_PURSE_PUB_H

#include <taler/exchange/common.h>

/**
 * Handle for an operation to DELETE /purses/$PURSE_PUB.
 */
struct TALER_EXCHANGE_DeletePursesHandle;


/**
 * Set up DELETE /purses/$PURSE_PUB operation.
 * Note that you must explicitly start the operation after setup.
 *
 * Asks the exchange to delete a purse. Will only succeed if
 * the purse was not yet merged and did not yet time out.
 *
 * @param ctx CURL context
 * @param url exchange base URL
 * @param purse_priv private key of the purse
 * @return handle to operation, NULL upon error
 */
struct TALER_EXCHANGE_DeletePursesHandle *
TALER_EXCHANGE_delete_purses_create (
  struct GNUNET_CURL_Context *ctx,
  const char *url,
  const struct TALER_PurseContractPrivateKeyP *purse_priv);


/**
 * Response generated for a purse deletion request.
 */
struct TALER_EXCHANGE_DeletePursesResponse
{
  /**
   * Full HTTP response.
   */
  struct TALER_EXCHANGE_HttpResponse hr;
};


#ifndef TALER_EXCHANGE_DELETE_PURSES_RESULT_CLOSURE
/**
 * Type of the closure used by
 * the #TALER_EXCHANGE_DeletePursesCallback.
 */
#define TALER_EXCHANGE_DELETE_PURSES_RESULT_CLOSURE void
#endif /* TALER_EXCHANGE_DELETE_PURSES_RESULT_CLOSURE */

/**
 * Function called with information about the deletion
 * of a purse.
 *
 * @param cls closure
 * @param pdr HTTP response data
 */
typedef void
(*TALER_EXCHANGE_DeletePursesCallback) (
  TALER_EXCHANGE_DELETE_PURSES_RESULT_CLOSURE *cls,
  const struct TALER_EXCHANGE_DeletePursesResponse *pdr);


/**
 * Start DELETE /purses/$PURSE_PUB operation.
 *
 * @param[in,out] dph 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_delete_purses_start (
  struct TALER_EXCHANGE_DeletePursesHandle *dph,
  TALER_EXCHANGE_DeletePursesCallback cb,
  TALER_EXCHANGE_DELETE_PURSES_RESULT_CLOSURE *cb_cls);


/**
 * Cancel DELETE /purses/$PURSE_PUB operation.  This function must not be
 * called by clients after the TALER_EXCHANGE_DeletePursesCallback has been
 * invoked (as in those cases it'll be called internally by the
 * implementation already).
 *
 * @param[in] dph operation to cancel
 */
void
TALER_EXCHANGE_delete_purses_cancel (
  struct TALER_EXCHANGE_DeletePursesHandle *dph);

#endif
