/*
   This file is part of TALER
   Copyright (C) 2022 Taler Systems SA

   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU 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 General Public License for more details.

   You should have received a copy of the GNU General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 */
/**
 * @file src/include/exchange-database/get_ready_deposit.h
 * @brief implementation of the get_ready_deposit function for Postgres
 * @author Christian Grothoff
 */
#ifndef EXCHANGE_DATABASE_GET_READY_DEPOSIT_H
#define EXCHANGE_DATABASE_GET_READY_DEPOSIT_H

#include "taler/taler_util.h"
#include "taler/taler_json_lib.h"
#include "exchangedb_lib.h"


/**
 * Obtain information about deposits that are ready to be executed.  Such
 * deposits must not be marked as "done" or policy-blocked, their wire
 * deadline must have passed, and their refund deadline must have passed
 * the current aggregation shift boundary.
 *
 * The last condition is what makes the result *actionable*: it is the
 * same cut-off that TALER_EXCHANGEDB_do_aggregate() applies when marking
 * deposits as done.  Without it this function reports deposits that the
 * aggregator then cannot make progress on, which makes it spin (and
 * `taler-exchange-aggregator -t` never reach an idle shard, hence never
 * terminate).  Note that a deposit is therefore not necessarily ready
 * the instant its wire deadline passes; it becomes ready at the next
 * shift boundary, which is precisely what AGGREGATOR_SHIFT asks for.
 *
 * @param pg the database context
 * @param start_shard_row minimum shard row to select
 * @param end_shard_row maximum shard row to select (inclusive)
 * @param[out] merchant_pub set to the public key of a merchant with a ready deposit
 * @param[out] payto_uri set to the account of the merchant, to be freed by caller
 * @param[out] extra_wire_subject_metadata set to additional metadata to include in the wire subject, or NULL for none
 * @return transaction status code
 */
enum GNUNET_DB_QueryStatus
TALER_EXCHANGEDB_get_ready_deposit (struct TALER_EXCHANGEDB_PostgresContext *pg,
                                    uint64_t start_shard_row,
                                    uint64_t end_shard_row,
                                    struct TALER_MerchantPublicKeyP *
                                    merchant_pub,
                                    struct TALER_FullPayto *payto_uri,
                                    char **extra_wire_subject_metadata);

#endif
