/*
This file is part of TALER
Copyright (C) 2016-2020 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
*/
/**
* @file include/taler_wire_plugin.h
* @brief Plugin API for the handling of wire transactions
* @author Christian Grothoff
*/
#ifndef TALER_WIRE_PLUGIN_H
#define TALER_WIRE_PLUGIN_H
#include
#include "taler_util.h"
#include "taler_error_codes.h"
#include "taler_bank_service.h" /* for `enum TALER_BANK_Direction` and `struct TALER_BANK_TransferDetails` */
/**
* Callback with prepared transaction.
*
* @param cls closure
* @param buf transaction data to persist, NULL on error
* @param buf_size number of bytes in @a buf, 0 on error
*/
typedef void
(*TALER_WIRE_PrepareTransactionCallback) (void *cls,
const char *buf,
size_t buf_size);
/**
* Details about a valid wire transfer to the exchange.
*/
struct TALER_WIRE_CreditDetails
{
/**
* Amount that was transferred
*/
struct TALER_Amount amount;
/**
* Time of the the transfer
*/
struct GNUNET_TIME_Absolute execution_date;
/**
* Binary data that was encoded in the wire transfer subject.
*/
struct TALER_ReservePublicKeyP reserve_pub;
/**
* payto://-URL of the source's account (used
* when the reserve is closed or for debugging).
*/
const char *source_account_url;
};
/**
* Details about a valid wire transfer made by the
* exchange's aggregator to a merchant.
*/
struct TALER_WIRE_DebitDetails
{
/**
* Amount that was transferred
*/
struct TALER_Amount amount;
/**
* Time of the the transfer
*/
struct GNUNET_TIME_Absolute execution_date;
/**
* Binary data that was encoded in the wire transfer subject.
*/
struct TALER_WireTransferIdentifierRawP wtid;
/**
* payto://-URL of the target account which received
* the funds.
*/
const char *target_account_url;
};
/**
* Callbacks of this type are used to serve the result of asking
* the bank for the transaction history. NOTE: this function will
* NOT get the list of history elements, but rather get (iteratively)
* called for each (parsed) history element.
*
* @param cls closure
* @param ec taler error code
* @param row_off identification of the position at which we are querying
* @param row_off_size number of bytes in @a row_off
* @param details details about the wire transfer
* @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration
*/
typedef int
(*TALER_WIRE_CreditResultCallback) (void *cls,
enum TALER_ErrorCode ec,
const void *row_off,
size_t row_off_size,
const struct
TALER_WIRE_CreditDetails *details);
/**
* Callbacks of this type are used to serve the result of asking
* the bank for the transaction history. NOTE: this function will
* NOT get the list of history elements, but rather get (iteratively)
* called for each (parsed) history element.
*
* @param cls closure
* @param ec taler error code
* @param row_off identification of the position at which we are querying
* @param row_off_size number of bytes in @a row_off
* @param details details about the wire transfer
* @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration
*/
typedef int
(*TALER_WIRE_DebitResultCallback) (void *cls,
enum TALER_ErrorCode ec,
const void *row_off,
size_t row_off_size,
const struct
TALER_WIRE_DebitDetails *details);
/**
* Handle returned for cancelling a preparation step.
*/
struct TALER_WIRE_PrepareHandle;
/**
* Handle returned for cancelling an execution step.
*/
struct TALER_WIRE_ExecuteHandle;
/**
* Handle returned for querying the credit transaction history.
*/
struct TALER_WIRE_CreditHistoryHandle;
/**
* Handle returned for querying the debit transaction history.
*/
struct TALER_WIRE_DebitHistoryHandle;
/**
* Function called with the result from the execute step.
*
* @param cls closure
* @param success #GNUNET_OK on success, #GNUNET_SYSERR on failure
* @param row_id unique ID of the wire transfer in the bank's records; NULL on error
* @param row_id_size number of bytes in @e row_id
* @param emsg NULL on success, otherwise an error message
*/
typedef void
(*TALER_WIRE_ConfirmationCallback)(void *cls,
int success,
const void *row_id,
size_t row_id_size,
const char *emsg);
/**
* @brief The plugin API, returned from the plugin's "init" function.
* The argument given to "init" is simply a configuration handle.
*/
struct TALER_WIRE_Plugin
{
/**
* Closure for all callbacks.
*/
void *cls;
/**
* Name of the library which generated this plugin. Set by the
* plugin loader.
*/
char *library_name;
/**
* Which wire method (payto://METHOD/") is supported by this plugin?
* For example, "x-taler-bank" or "iban".
*/
const char *method;
/**
* Round amount DOWN to the amount that can be transferred via the wire
* method. For example, Taler may support 0.000001 EUR as a unit of
* payment, but IBAN only supports 0.01 EUR. This function would
* round 0.125 EUR to 0.12 EUR in this case.
*
* @param cls the @e cls of this struct with the plugin-specific state
* @param[in,out] amount amount to round down
* @return #GNUNET_OK on success, #GNUNET_NO if rounding was unnecessary,
* #GNUNET_SYSERR if the amount or currency was invalid
*/
int
(*amount_round) (void *cls,
struct TALER_Amount *amount);
/**
* Check if the given payto:// URL is correctly formatted for this plugin
*
* @param cls the @e cls of this struct with the plugin-specific state
* @param account_url the payto:// URL
* @return #TALER_EC_NONE if correctly formatted
*/
enum TALER_ErrorCode
(*wire_validate)(void *cls,
const char *account_url);
/**
* Query credits made to exchange account. We use the variable-size
* @a start_off to indicate which transfers we are interested in as
* different banking systems may have different ways to identify
* transfers. The @a start_off value must thus match the value of
* a `row_off` argument previously given to the @a hres_cb. Use
* NULL to query transfers from the beginning of time (with
* positive @a num_results) or from the latest committed transfers
* (with negative @a num_results).
*
* @param cls the @e cls of this struct with the plugin-specific state
* @param account_section specifies the configuration section which
* identifies the account for which we should get the history
* @param start_off from which row on do we want to get results, use NULL for the latest; exclusive
* @param start_off_len number of bytes in @a start_off
* @param num_results how many results do we want; negative numbers to go into the past,
* positive numbers to go into the future starting at @a start_row;
* must not be zero.
* @param hres_cb the callback to call with the transaction history
* @param hres_cb_cls closure for the above callback
*/
struct TALER_WIRE_CreditHistoryHandle *
(*get_credits) (void *cls,
const char *account_section,
const void *start_off,
size_t start_off_len,
int64_t num_results,
TALER_WIRE_CreditResultCallback hres_cb,
void *hres_cb_cls);
/**
* Cancel going over the account's history.
*
* @param cls plugins' closure
* @param chh operation to cancel
*/
void
(*get_credits_cancel) (void *cls,
struct TALER_WIRE_CreditHistoryHandle *chh);
/**
* Query debits (transfers to merchants) made by an exchange. We use the
* variable-size @a start_off to indicate which transfers we are interested
* in as different banking systems may have different ways to identify
* transfers. The @a start_off value must thus match the value of a
* `row_off` argument previously given to the @a hres_cb. Use NULL to query
* transfers from the beginning of time (with positive @a num_results) or
* from the latest committed transfers (with negative @a num_results).
*
* @param cls the @e cls of this struct with the plugin-specific state
* @param account_section specifies the configuration section which
* identifies the account for which we should get the history
* @param start_off from which row on do we want to get results, use NULL for the latest; exclusive
* @param start_off_len number of bytes in @a start_off
* @param num_results how many results do we want; negative numbers to go into the past,
* positive numbers to go into the future starting at @a start_row;
* must not be zero.
* @param hres_cb the callback to call with the transaction history
* @param hres_cb_cls closure for the above callback
*/
struct TALER_WIRE_DebitHistoryHandle *
(*get_debits) (void *cls,
const char *account_section,
const void *start_off,
size_t start_off_len,
int64_t num_results,
TALER_WIRE_DebitResultCallback hres_cb,
void *hres_cb_cls);
/**
* Cancel going over the account's history.
*
* @param cls plugins' closure
* @param dhh operation to cancel
*/
void
(*get_debits_cancel) (void *cls,
struct TALER_WIRE_DebitHistoryHandle *dhh);
};
#endif /* TALER_WIRE_PLUGIN_H */