commit c83b53428f42c9bcb1dcbefcc897b062a0571343
parent 5a96fed086fa6dcbab52496e75c1895870ae1e79
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 22 Feb 2026 13:45:12 +0100
add prototypes for future exchange C API (first draft)
Diffstat:
65 files changed, 9270 insertions(+), 4524 deletions(-)
diff --git a/contrib/microhttpd.tag b/contrib/microhttpd.tag
@@ -94,6 +94,24 @@
</member>
<member kind="define">
<type>#define</type>
+ <name>MHD_HTTP_FOUND</name>
+ <anchorfile>microhttpd.h</anchorfile>
+ <arglist></arglist>
+ </member>
+ <member kind="define">
+ <type>#define</type>
+ <name>MHD_HTTP_CREATED</name>
+ <anchorfile>microhttpd.h</anchorfile>
+ <arglist></arglist>
+ </member>
+ <member kind="define">
+ <type>#define</type>
+ <name>MHD_HTTP_NOT_MODIFIED</name>
+ <anchorfile>microhttpd.h</anchorfile>
+ <arglist></arglist>
+ </member>
+ <member kind="define">
+ <type>#define</type>
<name>MHD_HTTP_NO_CONTENT</name>
<anchorfile>microhttpd.h</anchorfile>
<arglist></arglist>
diff --git a/src/exchange-tools/taler-exchange-offline.c b/src/exchange-tools/taler-exchange-offline.c
@@ -574,7 +574,7 @@ static struct GNUNET_SCHEDULER_Task *nxt;
/**
* Handle for #do_download.
*/
-static struct TALER_EXCHANGE_ManagementGetKeysHandle *mgkh;
+static struct TALER_EXCHANGE_GetManagementKeysHandle *mgkh;
/**
* Active AML staff change requests.
diff --git a/src/include/taler/taler-exchange/aml_attributes_get.h b/src/include/taler/taler-exchange/aml_attributes_get.h
@@ -1,305 +0,0 @@
-/*
- This file is part of TALER
- Copyright (C) 2025 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/taler-exchange/aml_attributes_get.h
- * @brief C interface for the GET /aml/$OFFICER_PUB/attributes/$H_NORMALIZED_PAYTO endpoint
- * @author Christian Grothoff
- */
-#ifndef _TALER_EXCHANGE__AML_ATTRIBUTES_GET_H
-#define _TALER_EXCHANGE__AML_ATTRIBUTES_GET_H
-
-#include <taler/taler-exchange/common.h>
-
-/**
- * Possible options we can set for the GET attributes request.
- */
-enum TALER_EXCHANGE_AmlAttributesGetOption
-{
- /**
- * End of list of options.
- */
- TALER_EXCHANGE_AML_ATTRIBUTES_GET_OPTION_END = 0,
-
- /**
- * Return at most N values, default is -20 to return
- * the last 20 entries before start. Negative values
- * to return before limit, positive to return after limit.
- */
- TALER_EXCHANGE_AML_ATTRIBUTES_GET_OPTION_LIMIT,
-
- /**
- * Row number threshold, defaults to INT64_MAX, namely
- * the biggest row id possible in the database.
- */
- TALER_EXCHANGE_AML_ATTRIBUTES_GET_OPTION_OFFSET
-
-};
-
-
-/**
- * Possible options we can set for the GET attributes request.
- */
-struct TALER_EXCHANGE_AmlAttributesGetOptionValue
-{
-
- /**
- * Type of the option being set.
- */
- enum TALER_EXCHANGE_AmlAttributesGetOption option;
-
- /**
- * Specific option value.
- */
- union
- {
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_ATTRIBUTES_GET_OPTION_LIMIT.
- */
- int64_t limit;
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_ATTRIBUTES_GET_OPTION_OFFSET.
- * Note that in practice the maximum value is INT64_MAX, even though
- * this value is unsigned.
- */
- uint64_t offset;
-
- } details;
-
-};
-
-
-/**
- * Handle for an operation to GET /aml/$OFFICER_PUB/attributes/$H_NORMALIZED_PAYTO.
- */
-struct TALER_EXCHANGE_AmlAttributesGetHandle;
-
-
-/**
- * Set up GET /aml/$OPUB/attributes/$H_NORMALIZED_PAYTO operation.
- * Note that you must explicitly start the operation after
- * possibly setting options.
- *
- * @param ctx the context
- * @param url base URL of the exchange
- * @param officer_priv private key of the officer
- * @param h_payto normalized payto URI hash of the account to get attributes for
- * @return handle to operation
- */
-struct TALER_EXCHANGE_AmlAttributesGetHandle *
-TALER_EXCHANGE_aml_attributes_get_create (
- struct GNUNET_CURL_Context *ctx,
- const char *url,
- const struct TALER_AmlOfficerPrivateKeyP *officer_priv,
- const struct TALER_NormalizedPaytoHashP *h_payto);
-
-
-/**
- * Terminate the list of the options.
- *
- * @return the terminating object of struct TALER_EXCHANGE_AmlAttributesGetOptionValue
- */
-#define TALER_EXCHANGE_aml_attributes_get_option_end_() \
- (const struct TALER_EXCHANGE_AmlAttributesGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_ATTRIBUTES_GET_OPTION_END \
- }
-
-/**
- * Set limit @a l on the number of results to return.
- *
- * @param l limit on the number of results to return
- * @return representation of the option as a struct TALER_EXCHANGE_AmlAttributesGetOptionValue
- */
-#define TALER_EXCHANGE_aml_attributes_get_option_limit(l) \
- (const struct TALER_EXCHANGE_AmlAttributesGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_ATTRIBUTES_GET_OPTION_LIMIT, \
- .details.limit = (l) \
- }
-
-
-/**
- * Set row offset from which to return results.
- *
- * @param o offset to use
- * @return representation of the option as a struct TALER_EXCHANGE_AmlAttributesGetOptionValue
- */
-#define TALER_EXCHANGE_aml_attributes_get_option_offset(o) \
- (const struct TALER_EXCHANGE_AmlAttributesGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_ATTRIBUTES_GET_OPTION_OFFSET, \
- .details.offset = (o) \
- }
-
-
-/**
- * Set the requested options for the operation.
- *
- * If any option fail other options may be or may be not applied.
- *
- * @param aagh the request to set the options for
- * @param num_options length of the @a options array
- * @param options an array of options
- * @return ::TALER_EC_NONE on success,
- * error code otherwise
- * @return #GNUNET_OK on success,
- * #GNUNET_NO on failure,
- * #GNUNET_SYSERR on internal error
- */
-enum GNUNET_GenericReturnValue
-TALER_EXCHANGE_aml_attributes_get_set_options_ (
- struct TALER_EXCHANGE_AmlAttributesGetHandle *aagh,
- unsigned int num_options,
- const struct TALER_EXCHANGE_AmlAttributesGetOptionValue *options);
-
-
-/**
- * Set the requested options for the operation.
- *
- * If any option fail other options may be or may be not applied.
- *
- * It should be used with helpers that creates required options, for example:
- *
- * TALER_EXCHANGE_aml_attributes_get_set_options (
- * aagh,
- * TALER_EXCHANGE_aml_attributes_get_option_limit_(10));
- *
- * @param aagh the request to set the options for
- * @param ... the list of the options, each option must be created
- * by helpers TALER_EXCHANGE_aml_attributes_get_option_NAME(VALUE)
- * @return ::TALER_EC_NONE on success,
- * error code otherwise
- */
-#define TALER_EXCHANGE_aml_attributes_get_set_options(aagh,...) \
- TALER_EXCHANGE_aml_attributes_get_set_options_ ( \
- aagh, \
- TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
- ((const struct TALER_EXCHANGE_AmlAttributesGetOptionValue[]) \
- {__VA_ARGS__, TALER_EXCHANGE_aml_attributes_get_option_end_ () } \
- ))
-
-
-/**
- * Entry in the set of KYC attribute collection events that are returned
- * by the server in a single request.
- */
-struct TALER_EXCHANGE_AmlAttributesGetCollectionEvent
-{
- /**
- * Row ID of the record. Used to filter by offset.
- */
- uint64_t rowid;
-
- /**
- * The collected KYC data. NULL if the attribute data could not
- * be decrypted (internal error of the exchange, likely the
- * attribute key was changed).
- */
- const json_t *attributes;
-
- /**
- * Time when the KYC data was collected.
- */
- struct GNUNET_TIME_Timestamp collection_time;
-};
-
-/**
- * Information returned from the exchange for a
- * GET /aml/$OFFICER_PUB/attributes/$H_NORMALIZED_PAYTO request.
- */
-struct TALER_EXCHANGE_AmlAttributesGetResult
-{
- /**
- * HTTP response data
- */
- struct TALER_EXCHANGE_HttpResponse hr;
-
- /**
- * Details depending on the HTTP status code.
- */
- union
- {
-
- /**
- * Details on #MHD_HTTP_OK.
- */
- struct
- {
- /**
- * Length of the @e details array.
- */
- size_t details_length;
-
- /**
- * Matching KYC attribute history of the account.
- */
- const struct TALER_EXCHANGE_AmlAttributesGetCollectionEvent *details;
-
- } ok;
-
- } details;
-};
-
-
-#ifndef TALER_EXCHANGE__AML_ATTRIBUTES_GET_RESULT_CLOSURE
-/**
- * Type of the closure used by
- * the #TALER_EXCHANGE_AmlAttributesGetCallback.
- */
-#define TALER_EXCHANGE__AML_ATTRIBUTES_GET_RESULT_CLOSURE void
-#endif
-
-/**
- * Type of the function that receives the result of a
- * GET /aml/$OFFICER_PUB/attributes/$H_NORMALIZED_PAYTO request.
- *
- * @param cls closure
- * @param result result returned by the HTTP server
- */
-typedef void
-(*TALER_EXCHANGE_AmlAttributesGetCallback)(
- TALER_EXCHANGE__AML_ATTRIBUTES_GET_RESULT_CLOSURE *cls,
- const struct TALER_EXCHANGE_AmlAttributesGetResult *result);
-
-
-/**
- * Start GET /aml/$OPUB/attributes/$H_NORMALIZED_PAYTO operation.
- *
- * @param[in,out] aagh operation to start
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return status code
- */
-enum TALER_ErrorCode
-TALER_EXCHANGE_aml_attributes_get_start (
- struct TALER_EXCHANGE_AmlAttributesGetHandle *aagh,
- TALER_EXCHANGE_AmlAttributesGetCallback cb,
- TALER_EXCHANGE__AML_ATTRIBUTES_GET_RESULT_CLOSURE *cb_cls);
-
-
-/**
- * Cancel GET /aml/$OPUB/attributes/$H_NORMALIZED_PAYTO operation.
- *
- * @param[in] aagh operation to cancel
- */
-void
-TALER_EXCHANGE_aml_attributes_get_cancel (
- struct TALER_EXCHANGE_AmlAttributesGetHandle *aagh);
-
-
-#endif
diff --git a/src/include/taler/taler-exchange/aml_decisions_get.h b/src/include/taler/taler-exchange/aml_decisions_get.h
@@ -1,496 +0,0 @@
-/*
- This file is part of TALER
- Copyright (C) 2025 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/taler-exchange/aml_decisions_get.h
- * @brief C interface for the GET /aml/$OFFICER_PUB/decisions endpoint
- * @author Christian Grothoff
- */
-#ifndef _TALER_EXCHANGE__AML_DECISIONS_GET_H
-#define _TALER_EXCHANGE__AML_DECISIONS_GET_H
-
-#include <taler-exchange/common.h>
-
-/**
- * Possible options we can set for the GET decisions request.
- */
-enum TALER_EXCHANGE_AmlDecisionsGetOption
-{
- /**
- * End of list of options.
- */
- TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_END = 0,
-
- /**
- * Return at most N values, default is -20 to return
- * the last 20 entries before start. Negative values
- * to return before limit, positive to return after limit.
- */
- TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_LIMIT,
-
- /**
- * Row number threshold, defaults to INT64_MAX, namely
- * the biggest row id possible in the database.
- */
- TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_OFFSET,
-
- /**
- * Filter by account using a normalized payto URI hash.
- */
- TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_H_PAYTO,
-
- /**
- * If set to #TALER_EXCHANGE_YNA_YES, only return active
- * results, #TALER_EXCHANGE_YNA_NO, only return inactive
- * results, #TALER_EXCHANGE_YNA_ALL, to return all
- * decisions. Default is all.
- */
- TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_ACTIVE,
-
- /**
- * If set to #TALER_EXCHANGE_YNA_YES, only return accounts
- * under investigation, #TALER_EXCHANGE_YNA_NO, only return
- * accounts not under investigation, #TALER_EXCHANGE_YNA_ALL,
- * to return all accounts. Default is all.
- */
- TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_INVESTIGATION
-
-};
-
-
-/**
- * Possible options we can set for the GET decisions request.
- */
-struct TALER_EXCHANGE_AmlDecisionsGetOptionValue
-{
-
- /**
- * Type of the option being set.
- */
- enum TALER_EXCHANGE_AmlDecisionsGetOption option;
-
- /**
- * Specific option value.
- */
- union
- {
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_LIMIT.
- */
- int64_t limit;
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_OFFSET.
- * Note that in practice the maximum value is INT64_MAX, even though
- * this value is unsigned.
- */
- uint64_t offset;
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_H_PAYTO.
- */
- const struct TALER_NormalizedPaytoHashP *h_payto;
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_ACTIVE.
- */
- enum TALER_EXCHANGE_YesNoAll active;
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_INVESTIGATION.
- */
- enum TALER_EXCHANGE_YesNoAll investigation;
-
- } details;
-
-};
-
-
-/**
- * Handle for an operation to GET /aml/$OFFICER_PUB/decisions.
- */
-struct TALER_EXCHANGE_AmlDecisionsGetHandle;
-
-
-/**
- * Information about a KYC rule.
- */
-struct TALER_EXCHANGE_AmlDecisionsGetKycRule
-{
- /**
- * Type of operation to which the rule applies.
- */
- enum TALER_KYCLOGIC_KycTriggerEvent operation_type;
-
- /**
- * Name of the configuration section this rule originates from.
- * Can be NULL.
- */
- const char *rule_name;
-
- /**
- * The threshold amount that triggers the measures.
- */
- struct TALER_Amount threshold;
-
- /**
- * Over which duration should the threshold be computed.
- */
- struct GNUNET_TIME_Relative timeframe;
-
- /**
- * Length of the @e measures array.
- */
- size_t measures_length;
-
- /**
- * Array of names of measures to apply.
- */
- const char **measures;
-
- /**
- * Display priority for this rule.
- */
- int64_t display_priority;
-
- /**
- * True if the rule should be exposed to the client.
- */
- bool exposed;
-
- /**
- * True if all measures need to be satisfied (AND combinator),
- * false if any measure is sufficient (OR combinator).
- */
- bool is_and_combinator;
-};
-
-
-/**
- * Legitimization rule set associated with an AML decision.
- */
-struct TALER_EXCHANGE_AmlDecisionsGetLegitimizationRuleSet
-{
- /**
- * When does this set of rules expire?
- */
- struct GNUNET_TIME_Timestamp expiration_time;
-
- /**
- * Name of the successor measure to apply when expiration time is reached.
- * Can be NULL.
- */
- const char *successor_measure;
-
- /**
- * Length of the @e rules array.
- */
- size_t rules_length;
-
- /**
- * Array of KYC rules.
- */
- struct TALER_EXCHANGE_AmlDecisionsGetKycRule *rules;
-
- /**
- * Custom measures.
- */
- const json_t *custom_measures;
-};
-
-
-/**
- * Entry in the set of AML decisions that are returned
- * by the server in a single request.
- */
-struct TALER_EXCHANGE_AmlDecisionsGetDecision
-{
- /**
- * Hash of the normalized payto:// URI of the account the
- * decision applies to.
- */
- struct TALER_NormalizedPaytoHashP h_payto;
-
- /**
- * True if the underlying payto://-URI is for a wallet.
- */
- bool is_wallet;
-
- /**
- * Row ID of the decision in the exchange database.
- */
- uint64_t rowid;
-
- /**
- * Justification for the decision. Can be NULL.
- */
- const char *justification;
-
- /**
- * When was the decision made?
- */
- struct GNUNET_TIME_Timestamp decision_time;
-
- /**
- * Account properties. Can be NULL if no properties are set.
- */
- const json_t *properties;
-
- /**
- * Legitimization rules that apply to this account.
- */
- struct TALER_EXCHANGE_AmlDecisionsGetLegitimizationRuleSet limits;
-
- /**
- * True if the account is under investigation by AML staff.
- */
- bool to_investigate;
-
- /**
- * True if this is the active decision for the account.
- */
- bool is_active;
-};
-
-
-/**
- * Information returned from the exchange for a
- * GET /aml/$OFFICER_PUB/decisions request.
- */
-struct TALER_EXCHANGE_AmlDecisionsGetResult
-{
- /**
- * HTTP response data
- */
- struct TALER_EXCHANGE_HttpResponse hr;
-
- /**
- * Details depending on the HTTP status code.
- */
- union
- {
-
- /**
- * Details on #MHD_HTTP_OK.
- */
- struct
- {
- /**
- * Length of the @e records array.
- */
- size_t records_length;
-
- /**
- * AML decisions.
- */
- const struct TALER_EXCHANGE_AmlDecisionsGetDecision *records;
-
- } ok;
-
- } details;
-};
-
-
-/**
- * Set up GET /aml/$OPUB/decisions operation.
- * Note that you must explicitly start the operation after
- * possibly setting options.
- *
- * @param ctx the context
- * @param url base URL of the exchange
- * @param officer_priv private key of the officer
- * @return handle to operation
- */
-struct TALER_EXCHANGE_AmlDecisionsGetHandle *
-TALER_EXCHANGE_aml_decisions_get_create (
- struct GNUNET_CURL_Context *ctx,
- const char *url,
- const struct TALER_AmlOfficerPrivateKeyP *officer_priv);
-
-
-/**
- * Terminate the list of the options.
- *
- * @return the terminating object of struct TALER_EXCHANGE_AmlDecisionsGetOptionValue
- */
-#define TALER_EXCHANGE_aml_decisions_get_option_end_() \
- (const struct TALER_EXCHANGE_AmlDecisionsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_END \
- }
-
-/**
- * Set limit @a l on the number of results to return.
- *
- * @param l limit on the number of results to return
- * @return representation of the option as a struct TALER_EXCHANGE_AmlDecisionsGetOptionValue
- */
-#define TALER_EXCHANGE_aml_decisions_get_option_limit(l) \
- (const struct TALER_EXCHANGE_AmlDecisionsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_LIMIT, \
- .details.limit = (l) \
- }
-
-
-/**
- * Set row offset from which to return results.
- *
- * @param o offset to use
- * @return representation of the option as a struct TALER_EXCHANGE_AmlDecisionsGetOptionValue
- */
-#define TALER_EXCHANGE_aml_decisions_get_option_offset(o) \
- (const struct TALER_EXCHANGE_AmlDecisionsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_OFFSET, \
- .details.offset = (o) \
- }
-
-
-/**
- * Set filter on which account to filter AML decisions by.
- *
- * @param p normalized payto URI hash of the account to filter by
- * @return representation of the option as a struct TALER_EXCHANGE_AmlDecisionsGetOptionValue
- */
-#define TALER_EXCHANGE_aml_decisions_get_option_h_payto(p) \
- (const struct TALER_EXCHANGE_AmlDecisionsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_H_PAYTO, \
- .details.h_payto = (p) \
- }
-
-/**
- * Set filter on active (or inactive) results.
- *
- * @param a activity filter to use
- * @return representation of the option as a struct TALER_EXCHANGE_AmlDecisionsGetOptionValue
- */
-#define TALER_EXCHANGE_aml_decisions_get_option_active(a) \
- (const struct TALER_EXCHANGE_AmlDecisionsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_ACTIVE, \
- .details.active = (a) \
- }
-
-/**
- * Set filter on investigation status.
- *
- * @param i investigation filter to use
- * @return representation of the option as a struct TALER_EXCHANGE_AmlDecisionsGetOptionValue
- */
-#define TALER_EXCHANGE_aml_decisions_get_option_investigation(i) \
- (const struct TALER_EXCHANGE_AmlDecisionsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_DECISIONS_GET_OPTION_INVESTIGATION, \
- .details.investigation = (i) \
- }
-
-
-/**
- * Set the requested options for the operation.
- *
- * If any option fail other options may be or may be not applied.
- *
- * @param adgh the request to set the options for
- * @param num_options length of the @a options array
- * @param options an array of options
- * @return #GNUNET_OK on success,
- * #GNUNET_NO on failure,
- * #GNUNET_SYSERR on internal error
- */
-enum GNUNET_GenericReturnValue
-TALER_EXCHANGE_aml_decisions_get_set_options_ (
- struct TALER_EXCHANGE_AmlDecisionsGetHandle *adgh,
- unsigned int num_options,
- struct TALER_EXCHANGE_AmlDecisionsGetOptionValue options[
- static num_options]);
-
-
-/**
- * Set the requested options for the operation.
- *
- * If any option fail other options may be or may be not applied.
- *
- * It should be used with helpers that creates required options, for example:
- *
- * TALER_EXCHANGE_aml_decisions_get_set_options (
- * adgh,
- * TALER_EXCHANGE_aml_decisions_get_option_h_payto_(&h_payto));
- *
- * @param adgh the request to set the options for
- * @param ... the list of the options, each option must be created
- * by helpers TALER_EXCHANGE_aml_decisions_get_option_NAME(VALUE)
- * @return #GNUNET_OK on success,
- * #GNUNET_NO on failure,
- * #GNUNET_SYSERR on internal error
- */
-#define TALER_EXCHANGE_aml_decisions_get_set_options(adgh,...) \
- TALER_EXCHANGE_aml_decisions_get_set_options_ ( \
- adgh, \
- ((const struct TALER_EXCHANGE_AmlDecisionsGetOptionValue[]) \
- {__VA_ARGS__, TALER_EXCHANGE_aml_decisions_get_option_end_ () } \
- ), \
- TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE)
-
-
-#ifndef TALER_EXCHANGE__AML_DECISIONS_GET_RESULT_CLOSURE
-/**
- * Type of the closure used by
- * the #TALER_EXCHANGE_AmlDecisionsGetCallback.
- */
-#define TALER_EXCHANGE__AML_DECISIONS_GET_RESULT_CLOSURE void
-#endif
-
-/**
- * Type of the function that receives the result of a
- * GET /aml/$OFFICER_PUB/decisions request.
- *
- * @param cls closure
- * @param result result returned by the HTTP server
- */
-typedef void
-(*TALER_EXCHANGE_AmlDecisionsGetCallback)(
- TALER_EXCHANGE__AML_DECISIONS_GET_RESULT_CLOSURE *cls,
- const struct TALER_EXCHANGE_AmlDecisionsGetResult *result);
-
-
-/**
- * Start GET /aml/$OPUB/decisions operation.
- *
- * @param[in,out] adgh operation to start
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return status code
- */
-enum TALER_ErrorCode
-TALER_EXCHANGE_aml_decisions_get_start (
- struct TALER_EXCHANGE_AmlDecisionsGetHandle *adgh,
- TALER_EXCHANGE_AmlDecisionsGetCallback cb,
- TALER_EXCHANGE__AML_DECISIONS_GET_RESULT_CLOSURE *cb_cls);
-
-
-/**
- * Cancel GET /aml/$OPUB/decisions operation.
- *
- * @param[in] adgh operation to cancel
- */
-void
-TALER_EXCHANGE_aml_decisions_get_cancel (
- struct TALER_EXCHANGE_AmlDecisionsGetHandle *adgh);
-
-
-#endif
diff --git a/src/include/taler/taler-exchange/aml_legitimizations_get.h b/src/include/taler/taler-exchange/aml_legitimizations_get.h
@@ -1,377 +0,0 @@
-/*
- This file is part of TALER
- Copyright (C) 2025 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/taler-exchange/aml_legitimizations_get.h
- * @brief C interface for the GET /aml/$OFFICER_PUB/legitimizations endpoint
- * @author Christian Grothoff
- */
-#ifndef _TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_H
-#define _TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_H
-
-#include <taler/taler-exchange/common.h>
-
-/**
- * Possible options we can set for the GET legitimizations request.
- */
-enum TALER_EXCHANGE_AmlLegitimizationsGetOption
-{
- /**
- * End of list of options.
- */
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_END = 0,
-
- /**
- * Return at most N values, default is -20 to return
- * the last 20 entries before start. Negative values
- * to return before limit, positive to return after limit.
- */
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_LIMIT,
-
- /**
- * Row number threshold, defaults to INT64_MAX, namely
- * the biggest row id possible in the database.
- */
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_OFFSET,
-
- /**
- * Filter by account using a normalized payto URI hash.
- */
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_H_PAYTO,
-
- /**
- * If set to #TALER_EXCHANGE_YNA_YES, only return active
- * results, #TALER_EXCHANGE_YNA_NO, only return inactive
- * results, #TALER_EXCHANGE_YNA_ALL, to return all
- * decisions. Default is all.
- */
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_ACTIVE
-
-};
-
-
-/**
- * Possible options we can set for the GET legitimizations request.
- */
-struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
-{
-
- /**
- * Type of the option being set.
- */
- enum TALER_EXCHANGE_AmlLegitimizationsGetOption option;
-
- /**
- * Specific option value.
- */
- union
- {
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_LIMIT.
- */
- int64_t limit;
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_OFFSET.
- * Note that in practice the maximum value is INT64_MAX, even though
- * this value is unsigned.
- */
- uint64_t offset;
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_H_PAYTO.
- */
- const struct TALER_NormalizedPaytoHashP *h_payto;
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_ACTIVE.
- */
- enum TALER_EXCHANGE_YesNoAll active;
-
- } details;
-
-};
-
-
-/**
- * Handle for an operation to GET /aml/$OFFICER_PUB/legitimizations.
- */
-struct TALER_EXCHANGE_AmlLegitimizationsGetHandle;
-
-
-/**
- * Set up GET /aml/$OPUB/legitimizations operation.
- * Note that you must explicitly start the operation after
- * possibly setting options.
- *
- * @param ctx the context
- * @param url base URL of the exchange
- * @param officer_priv private key of the officer
- * @return handle to operation
- */
-struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *
-TALER_EXCHANGE_aml_legitimizations_get_create (
- struct GNUNET_CURL_Context *ctx,
- const char *url,
- const struct TALER_AmlOfficerPrivateKeyP *officer_priv);
-
-
-/**
- * Terminate the list of the options.
- *
- * @return the terminating object of struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
- */
-#define TALER_EXCHANGE_aml_legitimizations_get_option_end_() \
- (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_END \
- }
-
-/**
- * Set limit @a l on the number of results to return.
- *
- * @param l limit on the number of results to return
- * @return representation of the option as a struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
- */
-#define TALER_EXCHANGE_aml_legitimizations_get_option_limit(l) \
- (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_LIMIT, \
- .details.limit = (l) \
- }
-
-
-/**
- * Set row offset from which to return results.
- *
- * @param o offset to use
- * @return representation of the option as a struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
- */
-#define TALER_EXCHANGE_aml_legitimizations_get_option_offset(o) \
- (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_OFFSET, \
- .details.offset = (o) \
- }
-
-
-/**
- * Set filter on which account to filter legitimization measures by.
- *
- * @param p normalized payto URI hash of the account to filter by
- * @return representation of the option as a struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
- */
-#define TALER_EXCHANGE_aml_legitimizations_get_option_h_payto(p) \
- (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_H_PAYTO, \
- .details.h_payto = (p) \
- }
-
-/**
- * Set filter on active (or inactive) results.
- *
- * @param a activity filter to use
- * @return representation of the option as a struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
- */
-#define TALER_EXCHANGE_aml_legitimizations_get_option_active(a) \
- (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_ACTIVE, \
- .details.active = (a) \
- }
-
-
-/**
- * Set the requested options for the operation.
- *
- * If any option fail other options may be or may be not applied.
- *
- * @param algh the request to set the options for
- * @param num_options length of the @a options array
- * @param options array of options, each option must be created
- * by helpers TALER_EXCHANGE_aml_legitimizations_get_option_NAME(VALUE)
- * @return #GNUNET_OK on success,
- * #GNUNET_NO on failure,
- * #GNUNET_SYSERR on internal error
- */
-enum GNUNET_GenericReturnValue
-TALER_EXCHANGE_aml_legitimizations_get_set_options_ (
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh,
- unsigned int num_options,
- const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue *options);
-
-
-/**
- * Set the requested options for the operation.
- *
- * If any option fail other options may be or may be not applied.
- *
- * It should be used with helpers that creates required options, for example:
- *
- * TALER_EXCHANGE_aml_legitimizations_get_set_options (
- * algh,
- * TALER_EXCHANGE_aml_legitimizations_get_option_h_payto_(&h_payto));
- *
- * @param algh the request to set the options for
- * @param ... the list of the options, each option must be created
- * by helpers TALER_EXCHANGE_aml_legitimizations_get_option_NAME(VALUE)
- * @return #GNUNET_OK on success,
- * #GNUNET_NO on failure,
- * #GNUNET_SYSERR on internal error
- */
-#define TALER_EXCHANGE_aml_legitimizations_get_set_options(algh,...) \
- TALER_EXCHANGE_aml_legitimizations_get_set_options_ ( \
- algh, \
- TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
- ((const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue[]) \
- {__VA_ARGS__, TALER_EXCHANGE_aml_legitimizations_get_option_end_ () } \
- ))
-
-
-/**
- * Entry in the set of legitimization measures that are returned
- * by the server in a single request.
- */
-struct TALER_EXCHANGE_AmlLegitimizationsGetMeasureDetails
-{
- /**
- * Hash of the normalized payto:// URI of the account the
- * measure applies to.
- */
- struct TALER_NormalizedPaytoHashP h_payto;
-
- /**
- * Row ID of the measure in the exchange database.
- */
- uint64_t rowid;
-
- /**
- * When was the measure started / triggered?
- */
- struct GNUNET_TIME_Timestamp start_time;
-
- /**
- * Object with the legitimization measures that are to be applied.
- */
- const json_t *measures;
-
- /**
- * Was this measure finished by the customer? (or obsoleted
- * by a subsequent other measure taken)?
- */
- bool is_finished;
-};
-
-/**
- * Information returned from the exchange for a
- * GET /aml/$OFFICER_PUB/legitimizations request.
- */
-struct TALER_EXCHANGE_AmlLegitimizationsGetResult
-{
- /**
- * HTTP response data
- */
- struct TALER_EXCHANGE_HttpResponse hr;
-
- /**
- * Details depending on the HTTP status code.
- */
- union
- {
-
- /**
- * Details on #MHD_HTTP_OK.
- */
- struct
- {
- /**
- * Length of the @e measures array.
- */
- size_t measures_length;
-
- /**
- * Legitimization measures.
- */
- const struct TALER_EXCHANGE_AmlLegitimizationsGetMeasureDetails *measures;
-
- } ok;
-
- } details;
-};
-
-
-#ifndef TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE
-/**
- * Type of the closure used by
- * the #TALER_EXCHANGE_AmlLegitimizationsGetCallback.
- */
-#define TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE void
-#endif
-
-/**
- * Type of the function that receives the result of a
- * GET /aml/$OFFICER_PUB/legitimizations request.
- *
- * @param cls closure
- * @param result result returned by the HTTP server
- */
-typedef void
-(*TALER_EXCHANGE_AmlLegitimizationsGetCallback)(
- TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE *cls,
- const struct TALER_EXCHANGE_AmlLegitimizationsGetResult *result);
-
-
-/**
- * Start GET /aml/$OPUB/legitimizations operation.
- *
- * @param[in,out] algh operation to start
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return status code
- */
-enum TALER_EXCHANGE_AmlLegitimizationsGetStartError
-{
- /**
- * Success.
- */
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_OK = 0,
- /**
- * Only allowed to be started once.
- */
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_E_AGAIN = 1,
- /**
- * Internal logic failure.
- */
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_E_INTERNAL = 2,
-}
-TALER_EXCHANGE_aml_legitimizations_get_start (
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh,
- TALER_EXCHANGE_AmlLegitimizationsGetCallback cb,
- TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE * cb_cls);
-
-
-/**
- * Cancel GET /aml/$OPUB/legitimizations operation.
- *
- * @param[in] algh operation to cancel
- */
-void
-TALER_EXCHANGE_aml_legitimizations_get_cancel (
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh);
-
-
-#endif
diff --git a/src/include/taler/taler-exchange/aml_transfers_kycauth_get.h b/src/include/taler/taler-exchange/aml_transfers_kycauth_get.h
@@ -1,352 +0,0 @@
-/*
- This file is part of TALER
- Copyright (C) 2025 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/taler-exchange/aml_transfers_kycauth_get.h
- * @brief C interface for the GET /aml/$OFFICER_PUB/transfers-kycauth endpoint
- * @author Christian Grothoff
- */
-#ifndef _TALER_EXCHANGE__AML_TRANSFERS_KYCAUTH_GET_H
-#define _TALER_EXCHANGE__AML_TRANSFERS_KYCAUTH_GET_H
-
-#include <taler/taler-exchange/common.h>
-
-/**
- * Possible options we can set for the GET transfers-kycauth request.
- */
-enum TALER_EXCHANGE_AmlTransfersKycauthGetOption
-{
- /**
- * End of list of options.
- */
- TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_END = 0,
-
- /**
- * Minimum amount threshold to return. All amounts below
- * the given threshold will be filtered.
- */
- TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_THRESHOLD,
-
- /**
- * Return at most N values, default is -20 to return
- * the last 20 entries before start. Negative values
- * to return before limit, positive to return after limit.
- */
- TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_LIMIT,
-
- /**
- * Row number threshold, defaults to INT64_MAX, namely
- * the biggest row id possible in the database.
- */
- TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_OFFSET,
-
- /**
- * Filter by account using a normalized payto URI hash.
- */
- TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_H_PAYTO
-
-};
-
-
-/**
- * Possible options we can set for the GET transfers-kycauth request.
- */
-struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
-{
-
- /**
- * Type of the option being set.
- */
- enum TALER_EXCHANGE_AmlTransfersKycauthGetOption option;
-
- /**
- * Specific option value.
- */
- union
- {
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_THRESHOLD.
- */
- const struct TALER_Amount *threshold;
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_LIMIT.
- */
- int64_t limit;
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_OFFSET.
- * Note that in practice the maximum value is INT64_MAX, even though
- * this value is unsigned.
- */
- uint64_t offset;
-
- /**
- * Value of if @e option is TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_H_PAYTO.
- */
- const struct TALER_NormalizedPaytoHashP *h_payto;
-
- } details;
-
-};
-
-
-/**
- * Handle for an operation to GET /aml/$OFFICER_PUB/transfers-kycauth.
- */
-struct TALER_EXCHANGE_AmlTransfersKycauthGetHandle;
-
-
-/**
- * Set up GET /aml/$OPUB/transfers-kycauth operation.
- * Note that you must explicitly start the operation after
- * possibly setting options.
- *
- * @param ctx the context
- * @param url base URL of the exchange
- * @param officer_priv private key of the officer
- * @return handle to operation
- */
-struct TALER_EXCHANGE_AmlTransfersKycauthGetHandle *
-TALER_EXCHANGE_aml_transfers_kycauth_get_create (
- struct GNUNET_CURL_Context *ctx,
- const char *url,
- const struct TALER_AmlOfficerPrivateKeyP *officer_priv);
-
-
-/**
- * Terminate the list of the options.
- *
- * @return the terminating object of struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
- */
-#define TALER_EXCHANGE_aml_transfers_kycauth_get_option_end_() \
- (const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_END \
- }
-
-/**
- * Set minimum amount threshold @a t for transfers to return.
- *
- * @param t minimum amount threshold
- * @return representation of the option as a struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
- */
-#define TALER_EXCHANGE_aml_transfers_kycauth_get_option_threshold(t) \
- (const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_THRESHOLD, \
- .details.threshold = (t) \
- }
-
-/**
- * Set limit @a l on the number of results to return.
- *
- * @param l limit on the number of results to return
- * @return representation of the option as a struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
- */
-#define TALER_EXCHANGE_aml_transfers_kycauth_get_option_limit(l) \
- (const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_LIMIT, \
- .details.limit = (l) \
- }
-
-
-/**
- * Set row offset from which to return results.
- *
- * @param o offset to use
- * @return representation of the option as a struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
- */
-#define TALER_EXCHANGE_aml_transfers_kycauth_get_option_offset(o) \
- (const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_OFFSET, \
- .details.offset = (o) \
- }
-
-
-/**
- * Set filter on which account to filter transfers by.
- *
- * @param p normalized payto URI hash of the account to filter by
- * @return representation of the option as a struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
- */
-#define TALER_EXCHANGE_aml_transfers_kycauth_get_option_h_payto(p) \
- (const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_H_PAYTO, \
- .details.h_payto = (p) \
- }
-
-
-/**
- * Set the requested options for the operation.
- *
- * If any option fail other options may be or may be not applied.
- *
- * @param atkgh the request to set the options for
- * @param num_options length of the @a options array
- * @param options an array of options
- * @return #GNUNET_OK on success,
- * #GNUNET_NO on failure,
- * #GNUNET_SYSERR on internal error
- */
-enum GNUNET_GenericReturnValue
-TALER_EXCHANGE_aml_transfers_kycauth_get_set_options_ (
- struct TALER_EXCHANGE_AmlTransfersKycauthGetHandle *atkgh,
- unsigned int num_options,
- const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue *options);
-
-
-/**
- * Set the requested options for the operation.
- *
- * If any option fail other options may be or may be not applied.
- *
- * It should be used with helpers that creates required options, for example:
- *
- * TALER_EXCHANGE_aml_transfers_kycauth_get_set_options (
- * atkgh,
- * TALER_EXCHANGE_aml_transfers_kycauth_get_option_h_payto_(&h_payto));
- *
- * @param atkgh the request to set the options for
- * @param ... the list of the options, each option must be created
- * by helpers TALER_EXCHANGE_aml_transfers_kycauth_get_option_NAME(VALUE)
- * @return ::TALER_EC_NONE on success,
- * error code otherwise
- */
-#define TALER_EXCHANGE_aml_transfers_kycauth_get_set_options(atkgh,...) \
- TALER_EXCHANGE_aml_transfers_kycauth_get_set_options_ ( \
- atkgh, \
- TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
- ((const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue[]) \
- {__VA_ARGS__, TALER_EXCHANGE_aml_transfers_kycauth_get_option_end_ () \
- })
-
-
-/**
- * Entry in the set of transfers that are returned
- * by the server in a single request.
- */
-struct TALER_EXCHANGE_AmlTransfersKycauthGetTransferEntry
-{
- /**
- * Row ID of the record. Used to filter by offset.
- */
- uint64_t rowid;
-
- /**
- * payto://-URI of the other account.
- */
- const char *payto_uri;
-
- /**
- * The amount involved.
- */
- struct TALER_Amount amount;
-
- /**
- * Time when the transfer was made.
- */
- struct GNUNET_TIME_Timestamp execution_time;
-};
-
-/**
- * Information returned from the exchange for a
- * GET /aml/$OFFICER_PUB/transfers-kycauth request.
- */
-struct TALER_EXCHANGE_AmlTransfersKycauthGetResult
-{
- /**
- * HTTP response data
- */
- struct TALER_EXCHANGE_HttpResponse hr;
-
- /**
- * Details depending on the HTTP status code.
- */
- union
- {
-
- /**
- * Details on #MHD_HTTP_OK.
- */
- struct
- {
- /**
- * Length of the @e transfers array.
- */
- size_t transfers_length;
-
- /**
- * Matching transactions of the exchange.
- */
- const struct TALER_EXCHANGE_AmlTransfersKycauthGetTransferEntry *
- transfers;
-
- } ok;
-
- } details;
-};
-
-
-#ifndef TALER_EXCHANGE__AML_TRANSFERS_KYCAUTH_GET_RESULT_CLOSURE
-/**
- * Type of the closure used by
- * the #TALER_EXCHANGE_AmlTransfersKycauthGetCallback.
- */
-#define TALER_EXCHANGE__AML_TRANSFERS_KYCAUTH_GET_RESULT_CLOSURE void
-#endif
-
-/**
- * Type of the function that receives the result of a
- * GET /aml/$OFFICER_PUB/transfers-kycauth request.
- *
- * @param cls closure
- * @param result result returned by the HTTP server
- */
-typedef void
-(*TALER_EXCHANGE_AmlTransfersKycauthGetCallback)(
- TALER_EXCHANGE__AML_TRANSFERS_KYCAUTH_GET_RESULT_CLOSURE *cls,
- const struct TALER_EXCHANGE_AmlTransfersKycauthGetResult *result);
-
-
-/**
- * Start GET /aml/$OPUB/transfers-kycauth operation.
- *
- * @param[in,out] atkgh operation to start
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- */
-void
-TALER_EXCHANGE_aml_transfers_kycauth_get_start (
- struct TALER_EXCHANGE_AmlTransfersKycauthGetHandle *atkgh,
- TALER_EXCHANGE_AmlTransfersKycauthGetCallback cb,
- TALER_EXCHANGE__AML_TRANSFERS_KYCAUTH_GET_RESULT_CLOSURE *cb_cls);
-
-
-/**
- * Cancel GET /aml/$OPUB/transfers-kycauth operation.
- *
- * @param[in] atkgh operation to cancel
- */
-void
-TALER_EXCHANGE_aml_transfers_kycauth_get_cancel (
- struct TALER_EXCHANGE_AmlTransfersKycauthGetHandle *atkgh);
-
-
-#endif
diff --git a/src/include/taler/taler-exchange/get-aml-OFFICER_PUB-accounts.h b/src/include/taler/taler-exchange/get-aml-OFFICER_PUB-accounts.h
@@ -0,0 +1,403 @@
+/*
+ This file is part of TALER
+ Copyright (C) 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/taler-exchange/get-aml-OFFICER_PUB-accounts.h
+ * @brief C interface for the GET /aml/$OFFICER_PUB/accounts endpoint
+ * @author Christian Grothoff
+ */
+#ifndef _TALER_EXCHANGE__GET_AML_OFFICER_PUB_ACCOUNTS_H
+#define _TALER_EXCHANGE__GET_AML_OFFICER_PUB_ACCOUNTS_H
+
+#include <taler/taler-exchange/common.h>
+
+/**
+ * Possible options we can set for the GET accounts request.
+ */
+enum TALER_EXCHANGE_GetAmlAccountsOption
+{
+ /**
+ * End of list of options.
+ */
+ TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_END = 0,
+
+ /**
+ * Return at most N values, default is -20 to return
+ * the last 20 entries before start. Negative values
+ * to return before limit, positive to return after limit.
+ */
+ TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_LIMIT,
+
+ /**
+ * Row number threshold, defaults to INT64_MAX, namely
+ * the biggest row id possible in the database.
+ */
+ TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_OFFSET,
+
+ /**
+ * If set to #TALER_EXCHANGE_YNA_YES, only return accounts under
+ * AML investigation, #TALER_EXCHANGE_YNA_NO for accounts not
+ * under investigation, #TALER_EXCHANGE_YNA_ALL for all. Default is all.
+ */
+ TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_INVESTIGATION,
+
+ /**
+ * If set to #TALER_EXCHANGE_YNA_YES, only return accounts that are open
+ * (crossed some initial limit and have custom rules),
+ * #TALER_EXCHANGE_YNA_ALL for all. Default is all.
+ */
+ TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_OPEN,
+
+ /**
+ * If set to #TALER_EXCHANGE_YNA_YES, only return accounts flagged as
+ * high risk, #TALER_EXCHANGE_YNA_ALL for all. Default is all.
+ */
+ TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_HIGH_RISK
+
+};
+
+
+/**
+ * Value for an option for the GET accounts request.
+ */
+struct TALER_EXCHANGE_GetAmlAccountsOptionValue
+{
+
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_GetAmlAccountsOption option;
+
+ /**
+ * Specific option value.
+ */
+ union
+ {
+
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_LIMIT.
+ */
+ int64_t limit;
+
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_OFFSET.
+ * Note that in practice the maximum value is INT64_MAX, even though
+ * this value is unsigned.
+ */
+ uint64_t offset;
+
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_INVESTIGATION.
+ */
+ enum TALER_EXCHANGE_YesNoAll investigation;
+
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_OPEN.
+ */
+ enum TALER_EXCHANGE_YesNoAll open;
+
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_HIGH_RISK.
+ */
+ enum TALER_EXCHANGE_YesNoAll high_risk;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to GET /aml/$OFFICER_PUB/accounts.
+ */
+struct TALER_EXCHANGE_GetAmlAccountsHandle;
+
+
+/**
+ * Set up GET /aml/$OPUB/accounts operation.
+ * Note that you must explicitly start the operation after
+ * possibly setting options.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param officer_priv private key of the officer
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetAmlAccountsHandle *
+TALER_EXCHANGE_get_aml_accounts_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_AmlOfficerPrivateKeyP *officer_priv);
+
+
+/**
+ * Terminate the list of the options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_GetAmlAccountsOptionValue
+ */
+#define TALER_EXCHANGE_get_aml_accounts_option_end_() \
+ (const struct TALER_EXCHANGE_GetAmlAccountsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_END \
+ }
+
+/**
+ * Set limit @a l on the number of results to return.
+ *
+ * @param l limit on the number of results to return
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlAccountsOptionValue
+ */
+#define TALER_EXCHANGE_get_aml_accounts_option_limit(l) \
+ (const struct TALER_EXCHANGE_GetAmlAccountsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_LIMIT, \
+ .details.limit = (l) \
+ }
+
+/**
+ * Set row offset from which to return results.
+ *
+ * @param o offset to use
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlAccountsOptionValue
+ */
+#define TALER_EXCHANGE_get_aml_accounts_option_offset(o) \
+ (const struct TALER_EXCHANGE_GetAmlAccountsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_OFFSET, \
+ .details.offset = (o) \
+ }
+
+/**
+ * Set filter on investigation status.
+ *
+ * @param i investigation filter to use
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlAccountsOptionValue
+ */
+#define TALER_EXCHANGE_get_aml_accounts_option_filter_investigation(i) \
+ (const struct TALER_EXCHANGE_GetAmlAccountsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_INVESTIGATION, \
+ .details.investigation = (i) \
+ }
+
+/**
+ * Set filter on open status.
+ *
+ * @param o open filter to use
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlAccountsOptionValue
+ */
+#define TALER_EXCHANGE_get_aml_accounts_option_filter_open(o) \
+ (const struct TALER_EXCHANGE_GetAmlAccountsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_OPEN, \
+ .details.open = (o) \
+ }
+
+/**
+ * Set filter on high-risk status.
+ *
+ * @param r high-risk filter to use
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlAccountsOptionValue
+ */
+#define TALER_EXCHANGE_get_aml_accounts_option_filter_high_risk(r) \
+ (const struct TALER_EXCHANGE_GetAmlAccountsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_ACCOUNTS_OPTION_HIGH_RISK, \
+ .details.high_risk = (r) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fail other options may be or may be not applied.
+ *
+ * @param aah the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_get_aml_accounts_set_options_ (
+ struct TALER_EXCHANGE_GetAmlAccountsHandle *aah,
+ unsigned int num_options,
+ const struct TALER_EXCHANGE_GetAmlAccountsOptionValue *options);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fail other options may be or may be not applied.
+ *
+ * It should be used with helpers that create required options, for example:
+ *
+ * TALER_EXCHANGE_get_aml_accounts_set_options (
+ * aah,
+ * TALER_EXCHANGE_get_aml_accounts_option_filter_investigation (
+ * TALER_EXCHANGE_YNA_YES));
+ *
+ * @param aah the request to set the options for
+ * @param ... the list of the options, each option must be created
+ * by helpers TALER_EXCHANGE_get_aml_accounts_option_NAME(VALUE)
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_get_aml_accounts_set_options(aah,...) \
+ TALER_EXCHANGE_get_aml_accounts_set_options_ ( \
+ aah, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_GetAmlAccountsOptionValue[]) \
+ {__VA_ARGS__, TALER_EXCHANGE_get_aml_accounts_option_end_ () } \
+ ))
+
+
+/**
+ * Summary information about a customer account.
+ */
+struct TALER_EXCHANGE_GetAmlAccountsAccountSummary
+{
+ /**
+ * Hash of the normalized payto:// URI of the account.
+ */
+ struct TALER_NormalizedPaytoHashP h_payto;
+
+ /**
+ * Full payto:// URI of the account.
+ */
+ const char *full_payto;
+
+ /**
+ * True if the account was assessed as being high risk.
+ */
+ bool high_risk;
+
+ /**
+ * Latest comments about the account. Can be NULL.
+ */
+ const char *comments;
+
+ /**
+ * Row of the account in the exchange tables. Useful to filter by offset.
+ */
+ uint64_t rowid;
+
+ /**
+ * When was the account opened? Zero if it was never opened.
+ */
+ struct GNUNET_TIME_Timestamp open_time;
+
+ /**
+ * When was the account closed? Zero if it was never closed.
+ */
+ struct GNUNET_TIME_Timestamp close_time;
+
+ /**
+ * True if the account is under investigation by AML staff.
+ */
+ bool to_investigate;
+};
+
+
+/**
+ * Information returned from the exchange for a
+ * GET /aml/$OFFICER_PUB/accounts request.
+ */
+struct TALER_EXCHANGE_GetAmlAccountsResponse
+{
+ /**
+ * HTTP response data
+ */
+ struct TALER_EXCHANGE_HttpResponse hr;
+
+ /**
+ * Details depending on the HTTP status code.
+ */
+ union
+ {
+
+ /**
+ * Details on #MHD_HTTP_OK.
+ */
+ struct
+ {
+ /**
+ * Length of the @e accounts array.
+ */
+ size_t accounts_length;
+
+ /**
+ * Array of customer account summaries.
+ */
+ const struct TALER_EXCHANGE_GetAmlAccountsAccountSummary *accounts;
+
+ } ok;
+
+ } details;
+};
+
+
+#ifndef TALER_EXCHANGE_GET_AML_ACCOUNTS_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetAmlAccountsCallback.
+ */
+#define TALER_EXCHANGE_GET_AML_ACCOUNTS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_AML_ACCOUNTS_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * GET /aml/$OFFICER_PUB/accounts request.
+ *
+ * @param cls closure
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetAmlAccountsCallback)(
+ TALER_EXCHANGE_GET_AML_ACCOUNTS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetAmlAccountsResponse *result);
+
+
+/**
+ * Start GET /aml/$OPUB/accounts operation.
+ *
+ * @param[in,out] aah 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_get_aml_accounts_start (
+ struct TALER_EXCHANGE_GetAmlAccountsHandle *aah,
+ TALER_EXCHANGE_GetAmlAccountsCallback cb,
+ TALER_EXCHANGE_GET_AML_ACCOUNTS_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /aml/$OPUB/accounts operation. This function
+ * must not be called by clients after the
+ * TALER_EXCHANGE_GetAmlAccountsCallback has been invoked
+ * (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] aah operation to cancel
+ */
+void
+TALER_EXCHANGE_get_aml_accounts_cancel (
+ struct TALER_EXCHANGE_GetAmlAccountsHandle *aah);
+
+
+#endif /* _TALER_EXCHANGE__GET_AML_OFFICER_PUB_ACCOUNTS_H */
diff --git a/src/include/taler/taler-exchange/get-aml-OFFICER_PUB-kyc-statistics-NAMES.h b/src/include/taler/taler-exchange/get-aml-OFFICER_PUB-kyc-statistics-NAMES.h
@@ -1,6 +1,6 @@
/*
This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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
@@ -24,14 +24,194 @@
#include <taler/taler-exchange/common.h>
/**
- * Handle for a GET /aml/$OFFICER_PUB/kyc-statistics/$NAME request.
+ * Possible options we can set for the GET kyc-statistics request.
*/
-struct TALER_EXCHANGE_KycGetStatisticsHandle;
+enum TALER_EXCHANGE_GetAmlKycStatisticsOption
+{
+ /**
+ * End of list of options.
+ */
+ TALER_EXCHANGE_GET_AML_KYC_STATISTICS_OPTION_END = 0,
+
+ /**
+ * Start date for the statistics window (inclusive).
+ * If not set, the start time of the exchange operation is used.
+ */
+ TALER_EXCHANGE_GET_AML_KYC_STATISTICS_OPTION_START_DATE,
+
+ /**
+ * End date for the statistics window (exclusive).
+ * If not set, the current date is used.
+ */
+ TALER_EXCHANGE_GET_AML_KYC_STATISTICS_OPTION_END_DATE
+
+};
+
/**
- * Response from a GET /aml/$OFFICER_PUB/kyc-statistics request.
+ * Value for an option for the GET kyc-statistics request.
*/
-struct TALER_EXCHANGE_KycGetStatisticsResponse
+struct TALER_EXCHANGE_GetAmlKycStatisticsOptionValue
+{
+
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_GetAmlKycStatisticsOption option;
+
+ /**
+ * Specific option value.
+ */
+ union
+ {
+
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_AML_KYC_STATISTICS_OPTION_START_DATE.
+ */
+ struct GNUNET_TIME_Timestamp start_date;
+
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_AML_KYC_STATISTICS_OPTION_END_DATE.
+ */
+ struct GNUNET_TIME_Timestamp end_date;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to GET /aml/$OFFICER_PUB/kyc-statistics/$NAMES.
+ */
+struct TALER_EXCHANGE_GetAmlKycStatisticsHandle;
+
+
+/**
+ * Set up GET /aml/$OPUB/kyc-statistics/$NAMES operation.
+ * Note that you must explicitly start the operation after
+ * possibly setting options.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param officer_priv private key of the officer
+ * @param names space-separated list of event type names to count
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetAmlKycStatisticsHandle *
+TALER_EXCHANGE_get_aml_kyc_statistics_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_AmlOfficerPrivateKeyP *officer_priv,
+ const char *names);
+
+
+/**
+ * Terminate the list of the options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_GetAmlKycStatisticsOptionValue
+ */
+#define TALER_EXCHANGE_get_aml_kyc_statistics_option_end_() \
+ (const struct TALER_EXCHANGE_GetAmlKycStatisticsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_KYC_STATISTICS_OPTION_END \
+ }
+
+/**
+ * Set start date for the statistics window.
+ *
+ * @param d start date (inclusive)
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlKycStatisticsOptionValue
+ */
+#define TALER_EXCHANGE_get_aml_kyc_statistics_option_start_date(d) \
+ (const struct TALER_EXCHANGE_GetAmlKycStatisticsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_KYC_STATISTICS_OPTION_START_DATE, \
+ .details.start_date = (d) \
+ }
+
+/**
+ * Set end date for the statistics window.
+ *
+ * @param d end date (exclusive)
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlKycStatisticsOptionValue
+ */
+#define TALER_EXCHANGE_get_aml_kyc_statistics_option_end_date(d) \
+ (const struct TALER_EXCHANGE_GetAmlKycStatisticsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_KYC_STATISTICS_OPTION_END_DATE, \
+ .details.end_date = (d) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fail other options may be or may be not applied.
+ *
+ * @param aksh the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_get_aml_kyc_statistics_set_options_ (
+ struct TALER_EXCHANGE_GetAmlKycStatisticsHandle *aksh,
+ unsigned int num_options,
+ const struct TALER_EXCHANGE_GetAmlKycStatisticsOptionValue *options);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fail other options may be or may be not applied.
+ *
+ * It should be used with helpers that create required options, for example:
+ *
+ * TALER_EXCHANGE_get_aml_kyc_statistics_set_options (
+ * aksh,
+ * TALER_EXCHANGE_get_aml_kyc_statistics_option_start_date (t_start),
+ * TALER_EXCHANGE_get_aml_kyc_statistics_option_end_date (t_end));
+ *
+ * @param aksh the request to set the options for
+ * @param ... the list of the options, each option must be created
+ * by helpers TALER_EXCHANGE_get_aml_kyc_statistics_option_NAME(VALUE)
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_get_aml_kyc_statistics_set_options(aksh,...) \
+ TALER_EXCHANGE_get_aml_kyc_statistics_set_options_ ( \
+ aksh, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_GetAmlKycStatisticsOptionValue[]) \
+ {__VA_ARGS__, TALER_EXCHANGE_get_aml_kyc_statistics_option_end_ () } \
+ ))
+
+
+/**
+ * A single event counter returned for one statistic name.
+ * Since protocol v30 (rev 1), the response returns an array of these.
+ */
+struct TALER_EXCHANGE_GetAmlKycStatisticsEventCounter
+{
+ /**
+ * Name of the statistic being reported.
+ */
+ const char *name;
+
+ /**
+ * Number of events of the specified type in the given time range.
+ */
+ uint64_t counter;
+};
+
+
+/**
+ * Response from a GET /aml/$OFFICER_PUB/kyc-statistics/$NAMES request.
+ */
+struct TALER_EXCHANGE_GetAmlKycStatisticsResponse
{
/**
* HTTP response data
@@ -50,9 +230,14 @@ struct TALER_EXCHANGE_KycGetStatisticsResponse
{
/**
- * Number of events of the specified type in the given time range.
+ * Array of event counters, one per requested name.
*/
- unsigned long long counter;
+ const struct TALER_EXCHANGE_GetAmlKycStatisticsEventCounter *statistics;
+
+ /**
+ * Length of the @e statistics array.
+ */
+ size_t statistics_length;
} ok;
@@ -61,31 +246,92 @@ struct TALER_EXCHANGE_KycGetStatisticsResponse
};
+#ifndef TALER_EXCHANGE_GET_AML_KYC_STATISTICS_RESULT_CLOSURE
/**
- * Function called with information about available
- * AML statistics.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetAmlKycStatisticsCallback.
+ */
+#define TALER_EXCHANGE_GET_AML_KYC_STATISTICS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_AML_KYC_STATISTICS_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * GET /aml/$OFFICER_PUB/kyc-statistics/$NAMES request.
*
* @param cls closure
- * @param hr HTTP response data
+ * @param result result returned by the HTTP server
*/
typedef void
-(*TALER_EXCHANGE_KycStatisticsCallback) (
- void *cls,
- const struct TALER_EXCHANGE_KycGetStatisticsResponse *hr);
+(*TALER_EXCHANGE_GetAmlKycStatisticsCallback)(
+ TALER_EXCHANGE_GET_AML_KYC_STATISTICS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetAmlKycStatisticsResponse *result);
/**
- * Inform client about available AML statistics.
+ * Start GET /aml/$OPUB/kyc-statistics/$NAMES operation.
*
- * @param ctx the context
- * @param exchange_url HTTP base URL for the exchange
- * @param name name of the statistic to get
- * @param start_date specifies the start date when to start looking
- * @param end_date specifies the end date when to stop looking (exclusive)
- * @param officer_priv private key of the officer
+ * @param[in,out] aksh operation to start
* @param cb function to call with the exchange's result
* @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @return status code, #TALER_EC_NONE on success
+ */
+enum TALER_ErrorCode
+TALER_EXCHANGE_get_aml_kyc_statistics_start (
+ struct TALER_EXCHANGE_GetAmlKycStatisticsHandle *aksh,
+ TALER_EXCHANGE_GetAmlKycStatisticsCallback cb,
+ TALER_EXCHANGE_GET_AML_KYC_STATISTICS_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /aml/$OPUB/kyc-statistics/$NAMES operation. This function
+ * must not be called by clients after the
+ * TALER_EXCHANGE_GetAmlKycStatisticsCallback has been invoked
+ * (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] aksh operation to cancel
+ */
+void
+TALER_EXCHANGE_get_aml_kyc_statistics_cancel (
+ struct TALER_EXCHANGE_GetAmlKycStatisticsHandle *aksh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlKycStatisticsResponse instead.
+ * Note: the legacy API accepted only a single name and returned only
+ * a single counter; use the new API for multi-name queries.
+ */
+struct TALER_EXCHANGE_KycGetStatisticsResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ unsigned long long counter;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlKycStatisticsCallback instead.
+ */
+typedef void
+(*TALER_EXCHANGE_KycStatisticsCallback) (
+ void *cls,
+ const struct TALER_EXCHANGE_KycGetStatisticsResponse *hr);
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlKycStatisticsHandle instead.
+ */
+struct TALER_EXCHANGE_KycGetStatisticsHandle;
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_get_aml_kyc_statistics_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_KycGetStatisticsHandle *
TALER_EXCHANGE_kyc_get_statistics (
@@ -98,14 +344,11 @@ TALER_EXCHANGE_kyc_get_statistics (
TALER_EXCHANGE_KycStatisticsCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_kyc_get_statistics() operation.
- *
- * @param kgs handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_get_aml_kyc_statistics_cancel() instead.
*/
void
TALER_EXCHANGE_kyc_get_statistics_cancel (
struct TALER_EXCHANGE_KycGetStatisticsHandle *kgs);
-#endif
+#endif /* _TALER_EXCHANGE__GET_AML_OFFICER_PUB_KYC_STATISTICS_NAMES_H */
diff --git a/src/include/taler/taler-exchange/get-aml-OFFICER_PUB-legitimizations.h b/src/include/taler/taler-exchange/get-aml-OFFICER_PUB-legitimizations.h
@@ -1,6 +1,6 @@
/*
This file is part of TALER
- Copyright (C) 2025 Taler Systems SA
+ Copyright (C) 2025, 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
@@ -26,30 +26,30 @@
/**
* Possible options we can set for the GET legitimizations request.
*/
-enum TALER_EXCHANGE_AmlLegitimizationsGetOption
+enum TALER_EXCHANGE_GetAmlLegitimizationsOption
{
/**
* End of list of options.
*/
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_END = 0,
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_END = 0,
/**
* Return at most N values, default is -20 to return
* the last 20 entries before start. Negative values
* to return before limit, positive to return after limit.
*/
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_LIMIT,
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_LIMIT,
/**
* Row number threshold, defaults to INT64_MAX, namely
* the biggest row id possible in the database.
*/
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_OFFSET,
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_OFFSET,
/**
* Filter by account using a normalized payto URI hash.
*/
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_H_PAYTO,
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_H_PAYTO,
/**
* If set to #TALER_EXCHANGE_YNA_YES, only return active
@@ -57,21 +57,21 @@ enum TALER_EXCHANGE_AmlLegitimizationsGetOption
* results, #TALER_EXCHANGE_YNA_ALL, to return all
* decisions. Default is all.
*/
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_ACTIVE
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_ACTIVE
};
/**
- * Possible options we can set for the GET legitimizations request.
+ * Value for an option for the GET legitimizations request.
*/
-struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
+struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue
{
/**
* Type of the option being set.
*/
- enum TALER_EXCHANGE_AmlLegitimizationsGetOption option;
+ enum TALER_EXCHANGE_GetAmlLegitimizationsOption option;
/**
* Specific option value.
@@ -80,24 +80,24 @@ struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
{
/**
- * Value of if @e option is TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_LIMIT.
+ * Value if @e option is TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_LIMIT.
*/
int64_t limit;
/**
- * Value of if @e option is TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_OFFSET.
+ * Value if @e option is TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_OFFSET.
* Note that in practice the maximum value is INT64_MAX, even though
* this value is unsigned.
*/
uint64_t offset;
/**
- * Value of if @e option is TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_H_PAYTO.
+ * Value if @e option is TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_H_PAYTO.
*/
const struct TALER_NormalizedPaytoHashP *h_payto;
/**
- * Value of if @e option is TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_ACTIVE.
+ * Value if @e option is TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_ACTIVE.
*/
enum TALER_EXCHANGE_YesNoAll active;
@@ -109,7 +109,7 @@ struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
/**
* Handle for an operation to GET /aml/$OFFICER_PUB/legitimizations.
*/
-struct TALER_EXCHANGE_AmlLegitimizationsGetHandle;
+struct TALER_EXCHANGE_GetAmlLegitimizationsHandle;
/**
@@ -122,8 +122,8 @@ struct TALER_EXCHANGE_AmlLegitimizationsGetHandle;
* @param officer_priv private key of the officer
* @return handle to operation
*/
-struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *
-TALER_EXCHANGE_aml_legitimizations_get_create (
+struct TALER_EXCHANGE_GetAmlLegitimizationsHandle *
+TALER_EXCHANGE_get_aml_legitimizations_create (
struct GNUNET_CURL_Context *ctx,
const char *url,
const struct TALER_AmlOfficerPrivateKeyP *officer_priv);
@@ -132,25 +132,25 @@ TALER_EXCHANGE_aml_legitimizations_get_create (
/**
* Terminate the list of the options.
*
- * @return the terminating object of struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
+ * @return the terminating object of struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue
*/
-#define TALER_EXCHANGE_aml_legitimizations_get_option_end_() \
- (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_END \
+#define TALER_EXCHANGE_get_aml_legitimizations_option_end_() \
+ (const struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_END \
}
/**
* Set limit @a l on the number of results to return.
*
* @param l limit on the number of results to return
- * @return representation of the option as a struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue
*/
-#define TALER_EXCHANGE_aml_legitimizations_get_option_limit(l) \
- (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_LIMIT, \
- .details.limit = (l) \
+#define TALER_EXCHANGE_get_aml_legitimizations_option_limit(l) \
+ (const struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_LIMIT, \
+ .details.limit = (l) \
}
@@ -158,13 +158,13 @@ TALER_EXCHANGE_aml_legitimizations_get_create (
* Set row offset from which to return results.
*
* @param o offset to use
- * @return representation of the option as a struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue
*/
-#define TALER_EXCHANGE_aml_legitimizations_get_option_offset(o) \
- (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_OFFSET, \
- .details.offset = (o) \
+#define TALER_EXCHANGE_get_aml_legitimizations_option_offset(o) \
+ (const struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_OFFSET, \
+ .details.offset = (o) \
}
@@ -172,26 +172,26 @@ TALER_EXCHANGE_aml_legitimizations_get_create (
* Set filter on which account to filter legitimization measures by.
*
* @param p normalized payto URI hash of the account to filter by
- * @return representation of the option as a struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue
*/
-#define TALER_EXCHANGE_aml_legitimizations_get_option_h_payto(p) \
- (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_H_PAYTO, \
- .details.h_payto = (p) \
+#define TALER_EXCHANGE_get_aml_legitimizations_option_filter_h_payto(p) \
+ (const struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_H_PAYTO, \
+ .details.h_payto = (p) \
}
/**
* Set filter on active (or inactive) results.
*
* @param a activity filter to use
- * @return representation of the option as a struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue
*/
-#define TALER_EXCHANGE_aml_legitimizations_get_option_active(a) \
- (const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_ACTIVE, \
- .details.active = (a) \
+#define TALER_EXCHANGE_get_aml_legitimizations_option_filter_active(a) \
+ (const struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_ACTIVE, \
+ .details.active = (a) \
}
@@ -202,17 +202,16 @@ TALER_EXCHANGE_aml_legitimizations_get_create (
*
* @param algh the request to set the options for
* @param num_options length of the @a options array
- * @param options array of options, each option must be created
- * by helpers TALER_EXCHANGE_aml_legitimizations_get_option_NAME(VALUE)
+ * @param options array of options
* @return #GNUNET_OK on success,
* #GNUNET_NO on failure,
* #GNUNET_SYSERR on internal error
*/
enum GNUNET_GenericReturnValue
-TALER_EXCHANGE_aml_legitimizations_get_set_options_ (
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh,
+TALER_EXCHANGE_get_aml_legitimizations_set_options_ (
+ struct TALER_EXCHANGE_GetAmlLegitimizationsHandle *algh,
unsigned int num_options,
- const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue *options);
+ const struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue *options);
/**
@@ -220,25 +219,25 @@ TALER_EXCHANGE_aml_legitimizations_get_set_options_ (
*
* If any option fail other options may be or may be not applied.
*
- * It should be used with helpers that creates required options, for example:
+ * It should be used with helpers that create required options, for example:
*
- * TALER_EXCHANGE_aml_legitimizations_get_set_options (
+ * TALER_EXCHANGE_get_aml_legitimizations_set_options (
* algh,
- * TALER_EXCHANGE_aml_legitimizations_get_option_h_payto_(&h_payto));
+ * TALER_EXCHANGE_get_aml_legitimizations_option_filter_h_payto (&h_payto));
*
* @param algh the request to set the options for
* @param ... the list of the options, each option must be created
- * by helpers TALER_EXCHANGE_aml_legitimizations_get_option_NAME(VALUE)
+ * by helpers TALER_EXCHANGE_get_aml_legitimizations_option_NAME(VALUE)
* @return #GNUNET_OK on success,
* #GNUNET_NO on failure,
* #GNUNET_SYSERR on internal error
*/
-#define TALER_EXCHANGE_aml_legitimizations_get_set_options(algh,...) \
- TALER_EXCHANGE_aml_legitimizations_get_set_options_ ( \
- algh, \
+#define TALER_EXCHANGE_get_aml_legitimizations_set_options(algh,...) \
+ TALER_EXCHANGE_get_aml_legitimizations_set_options_ ( \
+ algh, \
TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
- ((const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue[]) \
- {__VA_ARGS__, TALER_EXCHANGE_aml_legitimizations_get_option_end_ () } \
+ ((const struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue[]) \
+ {__VA_ARGS__, TALER_EXCHANGE_get_aml_legitimizations_option_end_ () } \
))
@@ -246,7 +245,7 @@ TALER_EXCHANGE_aml_legitimizations_get_set_options_ (
* Entry in the set of legitimization measures that are returned
* by the server in a single request.
*/
-struct TALER_EXCHANGE_AmlLegitimizationsGetMeasureDetails
+struct TALER_EXCHANGE_GetAmlLegitimizationsMeasureDetails
{
/**
* Hash of the normalized payto:// URI of the account the
@@ -280,7 +279,7 @@ struct TALER_EXCHANGE_AmlLegitimizationsGetMeasureDetails
* Information returned from the exchange for a
* GET /aml/$OFFICER_PUB/legitimizations request.
*/
-struct TALER_EXCHANGE_AmlLegitimizationsGetResult
+struct TALER_EXCHANGE_GetAmlLegitimizationsResponse
{
/**
* HTTP response data
@@ -306,7 +305,7 @@ struct TALER_EXCHANGE_AmlLegitimizationsGetResult
/**
* Legitimization measures.
*/
- const struct TALER_EXCHANGE_AmlLegitimizationsGetMeasureDetails *measures;
+ const struct TALER_EXCHANGE_GetAmlLegitimizationsMeasureDetails *measures;
} ok;
@@ -314,13 +313,13 @@ struct TALER_EXCHANGE_AmlLegitimizationsGetResult
};
-#ifndef TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE
+#ifndef TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_RESULT_CLOSURE
/**
* Type of the closure used by
- * the #TALER_EXCHANGE_AmlLegitimizationsGetCallback.
+ * the #TALER_EXCHANGE_GetAmlLegitimizationsCallback.
*/
-#define TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE void
-#endif /* _TALER_EXCHANGE__GET_AML_OFFICER_PUB_LEGITIMIZATIONS_H */
+#define TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_RESULT_CLOSURE */
/**
* Type of the function that receives the result of a
@@ -330,9 +329,9 @@ struct TALER_EXCHANGE_AmlLegitimizationsGetResult
* @param result result returned by the HTTP server
*/
typedef void
-(*TALER_EXCHANGE_AmlLegitimizationsGetCallback)(
- TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE *cls,
- const struct TALER_EXCHANGE_AmlLegitimizationsGetResult *result);
+(*TALER_EXCHANGE_GetAmlLegitimizationsCallback)(
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetAmlLegitimizationsResponse *result);
/**
@@ -341,37 +340,41 @@ typedef void
* @param[in,out] algh operation to start
* @param cb function to call with the exchange's result
* @param cb_cls closure for @a cb
- * @return status code
+ * @return status code, #TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_START_OK on success
*/
enum TALER_EXCHANGE_AmlLegitimizationsGetStartError
{
/**
* Success.
*/
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_OK = 0,
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_START_OK = 0,
/**
* Only allowed to be started once.
*/
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_E_AGAIN = 1,
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_START_E_AGAIN = 1,
/**
* Internal logic failure.
*/
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_E_INTERNAL = 2,
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_START_E_INTERNAL = 2,
}
-TALER_EXCHANGE_aml_legitimizations_get_start (
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh,
- TALER_EXCHANGE_AmlLegitimizationsGetCallback cb,
- TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE * cb_cls);
+TALER_EXCHANGE_get_aml_legitimizations_start (
+ struct TALER_EXCHANGE_GetAmlLegitimizationsHandle *algh,
+ TALER_EXCHANGE_GetAmlLegitimizationsCallback cb,
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_RESULT_CLOSURE * cb_cls);
/**
- * Cancel GET /aml/$OPUB/legitimizations operation.
+ * Cancel GET /aml/$OPUB/legitimizations operation. This function
+ * must not be called by clients after the
+ * TALER_EXCHANGE_GetAmlLegitimizationsCallback has been invoked
+ * (as in those cases it'll be called internally by the
+ * implementation already).
*
* @param[in] algh operation to cancel
*/
void
-TALER_EXCHANGE_aml_legitimizations_get_cancel (
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh);
+TALER_EXCHANGE_get_aml_legitimizations_cancel (
+ struct TALER_EXCHANGE_GetAmlLegitimizationsHandle *algh);
#endif /* _TALER_EXCHANGE__GET_AML_OFFICER_PUB_LEGITIMIZATIONS_H */
diff --git a/src/include/taler/taler-exchange/get-aml-OFFICER_PUB-measures.h b/src/include/taler/taler-exchange/get-aml-OFFICER_PUB-measures.h
@@ -1,6 +1,6 @@
/*
This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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
@@ -24,18 +24,19 @@
#include <taler/taler-exchange/common.h>
/**
- * @brief Handle for a GET /aml/$OFFICER_PUB/measures request.
+ * Handle for an operation to GET /aml/$OFFICER_PUB/measures.
*/
-struct TALER_EXCHANGE_AmlGetMeasuresHandle;
+struct TALER_EXCHANGE_GetAmlMeasuresHandle;
/**
- * Information about a root measures available at the exchange
+ * Information about a root measure available at the exchange.
+ * Corresponds to a MeasureInformation object in AvailableMeasureSummary.
*/
-struct TALER_EXCHANGE_AvailableAmlMeasures
+struct TALER_EXCHANGE_GetAmlMeasuresMeasureInfo
{
/**
- * Name of the measure.
+ * Name of the measure (map key in the response).
*/
const char *measure_name;
@@ -45,7 +46,8 @@ struct TALER_EXCHANGE_AvailableAmlMeasures
const char *check_name;
/**
- * Name of the AML program.
+ * Name of the AML program. Can be NULL.
+ * Since protocol v30.
*/
const char *prog_name;
@@ -53,16 +55,29 @@ struct TALER_EXCHANGE_AvailableAmlMeasures
* Context for the check. Can be NULL.
*/
const json_t *context;
+
+ /**
+ * Operation that this measure relates to. Can be NULL if unknown.
+ * Since protocol v21.
+ */
+ const char *operation_type;
+
+ /**
+ * True if this measure can be undertaken voluntarily.
+ * Since protocol vATTEST.
+ */
+ bool voluntary;
};
+
/**
- * Information about an AML programs available at the exchange
+ * Information about an AML program available at the exchange.
+ * Corresponds to an AmlProgramRequirement object.
*/
-struct TALER_EXCHANGE_AvailableAmlPrograms
+struct TALER_EXCHANGE_GetAmlMeasuresProgramRequirement
{
-
/**
- * Name of the AML program.
+ * Name of the AML program (map key in the response).
*/
const char *prog_name;
@@ -72,39 +87,35 @@ struct TALER_EXCHANGE_AvailableAmlPrograms
const char *description;
/**
- * Array of required field names in the context to run this AML program. SPA
- * must check that the AML staff is providing adequate CONTEXT when defining
- * a measure using this program.
+ * Array of required field names in the context to run this AML program.
*/
const char **contexts;
/**
- * List of required attribute names in the input of this AML program. These
- * attributes are the minimum that the check must produce (it may produce
- * more).
+ * Length of the @e contexts array.
*/
- const char **inputs;
+ size_t contexts_length;
/**
- * Length of the @e contexts array.
+ * Array of required attribute names in the input of this AML program.
*/
- unsigned int contexts_length;
+ const char **inputs;
/**
* Length of the @e inputs array.
*/
- unsigned int inputs_length;
+ size_t inputs_length;
};
/**
- * Information about a KYC check available at the exchange
+ * Information about a KYC check available at the exchange.
+ * Corresponds to a KycCheckInformation object.
*/
-struct TALER_EXCHANGE_AvailableKycChecks
+struct TALER_EXCHANGE_GetAmlMeasuresCheckInfo
{
-
/**
- * Name of the KYC check.
+ * Name of the KYC check (map key in the response).
*/
const char *check_name;
@@ -114,7 +125,7 @@ struct TALER_EXCHANGE_AvailableKycChecks
const char *description;
/**
- * Internationalized description of the KYC check.
+ * Internationalized description of the KYC check. Can be NULL.
*/
const json_t *description_i18n;
@@ -124,35 +135,88 @@ struct TALER_EXCHANGE_AvailableKycChecks
const char *fallback;
/**
- * Array with the names of the fields that the CONTEXT must provide as
- * inputs to this check. SPA must check that the AML staff is providing
- * adequate CONTEXT when defining a measure using this check.
+ * Array with the names of the fields that CONTEXT must provide as inputs
+ * to this check.
*/
const char **requires;
/**
- * Array of the attributes names the check will output. SPA must check that
- * the outputs match the required inputs when combining a KYC check with an
- * AML program into a measure.
+ * Length of the @e requires array.
+ */
+ size_t requires_length;
+
+ /**
+ * Array of attribute names the check will output.
*/
const char **outputs;
/**
- * Length of the @e requires array.
+ * Length of the @e outputs array.
*/
- unsigned int requires_length;
+ size_t outputs_length;
+};
+
+/**
+ * A KYC rule from the default rule set.
+ * Corresponds to a KycRule object in default_rules.
+ * Since protocol v28.
+ */
+struct TALER_EXCHANGE_GetAmlMeasuresKycRule
+{
/**
- * Length of the @e outputs array.
+ * Type of operation to which the rule applies.
*/
- unsigned int outputs_length;
+ enum TALER_KYCLOGIC_KycTriggerEvent operation_type;
+
+ /**
+ * Name of the configuration section this rule originates from.
+ * Can be NULL.
+ */
+ const char *rule_name;
+
+ /**
+ * The threshold amount that triggers the measures.
+ */
+ struct TALER_Amount threshold;
+
+ /**
+ * Over which duration should the threshold be computed.
+ */
+ struct GNUNET_TIME_Relative timeframe;
+
+ /**
+ * Length of the @e measures array.
+ */
+ size_t measures_length;
+
+ /**
+ * Array of names of measures to apply.
+ */
+ const char **measures;
+
+ /**
+ * Display priority for this rule.
+ */
+ int64_t display_priority;
+
+ /**
+ * True if the rule should be exposed to the client.
+ */
+ bool exposed;
+
+ /**
+ * True if all measures need to be satisfied (AND combinator),
+ * false if any measure is sufficient (OR combinator).
+ */
+ bool is_and_combinator;
};
/**
* Response from a GET /aml/$OFFICER_PUB/measures request.
*/
-struct TALER_EXCHANGE_AmlGetMeasuresResponse
+struct TALER_EXCHANGE_GetAmlMeasuresResponse
{
/**
* HTTP response data
@@ -170,34 +234,45 @@ struct TALER_EXCHANGE_AmlGetMeasuresResponse
struct
{
/**
- * Information about the root measures available at the exchange
+ * Available root measures. Length in @e roots_length.
*/
- const struct TALER_EXCHANGE_AvailableAmlMeasures *roots;
+ const struct TALER_EXCHANGE_GetAmlMeasuresMeasureInfo *roots;
/**
- * Information about the AML programs available at the exchange
+ * Length of the @e roots array.
*/
- const struct TALER_EXCHANGE_AvailableAmlPrograms *programs;
+ size_t roots_length;
/**
- * Information about KYC checks available at the exchange
+ * Available AML programs. Length in @e programs_length.
*/
- const struct TALER_EXCHANGE_AvailableKycChecks *checks;
+ const struct TALER_EXCHANGE_GetAmlMeasuresProgramRequirement *programs;
/**
- * Length of the @e roots array.
+ * Length of the @e programs array.
*/
- unsigned int roots_length;
+ size_t programs_length;
/**
- * Length of the @e programs array.
+ * Available KYC checks. Length in @e checks_length.
*/
- unsigned int programs_length;
+ const struct TALER_EXCHANGE_GetAmlMeasuresCheckInfo *checks;
/**
* Length of the @e checks array.
*/
- unsigned int checks_length;
+ size_t checks_length;
+
+ /**
+ * Default KYC rules applied to new accounts.
+ * Since protocol v28.
+ */
+ const struct TALER_EXCHANGE_GetAmlMeasuresKycRule *default_rules;
+
+ /**
+ * Length of the @e default_rules array.
+ */
+ size_t default_rules_length;
} ok;
} details;
@@ -205,28 +280,150 @@ struct TALER_EXCHANGE_AmlGetMeasuresResponse
};
+#ifndef TALER_EXCHANGE_GET_AML_MEASURES_RESULT_CLOSURE
/**
- * Function called with information about available
- * AML measures.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetAmlMeasuresCallback.
+ */
+#define TALER_EXCHANGE_GET_AML_MEASURES_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_AML_MEASURES_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * GET /aml/$OFFICER_PUB/measures request.
*
* @param cls closure
- * @param hr HTTP response data
+ * @param result result returned by the HTTP server
*/
typedef void
-(*TALER_EXCHANGE_AmlMeasuresCallback) (
- void *cls,
- const struct TALER_EXCHANGE_AmlGetMeasuresResponse *hr);
+(*TALER_EXCHANGE_GetAmlMeasuresCallback)(
+ TALER_EXCHANGE_GET_AML_MEASURES_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetAmlMeasuresResponse *result);
/**
- * Inform client about available AML measures.
+ * Set up GET /aml/$OPUB/measures operation.
+ * Note that you must explicitly start the operation after setup.
*
* @param ctx the context
- * @param url HTTP base URL for the exchange
+ * @param url base URL of the exchange
* @param officer_priv private key of the officer
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetAmlMeasuresHandle *
+TALER_EXCHANGE_get_aml_measures_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_AmlOfficerPrivateKeyP *officer_priv);
+
+
+/**
+ * Start GET /aml/$OPUB/measures operation.
+ *
+ * @param[in,out] amh operation to start
* @param cb function to call with the exchange's result
* @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @return status code, #TALER_EC_NONE on success
+ */
+enum TALER_ErrorCode
+TALER_EXCHANGE_get_aml_measures_start (
+ struct TALER_EXCHANGE_GetAmlMeasuresHandle *amh,
+ TALER_EXCHANGE_GetAmlMeasuresCallback cb,
+ TALER_EXCHANGE_GET_AML_MEASURES_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /aml/$OPUB/measures operation. This function
+ * must not be called by clients after the
+ * TALER_EXCHANGE_GetAmlMeasuresCallback has been invoked
+ * (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] amh operation to cancel
+ */
+void
+TALER_EXCHANGE_get_aml_measures_cancel (
+ struct TALER_EXCHANGE_GetAmlMeasuresHandle *amh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlMeasuresMeasureInfo instead.
+ */
+struct TALER_EXCHANGE_AvailableAmlMeasures
+{
+ const char *measure_name;
+ const char *check_name;
+ const char *prog_name;
+ const json_t *context;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlMeasuresProgramRequirement instead.
+ */
+struct TALER_EXCHANGE_AvailableAmlPrograms
+{
+ const char *prog_name;
+ const char *description;
+ const char **contexts;
+ const char **inputs;
+ unsigned int contexts_length;
+ unsigned int inputs_length;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlMeasuresCheckInfo instead.
+ */
+struct TALER_EXCHANGE_AvailableKycChecks
+{
+ const char *check_name;
+ const char *description;
+ const json_t *description_i18n;
+ const char *fallback;
+ const char **requires;
+ const char **outputs;
+ unsigned int requires_length;
+ unsigned int outputs_length;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlMeasuresResponse instead.
+ */
+struct TALER_EXCHANGE_AmlGetMeasuresResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ const struct TALER_EXCHANGE_AvailableAmlMeasures *roots;
+ const struct TALER_EXCHANGE_AvailableAmlPrograms *programs;
+ const struct TALER_EXCHANGE_AvailableKycChecks *checks;
+ unsigned int roots_length;
+ unsigned int programs_length;
+ unsigned int checks_length;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlMeasuresCallback instead.
+ */
+typedef void
+(*TALER_EXCHANGE_AmlMeasuresCallback) (
+ void *cls,
+ const struct TALER_EXCHANGE_AmlGetMeasuresResponse *hr);
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlMeasuresHandle instead.
+ */
+struct TALER_EXCHANGE_AmlGetMeasuresHandle;
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_get_aml_measures_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_AmlGetMeasuresHandle *
TALER_EXCHANGE_aml_get_measures (
@@ -236,14 +433,11 @@ TALER_EXCHANGE_aml_get_measures (
TALER_EXCHANGE_AmlMeasuresCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_aml_get_measures() operation.
- *
- * @param agml handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_get_aml_measures_cancel() instead.
*/
void
TALER_EXCHANGE_aml_get_measures_cancel (
struct TALER_EXCHANGE_AmlGetMeasuresHandle *agml);
-#endif
+#endif /* _TALER_EXCHANGE__GET_AML_OFFICER_PUB_MEASURES_H */
diff --git a/src/include/taler/taler-exchange/get-aml-OFFICER_PUB-transfers-credit.h b/src/include/taler/taler-exchange/get-aml-OFFICER_PUB-transfers-credit.h
@@ -1,6 +1,6 @@
/*
This file is part of TALER
- Copyright (C) 2025 Taler Systems SA
+ Copyright (C) 2025, 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
@@ -15,7 +15,7 @@
*/
/**
* @file include/taler/taler-exchange/get-aml-OFFICER_PUB-transfers-credit.h
- * @brief C interface for the GET /aml/$OFFICER_PUB/transfers-kycauth endpoint
+ * @brief C interface for the GET /aml/$OFFICER_PUB/transfers-{credit,debit,kycauth} endpoints
* @author Christian Grothoff
*/
#ifndef _TALER_EXCHANGE__GET_AML_OFFICER_PUB_TRANSFERS_CREDIT_H
@@ -24,52 +24,53 @@
#include <taler/taler-exchange/common.h>
/**
- * Possible options we can set for the GET transfers-kycauth request.
+ * Possible options we can set for the GET transfers request.
*/
-enum TALER_EXCHANGE_AmlTransfersKycauthGetOption
+enum TALER_EXCHANGE_GetAmlTransfersOption
{
/**
* End of list of options.
*/
- TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_END = 0,
+ TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_END = 0,
/**
* Minimum amount threshold to return. All amounts below
* the given threshold will be filtered.
*/
- TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_THRESHOLD,
+ TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_THRESHOLD,
/**
* Return at most N values, default is -20 to return
* the last 20 entries before start. Negative values
* to return before limit, positive to return after limit.
*/
- TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_LIMIT,
+ TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_LIMIT,
/**
* Row number threshold, defaults to INT64_MAX, namely
* the biggest row id possible in the database.
*/
- TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_OFFSET,
+ TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_OFFSET,
/**
* Filter by account using a normalized payto URI hash.
+ * Since protocol v29.
*/
- TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_H_PAYTO
+ TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_H_PAYTO
};
/**
- * Possible options we can set for the GET transfers-kycauth request.
+ * Value for an option for the GET transfers request.
*/
-struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
+struct TALER_EXCHANGE_GetAmlTransfersOptionValue
{
/**
* Type of the option being set.
*/
- enum TALER_EXCHANGE_AmlTransfersKycauthGetOption option;
+ enum TALER_EXCHANGE_GetAmlTransfersOption option;
/**
* Specific option value.
@@ -78,24 +79,24 @@ struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
{
/**
- * Value of if @e option is TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_THRESHOLD.
+ * Value if @e option is TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_THRESHOLD.
*/
const struct TALER_Amount *threshold;
/**
- * Value of if @e option is TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_LIMIT.
+ * Value if @e option is TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_LIMIT.
*/
int64_t limit;
/**
- * Value of if @e option is TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_OFFSET.
+ * Value if @e option is TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_OFFSET.
* Note that in practice the maximum value is INT64_MAX, even though
* this value is unsigned.
*/
uint64_t offset;
/**
- * Value of if @e option is TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_H_PAYTO.
+ * Value if @e option is TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_H_PAYTO.
*/
const struct TALER_NormalizedPaytoHashP *h_payto;
@@ -105,9 +106,43 @@ struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
/**
- * Handle for an operation to GET /aml/$OFFICER_PUB/transfers-kycauth.
+ * Handle for an operation to GET /aml/$OFFICER_PUB/transfers-{credit,debit,kycauth}.
*/
-struct TALER_EXCHANGE_AmlTransfersKycauthGetHandle;
+struct TALER_EXCHANGE_GetAmlTransfersHandle;
+
+
+/**
+ * Set up GET /aml/$OPUB/transfers-credit operation.
+ * Note that you must explicitly start the operation after
+ * possibly setting options.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param officer_priv private key of the officer
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetAmlTransfersHandle *
+TALER_EXCHANGE_get_aml_transfers_credit_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_AmlOfficerPrivateKeyP *officer_priv);
+
+
+/**
+ * Set up GET /aml/$OPUB/transfers-debit operation.
+ * Note that you must explicitly start the operation after
+ * possibly setting options.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param officer_priv private key of the officer
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetAmlTransfersHandle *
+TALER_EXCHANGE_get_aml_transfers_debit_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_AmlOfficerPrivateKeyP *officer_priv);
/**
@@ -120,8 +155,8 @@ struct TALER_EXCHANGE_AmlTransfersKycauthGetHandle;
* @param officer_priv private key of the officer
* @return handle to operation
*/
-struct TALER_EXCHANGE_AmlTransfersKycauthGetHandle *
-TALER_EXCHANGE_aml_transfers_kycauth_get_create (
+struct TALER_EXCHANGE_GetAmlTransfersHandle *
+TALER_EXCHANGE_get_aml_transfers_kycauth_create (
struct GNUNET_CURL_Context *ctx,
const char *url,
const struct TALER_AmlOfficerPrivateKeyP *officer_priv);
@@ -130,38 +165,38 @@ TALER_EXCHANGE_aml_transfers_kycauth_get_create (
/**
* Terminate the list of the options.
*
- * @return the terminating object of struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
+ * @return the terminating object of struct TALER_EXCHANGE_GetAmlTransfersOptionValue
*/
-#define TALER_EXCHANGE_aml_transfers_kycauth_get_option_end_() \
- (const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_END \
+#define TALER_EXCHANGE_get_aml_transfers_option_end_() \
+ (const struct TALER_EXCHANGE_GetAmlTransfersOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_END \
}
/**
* Set minimum amount threshold @a t for transfers to return.
*
* @param t minimum amount threshold
- * @return representation of the option as a struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlTransfersOptionValue
*/
-#define TALER_EXCHANGE_aml_transfers_kycauth_get_option_threshold(t) \
- (const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_THRESHOLD, \
- .details.threshold = (t) \
+#define TALER_EXCHANGE_get_aml_transfers_option_threshold(t) \
+ (const struct TALER_EXCHANGE_GetAmlTransfersOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_THRESHOLD, \
+ .details.threshold = (t) \
}
/**
* Set limit @a l on the number of results to return.
*
* @param l limit on the number of results to return
- * @return representation of the option as a struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlTransfersOptionValue
*/
-#define TALER_EXCHANGE_aml_transfers_kycauth_get_option_limit(l) \
- (const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_LIMIT, \
- .details.limit = (l) \
+#define TALER_EXCHANGE_get_aml_transfers_option_limit(l) \
+ (const struct TALER_EXCHANGE_GetAmlTransfersOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_LIMIT, \
+ .details.limit = (l) \
}
@@ -169,13 +204,13 @@ TALER_EXCHANGE_aml_transfers_kycauth_get_create (
* Set row offset from which to return results.
*
* @param o offset to use
- * @return representation of the option as a struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlTransfersOptionValue
*/
-#define TALER_EXCHANGE_aml_transfers_kycauth_get_option_offset(o) \
- (const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_OFFSET, \
- .details.offset = (o) \
+#define TALER_EXCHANGE_get_aml_transfers_option_offset(o) \
+ (const struct TALER_EXCHANGE_GetAmlTransfersOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_OFFSET, \
+ .details.offset = (o) \
}
@@ -183,13 +218,13 @@ TALER_EXCHANGE_aml_transfers_kycauth_get_create (
* Set filter on which account to filter transfers by.
*
* @param p normalized payto URI hash of the account to filter by
- * @return representation of the option as a struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue
+ * @return representation of the option as a struct TALER_EXCHANGE_GetAmlTransfersOptionValue
*/
-#define TALER_EXCHANGE_aml_transfers_kycauth_get_option_h_payto(p) \
- (const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue) \
- { \
- .option = TALER_EXCHANGE_AML_TRANSFERS_KYCAUTH_GET_OPTION_H_PAYTO, \
- .details.h_payto = (p) \
+#define TALER_EXCHANGE_get_aml_transfers_option_filter_h_payto(p) \
+ (const struct TALER_EXCHANGE_GetAmlTransfersOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_AML_TRANSFERS_OPTION_H_PAYTO, \
+ .details.h_payto = (p) \
}
@@ -198,7 +233,7 @@ TALER_EXCHANGE_aml_transfers_kycauth_get_create (
*
* If any option fail other options may be or may be not applied.
*
- * @param atkgh the request to set the options for
+ * @param atgh the request to set the options for
* @param num_options length of the @a options array
* @param options an array of options
* @return #GNUNET_OK on success,
@@ -206,10 +241,10 @@ TALER_EXCHANGE_aml_transfers_kycauth_get_create (
* #GNUNET_SYSERR on internal error
*/
enum GNUNET_GenericReturnValue
-TALER_EXCHANGE_aml_transfers_kycauth_get_set_options_ (
- struct TALER_EXCHANGE_AmlTransfersKycauthGetHandle *atkgh,
+TALER_EXCHANGE_get_aml_transfers_set_options_ (
+ struct TALER_EXCHANGE_GetAmlTransfersHandle *atgh,
unsigned int num_options,
- const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue *options);
+ const struct TALER_EXCHANGE_GetAmlTransfersOptionValue *options);
/**
@@ -217,32 +252,33 @@ TALER_EXCHANGE_aml_transfers_kycauth_get_set_options_ (
*
* If any option fail other options may be or may be not applied.
*
- * It should be used with helpers that creates required options, for example:
+ * It should be used with helpers that create required options, for example:
*
- * TALER_EXCHANGE_aml_transfers_kycauth_get_set_options (
- * atkgh,
- * TALER_EXCHANGE_aml_transfers_kycauth_get_option_h_payto_(&h_payto));
+ * TALER_EXCHANGE_get_aml_transfers_set_options (
+ * atgh,
+ * TALER_EXCHANGE_get_aml_transfers_option_filter_h_payto (&h_payto));
*
- * @param atkgh the request to set the options for
+ * @param atgh the request to set the options for
* @param ... the list of the options, each option must be created
- * by helpers TALER_EXCHANGE_aml_transfers_kycauth_get_option_NAME(VALUE)
- * @return ::TALER_EC_NONE on success,
- * error code otherwise
+ * by helpers TALER_EXCHANGE_get_aml_transfers_option_NAME(VALUE)
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
*/
-#define TALER_EXCHANGE_aml_transfers_kycauth_get_set_options(atkgh,...) \
- TALER_EXCHANGE_aml_transfers_kycauth_get_set_options_ ( \
- atkgh, \
- TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
- ((const struct TALER_EXCHANGE_AmlTransfersKycauthGetOptionValue[]) \
- {__VA_ARGS__, TALER_EXCHANGE_aml_transfers_kycauth_get_option_end_ () \
- })
+#define TALER_EXCHANGE_get_aml_transfers_set_options(atgh,...) \
+ TALER_EXCHANGE_get_aml_transfers_set_options_ ( \
+ atgh, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_GetAmlTransfersOptionValue[]) \
+ {__VA_ARGS__, TALER_EXCHANGE_get_aml_transfers_option_end_ () } \
+ ))
/**
* Entry in the set of transfers that are returned
* by the server in a single request.
*/
-struct TALER_EXCHANGE_AmlTransfersKycauthGetTransferEntry
+struct TALER_EXCHANGE_GetAmlTransfersEntry
{
/**
* Row ID of the record. Used to filter by offset.
@@ -267,9 +303,9 @@ struct TALER_EXCHANGE_AmlTransfersKycauthGetTransferEntry
/**
* Information returned from the exchange for a
- * GET /aml/$OFFICER_PUB/transfers-kycauth request.
+ * GET /aml/$OFFICER_PUB/transfers-{credit,debit,kycauth} request.
*/
-struct TALER_EXCHANGE_AmlTransfersKycauthGetResult
+struct TALER_EXCHANGE_GetAmlTransfersResponse
{
/**
* HTTP response data
@@ -295,8 +331,7 @@ struct TALER_EXCHANGE_AmlTransfersKycauthGetResult
/**
* Matching transactions of the exchange.
*/
- const struct TALER_EXCHANGE_AmlTransfersKycauthGetTransferEntry *
- transfers;
+ const struct TALER_EXCHANGE_GetAmlTransfersEntry *transfers;
} ok;
@@ -304,45 +339,118 @@ struct TALER_EXCHANGE_AmlTransfersKycauthGetResult
};
-#ifndef TALER_EXCHANGE__AML_TRANSFERS_KYCAUTH_GET_RESULT_CLOSURE
+#ifndef TALER_EXCHANGE_GET_AML_TRANSFERS_RESULT_CLOSURE
/**
* Type of the closure used by
- * the #TALER_EXCHANGE_AmlTransfersKycauthGetCallback.
+ * the #TALER_EXCHANGE_GetAmlTransfersCallback.
*/
-#define TALER_EXCHANGE__AML_TRANSFERS_KYCAUTH_GET_RESULT_CLOSURE void
-#endif /* _TALER_EXCHANGE__GET_AML_OFFICER_PUB_TRANSFERS_CREDIT_H */
+#define TALER_EXCHANGE_GET_AML_TRANSFERS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_AML_TRANSFERS_RESULT_CLOSURE */
/**
* Type of the function that receives the result of a
- * GET /aml/$OFFICER_PUB/transfers-kycauth request.
+ * GET /aml/$OFFICER_PUB/transfers-{credit,debit,kycauth} request.
*
* @param cls closure
* @param result result returned by the HTTP server
*/
typedef void
-(*TALER_EXCHANGE_AmlTransfersKycauthGetCallback)(
- TALER_EXCHANGE__AML_TRANSFERS_KYCAUTH_GET_RESULT_CLOSURE *cls,
- const struct TALER_EXCHANGE_AmlTransfersKycauthGetResult *result);
+(*TALER_EXCHANGE_GetAmlTransfersCallback)(
+ TALER_EXCHANGE_GET_AML_TRANSFERS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetAmlTransfersResponse *result);
/**
- * Start GET /aml/$OPUB/transfers-kycauth operation.
+ * Start GET /aml/$OPUB/transfers-{credit,debit,kycauth} operation.
*
- * @param[in,out] atkgh operation to start
+ * @param[in,out] atgh 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
*/
-void
-TALER_EXCHANGE_aml_transfers_kycauth_get_start (
- struct TALER_EXCHANGE_AmlTransfersKycauthGetHandle *atkgh,
- TALER_EXCHANGE_AmlTransfersKycauthGetCallback cb,
- TALER_EXCHANGE__AML_TRANSFERS_KYCAUTH_GET_RESULT_CLOSURE *cb_cls);
+enum TALER_ErrorCode
+TALER_EXCHANGE_get_aml_transfers_start (
+ struct TALER_EXCHANGE_GetAmlTransfersHandle *atgh,
+ TALER_EXCHANGE_GetAmlTransfersCallback cb,
+ TALER_EXCHANGE_GET_AML_TRANSFERS_RESULT_CLOSURE *cb_cls);
/**
- * Cancel GET /aml/$OPUB/transfers-kycauth operation.
+ * Cancel GET /aml/$OPUB/transfers-{credit,debit,kycauth} operation.
+ * This function must not be called by clients after the
+ * TALER_EXCHANGE_GetAmlTransfersCallback has been invoked
+ * (as in those cases it'll be called internally by the
+ * implementation already).
*
- * @param[in] atkgh operation to cancel
+ * @param[in] atgh operation to cancel
+ */
+void
+TALER_EXCHANGE_get_aml_transfers_cancel (
+ struct TALER_EXCHANGE_GetAmlTransfersHandle *atgh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlTransfersEntry instead.
+ */
+struct TALER_EXCHANGE_AmlTransfersKycauthGetTransferEntry
+{
+ uint64_t rowid;
+ const char *payto_uri;
+ struct TALER_Amount amount;
+ struct GNUNET_TIME_Timestamp execution_time;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlTransfersResponse instead.
+ */
+struct TALER_EXCHANGE_AmlTransfersKycauthGetResult
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ size_t transfers_length;
+ const struct TALER_EXCHANGE_AmlTransfersKycauthGetTransferEntry *transfers
+ ;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlTransfersCallback instead.
+ */
+typedef void
+(*TALER_EXCHANGE_AmlTransfersKycauthGetCallback)(
+ void *cls,
+ const struct TALER_EXCHANGE_AmlTransfersKycauthGetResult *result);
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetAmlTransfersHandle instead.
+ */
+struct TALER_EXCHANGE_AmlTransfersKycauthGetHandle;
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_get_aml_transfers_kycauth_create() and
+ * the new API instead.
+ */
+struct TALER_EXCHANGE_AmlTransfersKycauthGetHandle *
+TALER_EXCHANGE_aml_transfers_kycauth_get (
+ struct GNUNET_CURL_Context *ctx,
+ const char *exchange_url,
+ const struct TALER_NormalizedPaytoHashP *h_payto,
+ const struct TALER_Amount *threshold,
+ uint64_t offset,
+ int64_t limit,
+ const struct TALER_AmlOfficerPrivateKeyP *officer_priv,
+ TALER_EXCHANGE_AmlTransfersKycauthGetCallback cb,
+ void *cb_cls);
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_get_aml_transfers_cancel() instead.
*/
void
TALER_EXCHANGE_aml_transfers_kycauth_get_cancel (
diff --git a/src/include/taler/taler-exchange/get-coins-COIN_PUB-history.h b/src/include/taler/taler-exchange/get-coins-COIN_PUB-history.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/get-coins-COIN_PUB-history.h
@@ -34,21 +34,17 @@ struct TALER_EXCHANGE_NonceKey
const struct TALER_EXCHANGE_DenomPublicKey *pk;
/**
- * What is number to derive the client nonce for the
- * fresh coin?
+ * What is the number to derive the client nonce for the fresh coin?
*/
uint32_t cnc_num;
};
-/* ********************* GET /coins/$COIN_PUB *********************** */
-
/**
* Ways how a coin's balance may change.
*/
enum TALER_EXCHANGE_CoinTransactionType
{
-
/**
* Reserved for uninitialized / none.
*/
@@ -222,15 +218,8 @@ struct TALER_EXCHANGE_CoinHistoryEntry
/**
- * @brief A /coins/$RID/history Handle
- */
-struct TALER_EXCHANGE_CoinsHistoryHandle;
-
-
-/**
- * Parses and verifies a coin's transaction history as
- * returned by the exchange. Note that in case of
- * incremental histories, the client must first combine
+ * Parses and verifies a coin's transaction history as returned by the exchange.
+ * Note that in case of incremental histories, the client must first combine
* the incremental histories into one complete history.
*
* @param keys /keys data of the exchange
@@ -238,7 +227,7 @@ struct TALER_EXCHANGE_CoinsHistoryHandle;
* @param history JSON array with the coin's history
* @param coin_pub public key of the coin
* @param[out] total_in set to total amount credited to the coin in @a history
- * @param[out] total_out set to total amount debited to the coin in @a history
+ * @param[out] total_out set to total amount debited from the coin in @a history
* @param rlen length of the @a rhistory array
* @param[out] rhistory array where to write the parsed @a history
* @return #GNUNET_OK if @a history is valid,
@@ -272,12 +261,150 @@ TALER_EXCHANGE_check_coin_signature_conflict (
/**
+ * Possible options we can set for the GET coins history request.
+ */
+enum TALER_EXCHANGE_GetCoinsHistoryOption
+{
+ /**
+ * End of list of options.
+ */
+ TALER_EXCHANGE_GET_COINS_HISTORY_OPTION_END = 0,
+
+ /**
+ * Only return entries with history_offset strictly greater than this value.
+ * Defaults to 0 (return all entries).
+ */
+ TALER_EXCHANGE_GET_COINS_HISTORY_OPTION_START_OFF
+
+};
+
+
+/**
+ * Value for an option for the GET coins history request.
+ */
+struct TALER_EXCHANGE_GetCoinsHistoryOptionValue
+{
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_GetCoinsHistoryOption option;
+
+ /**
+ * Specific option value.
+ */
+ union
+ {
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_COINS_HISTORY_OPTION_START_OFF.
+ */
+ uint64_t start_off;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to GET /coins/$COIN_PUB/history.
+ */
+struct TALER_EXCHANGE_GetCoinsHistoryHandle;
+
+
+/**
+ * Set up GET /coins/$COIN_PUB/history operation.
+ * Note that you must explicitly start the operation after
+ * possibly setting options.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param coin_priv private key of the coin (used for authentication)
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetCoinsHistoryHandle *
+TALER_EXCHANGE_get_coins_history_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_CoinSpendPrivateKeyP *coin_priv);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_GetCoinsHistoryOptionValue
+ */
+#define TALER_EXCHANGE_get_coins_history_option_end_() \
+ (const struct TALER_EXCHANGE_GetCoinsHistoryOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_COINS_HISTORY_OPTION_END \
+ }
+
+/**
+ * Set starting offset for partial history fetch.
+ *
+ * @param o offset: only return entries with history_offset > this value
+ * @return representation of the option as a struct TALER_EXCHANGE_GetCoinsHistoryOptionValue
+ */
+#define TALER_EXCHANGE_get_coins_history_option_start_off(o) \
+ (const struct TALER_EXCHANGE_GetCoinsHistoryOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_COINS_HISTORY_OPTION_START_OFF, \
+ .details.start_off = (o) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param gcsh the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_get_coins_history_set_options_ (
+ struct TALER_EXCHANGE_GetCoinsHistoryHandle *gcsh,
+ unsigned int num_options,
+ const struct TALER_EXCHANGE_GetCoinsHistoryOptionValue *options);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * It should be used with helpers that create required options, for example:
+ *
+ * TALER_EXCHANGE_get_coins_history_set_options (
+ * gcsh,
+ * TALER_EXCHANGE_get_coins_history_option_start_off (last_off));
+ *
+ * @param gcsh the request to set the options for
+ * @param ... the list of options, each created by a
+ * TALER_EXCHANGE_get_coins_history_option_NAME(VALUE) helper
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_get_coins_history_set_options(gcsh,...) \
+ TALER_EXCHANGE_get_coins_history_set_options_ ( \
+ gcsh, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_GetCoinsHistoryOptionValue[]) \
+ {__VA_ARGS__, TALER_EXCHANGE_get_coins_history_option_end_ () } \
+ ))
+
+
+/**
* Response to a GET /coins/$COIN_PUB/history request.
*/
-struct TALER_EXCHANGE_CoinHistory
+struct TALER_EXCHANGE_GetCoinsHistoryResponse
{
/**
- * High-level HTTP response details.
+ * HTTP response data.
*/
struct TALER_EXCHANGE_HttpResponse hr;
@@ -286,31 +413,26 @@ struct TALER_EXCHANGE_CoinHistory
*/
union
{
-
/**
- * Information returned on success, if
- * @e hr.http_status is #MHD_HTTP_OK
+ * Information returned on #MHD_HTTP_OK.
*/
struct
{
-
/**
* Coin transaction history (possibly partial).
- * Not yet validated, combine with other already
- * known history data for this coin and then use
- * #TALER_EXCHANGE_parse_coin_history() to validate
- * the complete history and obtain it in binary
- * format.
+ * Not yet validated; combine with other already known history data
+ * for this coin and then use TALER_EXCHANGE_parse_coin_history() to
+ * validate the complete history and obtain it in binary format.
*/
const json_t *history;
/**
- * The hash of the coin denomination's public key
+ * Hash of the coin denomination's public key.
*/
struct TALER_DenominationHashP h_denom_pub;
/**
- * Coin balance.
+ * Current coin balance.
*/
struct TALER_Amount balance;
@@ -321,33 +443,91 @@ struct TALER_EXCHANGE_CoinHistory
};
+#ifndef TALER_EXCHANGE_GET_COINS_HISTORY_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetCoinsHistoryCallback.
+ */
+#define TALER_EXCHANGE_GET_COINS_HISTORY_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_COINS_HISTORY_RESULT_CLOSURE */
+
/**
- * Signature of functions called with the result of
- * a coin transaction history request.
+ * Type of the function that receives the result of a
+ * GET /coins/$COIN_PUB/history request.
*
* @param cls closure
- * @param ch transaction history for the coin
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetCoinsHistoryCallback)(
+ TALER_EXCHANGE_GET_COINS_HISTORY_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetCoinsHistoryResponse *result);
+
+
+/**
+ * Start GET /coins/$COIN_PUB/history operation.
+ *
+ * @param[in,out] gcsh 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_get_coins_history_start (
+ struct TALER_EXCHANGE_GetCoinsHistoryHandle *gcsh,
+ TALER_EXCHANGE_GetCoinsHistoryCallback cb,
+ TALER_EXCHANGE_GET_COINS_HISTORY_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /coins/$COIN_PUB/history operation. This function must not
+ * be called by clients after the TALER_EXCHANGE_GetCoinsHistoryCallback has
+ * been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] gcsh operation to cancel
+ */
+void
+TALER_EXCHANGE_get_coins_history_cancel (
+ struct TALER_EXCHANGE_GetCoinsHistoryHandle *gcsh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetCoinsHistoryResponse instead.
+ */
+struct TALER_EXCHANGE_CoinHistory
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ const json_t *history;
+ struct TALER_DenominationHashP h_denom_pub;
+ struct TALER_Amount balance;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetCoinsHistoryCallback instead.
*/
typedef void
(*TALER_EXCHANGE_CoinsHistoryCallback)(
void *cls,
const struct TALER_EXCHANGE_CoinHistory *ch);
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetCoinsHistoryHandle instead.
+ */
+struct TALER_EXCHANGE_CoinsHistoryHandle;
/**
- * Parses and verifies a coin's transaction history as
- * returned by the exchange. Note that a client may
- * have to combine multiple partial coin histories
- * into one coherent history before calling this function.
- *
- * @param ctx context for managing request
- * @param url base URL of the exchange
- * @param coin_priv private key of the coin
- * @param start_off offset from which on to request history
- * @param cb function to call with results
- * @param cb_cls closure for @a cb
- * @return #GNUNET_OK if @a history is valid,
- * #GNUNET_SYSERR if not
+ * @deprecated Use #TALER_EXCHANGE_get_coins_history_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_CoinsHistoryHandle *
TALER_EXCHANGE_coins_history (
@@ -358,14 +538,12 @@ TALER_EXCHANGE_coins_history (
TALER_EXCHANGE_CoinsHistoryCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_coins_history() operation.
- *
- * @param[in] rsh operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_get_coins_history_cancel() instead.
*/
void
TALER_EXCHANGE_coins_history_cancel (
struct TALER_EXCHANGE_CoinsHistoryHandle *rsh);
-#endif
+
+#endif /* _TALER_EXCHANGE__GET_COINS_COIN_PUB_HISTORY_H */
diff --git a/src/include/taler/taler-exchange/get-config.h b/src/include/taler/taler-exchange/get-config.h
@@ -0,0 +1,227 @@
+/*
+ This file is part of TALER
+ Copyright (C) 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/taler-exchange/get-config.h
+ * @brief C interface for GET /config
+ * @author Christian Grothoff
+ */
+#ifndef _TALER_EXCHANGE__GET_CONFIG_H
+#define _TALER_EXCHANGE__GET_CONFIG_H
+
+#include <taler/taler-exchange/common.h>
+
+/**
+ * Handle for an operation to GET /config.
+ */
+struct TALER_EXCHANGE_GetConfigHandle;
+
+
+/**
+ * Information about how a currency should be rendered.
+ */
+struct TALER_EXCHANGE_GetConfigCurrencySpecification
+{
+ /**
+ * Name of the currency, e.g. "US Dollar".
+ */
+ const char *name;
+
+ /**
+ * Currency code, e.g. "USD".
+ * @deprecated in protocol v18
+ */
+ const char *currency;
+
+ /**
+ * Number of fractional digits the user may enter after the decimal separator.
+ */
+ unsigned int num_fractional_input_digits;
+
+ /**
+ * Number of fractional digits to render in normal font and size.
+ */
+ unsigned int num_fractional_normal_digits;
+
+ /**
+ * Number of fractional digits to always render, padding with zeros as needed.
+ */
+ unsigned int num_fractional_trailing_zero_digits;
+
+ /**
+ * Map of powers-of-10 to alternative currency names/symbols, as JSON object.
+ * Must always have an entry under "0" that defines the base name,
+ * e.g. {"0": "€"} or {"0": "BTC", "-3": "mBTC"}.
+ * Communicates the currency symbol to be used.
+ */
+ const json_t *alt_unit_names;
+
+ /**
+ * Array of common amounts that should be offered as display buttons.
+ * The array should have four entries, but may have fewer or more.
+ * Since protocol v30 rev 2.
+ */
+ const struct TALER_Amount *common_amounts;
+
+ /**
+ * Length of the @e common_amounts array.
+ */
+ size_t common_amounts_length;
+
+};
+
+
+/**
+ * Response from a GET /config request.
+ */
+struct TALER_EXCHANGE_GetConfigResponse
+{
+ /**
+ * HTTP response data.
+ */
+ struct TALER_EXCHANGE_HttpResponse hr;
+
+ /**
+ * Response details depending on HTTP status.
+ */
+ union
+ {
+ /**
+ * Details if HTTP status is #MHD_HTTP_OK.
+ */
+ struct
+ {
+ /**
+ * Protocol version of the exchange, libtool-style "current:revision:age".
+ */
+ const char *version;
+
+ /**
+ * Protocol name, always "taler-exchange".
+ */
+ const char *name;
+
+ /**
+ * Optional URN of the implementation.
+ * Since protocol v18.
+ */
+ const char *implementation;
+
+ /**
+ * Currency supported by this exchange (e.g. "USD" or "EUR").
+ */
+ const char *currency;
+
+ /**
+ * Optional URL of a shopping site where this exchange's currency is used.
+ * Since protocol v21.
+ */
+ const char *shopping_url;
+
+ /**
+ * Optional open banking gateway URL for wire-based withdrawals.
+ * Since protocol v30.
+ */
+ const char *open_banking_gateway;
+
+ /**
+ * How wallets should render this currency.
+ */
+ struct TALER_EXCHANGE_GetConfigCurrencySpecification
+ currency_specification;
+
+ /**
+ * NULL-terminated array of supported KYC requirement names.
+ * @deprecated since protocol v24.
+ */
+ const char **supported_kyc_requirements;
+
+ /**
+ * Optional AML SPA dialect name that determines which forms and
+ * statistics are available.
+ * Since protocol v24.
+ */
+ const char *aml_spa_dialect;
+
+ } ok;
+ } details;
+
+};
+
+
+#ifndef TALER_EXCHANGE_GET_CONFIG_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetConfigCallback.
+ */
+#define TALER_EXCHANGE_GET_CONFIG_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_CONFIG_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * GET /config request.
+ *
+ * @param cls closure
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetConfigCallback)(
+ TALER_EXCHANGE_GET_CONFIG_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetConfigResponse *result);
+
+
+/**
+ * Set up GET /config operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetConfigHandle *
+TALER_EXCHANGE_get_config_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url);
+
+
+/**
+ * Start GET /config operation.
+ *
+ * @param[in,out] gch 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_get_config_start (
+ struct TALER_EXCHANGE_GetConfigHandle *gch,
+ TALER_EXCHANGE_GetConfigCallback cb,
+ TALER_EXCHANGE_GET_CONFIG_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /config operation. This function must not be called
+ * by clients after the TALER_EXCHANGE_GetConfigCallback has been invoked
+ * (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] gch operation to cancel
+ */
+void
+TALER_EXCHANGE_get_config_cancel (
+ struct TALER_EXCHANGE_GetConfigHandle *gch);
+
+
+#endif /* _TALER_EXCHANGE__GET_CONFIG_H */
diff --git a/src/include/taler/taler-exchange/get-contracts-CONTRACT_PUB.h b/src/include/taler/taler-exchange/get-contracts-CONTRACT_PUB.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/get-contracts-CONTRACT_PUB.h
@@ -23,16 +23,19 @@
#include <taler/taler-exchange/common.h>
-/* ********************* W2W API ****************** */
+/**
+ * Handle for an operation to GET /contracts/$CONTRACT_PUB.
+ */
+struct TALER_EXCHANGE_GetContractsHandle;
/**
- * Response generated for a contract get request.
+ * Response from a GET /contracts/$CONTRACT_PUB request.
*/
-struct TALER_EXCHANGE_ContractGetResponse
+struct TALER_EXCHANGE_GetContractsResponse
{
/**
- * Full HTTP response.
+ * HTTP response data.
*/
struct TALER_EXCHANGE_HttpResponse hr;
@@ -46,14 +49,13 @@ struct TALER_EXCHANGE_ContractGetResponse
*/
struct
{
-
/**
* Public key of the purse.
*/
struct TALER_PurseContractPublicKeyP purse_pub;
/**
- * Encrypted contract.
+ * Encrypted contract data.
*/
const void *econtract;
@@ -68,33 +70,108 @@ struct TALER_EXCHANGE_ContractGetResponse
};
+
+#ifndef TALER_EXCHANGE_GET_CONTRACTS_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetContractsCallback.
+ */
+#define TALER_EXCHANGE_GET_CONTRACTS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_CONTRACTS_RESULT_CLOSURE */
+
/**
- * Function called with information about the a purse.
+ * Type of the function that receives the result of a
+ * GET /contracts/$CONTRACT_PUB request.
*
* @param cls closure
- * @param cgr HTTP response data
+ * @param result result returned by the HTTP server
*/
typedef void
-(*TALER_EXCHANGE_ContractGetCallback) (
- void *cls,
- const struct TALER_EXCHANGE_ContractGetResponse *cgr);
+(*TALER_EXCHANGE_GetContractsCallback)(
+ TALER_EXCHANGE_GET_CONTRACTS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetContractsResponse *result);
/**
- * @brief Handle for a GET /contracts/$CPUB request.
+ * Set up GET /contracts/$CONTRACT_PUB operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param contract_priv private key of the contract
+ * @return handle to operation
*/
-struct TALER_EXCHANGE_ContractsGetHandle;
+struct TALER_EXCHANGE_GetContractsHandle *
+TALER_EXCHANGE_get_contracts_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_ContractDiffiePrivateP *contract_priv);
/**
- * Request information about a contract from the exchange.
+ * Start GET /contracts/$CONTRACT_PUB operation.
*
- * @param ctx CURL context
- * @param url exchange base URL
- * @param contract_priv private key of the contract
+ * @param[in,out] gch operation to start
* @param cb function to call with the exchange's result
* @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @return status code, #TALER_EC_NONE on success
+ */
+enum TALER_ErrorCode
+TALER_EXCHANGE_get_contracts_start (
+ struct TALER_EXCHANGE_GetContractsHandle *gch,
+ TALER_EXCHANGE_GetContractsCallback cb,
+ TALER_EXCHANGE_GET_CONTRACTS_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /contracts/$CONTRACT_PUB operation. This function must not
+ * be called by clients after the TALER_EXCHANGE_GetContractsCallback has
+ * been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] gch operation to cancel
+ */
+void
+TALER_EXCHANGE_get_contracts_cancel (
+ struct TALER_EXCHANGE_GetContractsHandle *gch);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetContractsResponse instead.
+ */
+struct TALER_EXCHANGE_ContractGetResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct TALER_PurseContractPublicKeyP purse_pub;
+ const void *econtract;
+ size_t econtract_size;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetContractsCallback instead.
+ */
+typedef void
+(*TALER_EXCHANGE_ContractGetCallback) (
+ void *cls,
+ const struct TALER_EXCHANGE_ContractGetResponse *cgr);
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetContractsHandle instead.
+ */
+struct TALER_EXCHANGE_ContractsGetHandle;
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_get_contracts_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ContractsGetHandle *
TALER_EXCHANGE_contract_get (
@@ -104,14 +181,12 @@ TALER_EXCHANGE_contract_get (
TALER_EXCHANGE_ContractGetCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_contract_get() operation.
- *
- * @param cgh handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_get_contracts_cancel() instead.
*/
void
TALER_EXCHANGE_contract_get_cancel (
struct TALER_EXCHANGE_ContractsGetHandle *cgh);
-#endif
+
+#endif /* _TALER_EXCHANGE__GET_CONTRACTS_CONTRACT_PUB_H */
diff --git a/src/include/taler/taler-exchange/get-deposits-H_WIRE-MERCHANT_PUB-H_CONTRACT_TERMS-COIN_PUB.h b/src/include/taler/taler-exchange/get-deposits-H_WIRE-MERCHANT_PUB-H_CONTRACT_TERMS-COIN_PUB.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/get-deposits-H_WIRE-MERCHANT_PUB-H_CONTRACT_TERMS-COIN_PUB.h
@@ -25,21 +25,157 @@
#include <taler/taler-exchange/common.h>
-/* ********************* GET /deposits/ *********************** */
+/**
+ * Possible options we can set for the GET deposits request.
+ */
+enum TALER_EXCHANGE_GetDepositsOption
+{
+ /**
+ * End of list of options.
+ */
+ TALER_EXCHANGE_GET_DEPOSITS_OPTION_END = 0,
+
+ /**
+ * How long to wait for the wire transfer to be executed,
+ * enabling long polling. Default is zero (no long polling).
+ */
+ TALER_EXCHANGE_GET_DEPOSITS_OPTION_TIMEOUT
+
+};
/**
- * @brief A /deposits/ GET Handle
+ * Value for an option for the GET deposits request.
*/
-struct TALER_EXCHANGE_DepositGetHandle;
+struct TALER_EXCHANGE_GetDepositsOptionValue
+{
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_GetDepositsOption option;
+
+ /**
+ * Specific option value.
+ */
+ union
+ {
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_DEPOSITS_OPTION_TIMEOUT.
+ */
+ struct GNUNET_TIME_Relative timeout;
+
+ } details;
+
+};
/**
- * Data returned for a successful GET /deposits/ request.
+ * Handle for an operation to GET /deposits/$H_WIRE/$MERCHANT_PUB/$H_CONTRACT_TERMS/$COIN_PUB.
*/
-struct TALER_EXCHANGE_GetDepositResponse
-{
+struct TALER_EXCHANGE_GetDepositsHandle;
+
+/**
+ * Set up GET /deposits/... operation.
+ * Note that you must explicitly start the operation after
+ * possibly setting options.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param keys exchange keys for signature verification
+ * @param merchant_priv private key of the merchant
+ * @param h_wire hash of the merchant's wire transfer details
+ * @param h_contract_terms hash of the proposal data
+ * @param coin_pub public key of the coin
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetDepositsHandle *
+TALER_EXCHANGE_get_deposits_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_MerchantPrivateKeyP *merchant_priv,
+ const struct TALER_MerchantWireHashP *h_wire,
+ const struct TALER_PrivateContractHashP *h_contract_terms,
+ const struct TALER_CoinSpendPublicKeyP *coin_pub);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_GetDepositsOptionValue
+ */
+#define TALER_EXCHANGE_get_deposits_option_end_() \
+ (const struct TALER_EXCHANGE_GetDepositsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_DEPOSITS_OPTION_END \
+ }
+
+/**
+ * Set long-polling timeout.
+ *
+ * @param t how long to wait for the wire transfer to be executed
+ * @return representation of the option as a struct TALER_EXCHANGE_GetDepositsOptionValue
+ */
+#define TALER_EXCHANGE_get_deposits_option_timeout(t) \
+ (const struct TALER_EXCHANGE_GetDepositsOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_DEPOSITS_OPTION_TIMEOUT, \
+ .details.timeout = (t) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param gdh the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_get_deposits_set_options_ (
+ struct TALER_EXCHANGE_GetDepositsHandle *gdh,
+ unsigned int num_options,
+ const struct TALER_EXCHANGE_GetDepositsOptionValue *options);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * It should be used with helpers that create required options, for example:
+ *
+ * TALER_EXCHANGE_get_deposits_set_options (
+ * gdh,
+ * TALER_EXCHANGE_get_deposits_option_timeout (timeout));
+ *
+ * @param gdh the request to set the options for
+ * @param ... the list of options, each created by a
+ * TALER_EXCHANGE_get_deposits_option_NAME(VALUE) helper
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_get_deposits_set_options(gdh,...) \
+ TALER_EXCHANGE_get_deposits_set_options_ ( \
+ gdh, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_GetDepositsOptionValue[]) \
+ {__VA_ARGS__, TALER_EXCHANGE_get_deposits_option_end_ () } \
+ ))
+
+
+/**
+ * Data returned for a successful GET /deposits/... request.
+ */
+struct TALER_EXCHANGE_GetDepositsResponse
+{
/**
* HTTP response data.
*/
@@ -50,11 +186,11 @@ struct TALER_EXCHANGE_GetDepositResponse
*/
union
{
-
/**
- * Response if the status was #MHD_HTTP_OK
+ * Response if the status was #MHD_HTTP_OK.
+ * The wire transfer has been executed.
*/
- struct TALER_EXCHANGE_DepositData
+ struct
{
/**
* Exchange key used to sign.
@@ -72,82 +208,148 @@ struct TALER_EXCHANGE_GetDepositResponse
struct TALER_WireTransferIdentifierRawP wtid;
/**
- * Actual execution time for the wire transfer
+ * Actual execution time for the wire transfer.
*/
struct GNUNET_TIME_Timestamp execution_time;
/**
- * Contribution to the total amount by this coin.
+ * This coin's contribution to the total wire transfer amount.
*/
struct TALER_Amount coin_contribution;
} ok;
/**
- * Response if the status was #MHD_HTTP_ACCEPTED
+ * Response if the status was #MHD_HTTP_ACCEPTED.
+ * The wire transfer has not yet been executed.
*/
struct
{
-
/**
- * planned execution time for the wire transfer
+ * Planned execution time for the wire transfer.
*/
struct GNUNET_TIME_Timestamp execution_time;
/**
- * Public key needed to access the KYC state of
- * this account. All zeros if a wire transfer
- * is required first to establish the key.
+ * Public key needed to access the KYC state of this account.
+ * All zeros if a wire transfer is required first to establish the key.
*/
union TALER_AccountPublicKeyP account_pub;
/**
* KYC legitimization requirement that the merchant should use to check
* for its KYC status.
- *
* @deprecated, no longer needed.
*/
uint64_t requirement_row;
/**
- * Set to 'true' if the KYC check is already finished and
- * the exchange is merely waiting for the @e execution_time.
+ * True if the KYC check is already finished and the exchange is
+ * merely waiting for the @e execution_time.
*/
bool kyc_ok;
+
} accepted;
} details;
+
};
+#ifndef TALER_EXCHANGE_GET_DEPOSITS_RESULT_CLOSURE
/**
- * Function called with detailed wire transfer data.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetDepositsCallback.
+ */
+#define TALER_EXCHANGE_GET_DEPOSITS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_DEPOSITS_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * GET /deposits/... request.
*
* @param cls closure
- * @param dr details about the deposit response
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetDepositsCallback)(
+ TALER_EXCHANGE_GET_DEPOSITS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetDepositsResponse *result);
+
+
+/**
+ * Start GET /deposits/... operation.
+ *
+ * @param[in,out] gdh 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_get_deposits_start (
+ struct TALER_EXCHANGE_GetDepositsHandle *gdh,
+ TALER_EXCHANGE_GetDepositsCallback cb,
+ TALER_EXCHANGE_GET_DEPOSITS_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /deposits/... operation. This function must not be called
+ * by clients after the TALER_EXCHANGE_GetDepositsCallback has been invoked
+ * (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] gdh operation to cancel
+ */
+void
+TALER_EXCHANGE_get_deposits_cancel (
+ struct TALER_EXCHANGE_GetDepositsHandle *gdh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetDepositsResponse instead.
+ */
+struct TALER_EXCHANGE_GetDepositResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct TALER_EXCHANGE_DepositData
+ {
+ struct TALER_ExchangePublicKeyP exchange_pub;
+ struct TALER_ExchangeSignatureP exchange_sig;
+ struct TALER_WireTransferIdentifierRawP wtid;
+ struct GNUNET_TIME_Timestamp execution_time;
+ struct TALER_Amount coin_contribution;
+ } ok;
+ struct
+ {
+ struct GNUNET_TIME_Timestamp execution_time;
+ union TALER_AccountPublicKeyP account_pub;
+ uint64_t requirement_row;
+ bool kyc_ok;
+ } accepted;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetDepositsCallback instead.
*/
typedef void
(*TALER_EXCHANGE_DepositGetCallback)(
void *cls,
const struct TALER_EXCHANGE_GetDepositResponse *dr);
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetDepositsHandle instead.
+ */
+struct TALER_EXCHANGE_DepositGetHandle;
/**
- * Obtain the wire transfer details for a given transaction. Tells the client
- * which aggregate wire transfer the deposit operation identified by @a coin_pub,
- * @a merchant_priv and @a h_contract_terms contributed to.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param merchant_priv the merchant's private key
- * @param h_wire hash of merchant's wire transfer details
- * @param h_contract_terms hash of the proposal data
- * @param coin_pub public key of the coin
- * @param timeout timeout to use for long-polling, 0 for no long polling
- * @param cb function to call with the result
- * @param cb_cls closure for @a cb
- * @return handle to abort request
+ * @deprecated Use #TALER_EXCHANGE_get_deposits_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_DepositGetHandle *
TALER_EXCHANGE_deposits_get (
@@ -162,15 +364,13 @@ TALER_EXCHANGE_deposits_get (
TALER_EXCHANGE_DepositGetCallback cb,
void *cb_cls);
-
/**
- * Cancel deposit wtid request. This function cannot be used on a request
- * handle if a response is already served for it.
- *
- * @param dwh the wire deposits request handle
+ * @deprecated Use #TALER_EXCHANGE_get_deposits_cancel() instead.
*/
void
TALER_EXCHANGE_deposits_get_cancel (
struct TALER_EXCHANGE_DepositGetHandle *dwh);
-#endif
+
+#endif /* \
+ _TALER_EXCHANGE__GET_DEPOSITS_H_WIRE_MERCHANT_PUB_H_CONTRACT_TERMS_COIN_PUB_H */
diff --git a/src/include/taler/taler-exchange/get-kyc-check-H_NORMALIZED_PAYTO.h b/src/include/taler/taler-exchange/get-kyc-check-H_NORMALIZED_PAYTO.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/get-kyc-check-H_NORMALIZED_PAYTO.h
@@ -23,20 +23,11 @@
#include <taler/taler-exchange/common.h>
-/* ********************* KYC *********************** */
-
-/**
- * Handle for a ``/kyc-check`` operation.
- */
-struct TALER_EXCHANGE_KycCheckHandle;
-
-
/**
* KYC/AML status information about an account.
*/
struct TALER_EXCHANGE_AccountKycStatus
{
-
/**
* Current AML state for the target account. True if operations are not
* happening due to staff processing paperwork *or* due to legal
@@ -56,8 +47,8 @@ struct TALER_EXCHANGE_AccountKycStatus
uint64_t rule_gen;
/**
- * Array of length @e limits_array with (exposed) limits that apply to the
- * account.
+ * Array of (exposed) limits that apply to the account.
+ * Length in @e limits_length.
*/
const struct TALER_EXCHANGE_AccountLimit *limits;
@@ -70,39 +61,231 @@ struct TALER_EXCHANGE_AccountKycStatus
/**
- * KYC status response details.
+ * Possible options we can set for the GET kyc-check request.
*/
-struct TALER_EXCHANGE_KycStatus
+enum TALER_EXCHANGE_GetKycCheckOption
{
/**
- * HTTP response data
+ * End of list of options.
*/
- struct TALER_EXCHANGE_HttpResponse hr;
+ TALER_EXCHANGE_GET_KYC_CHECK_OPTION_END = 0,
/**
- * Details depending on @e http_status.
+ * Latest known AML/KYC rule generation, for long polling.
+ * The server will only respond when the rule generation exceeds this value.
+ * Default is 0 (respond immediately).
+ */
+ TALER_EXCHANGE_GET_KYC_CHECK_OPTION_KNOWN_RULE_GEN,
+
+ /**
+ * Long polling target: what KYC state to wait for.
+ * Default is to respond immediately.
+ */
+ TALER_EXCHANGE_GET_KYC_CHECK_OPTION_LPT,
+
+ /**
+ * How long to wait for an answer including long polling.
+ * Default is zero (no long polling).
+ */
+ TALER_EXCHANGE_GET_KYC_CHECK_OPTION_TIMEOUT
+
+};
+
+
+/**
+ * Value for an option for the GET kyc-check request.
+ */
+struct TALER_EXCHANGE_GetKycCheckOptionValue
+{
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_GetKycCheckOption option;
+
+ /**
+ * Specific option value.
*/
union
{
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_KYC_CHECK_OPTION_KNOWN_RULE_GEN.
+ */
+ uint64_t known_rule_gen;
+
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_KYC_CHECK_OPTION_LPT.
+ */
+ enum TALER_EXCHANGE_KycLongPollTarget lpt;
+
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_KYC_CHECK_OPTION_TIMEOUT.
+ */
+ struct GNUNET_TIME_Relative timeout;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to GET /kyc-check/$H_NORMALIZED_PAYTO.
+ */
+struct TALER_EXCHANGE_GetKycCheckHandle;
+
+
+/**
+ * Set up GET /kyc-check/$H_NORMALIZED_PAYTO operation.
+ * Note that you must explicitly start the operation after
+ * possibly setting options.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param h_payto hash of the account the KYC check is about
+ * @param pk private key to authorize the request with
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetKycCheckHandle *
+TALER_EXCHANGE_get_kyc_check_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_NormalizedPaytoHashP *h_payto,
+ const union TALER_AccountPrivateKeyP *pk);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_GetKycCheckOptionValue
+ */
+#define TALER_EXCHANGE_get_kyc_check_option_end_() \
+ (const struct TALER_EXCHANGE_GetKycCheckOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_KYC_CHECK_OPTION_END \
+ }
+
+/**
+ * Set the latest known rule generation for long polling.
+ *
+ * @param g latest known AML decision / rule generation
+ * @return representation of the option as a struct TALER_EXCHANGE_GetKycCheckOptionValue
+ */
+#define TALER_EXCHANGE_get_kyc_check_option_known_rule_gen(g) \
+ (const struct TALER_EXCHANGE_GetKycCheckOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_KYC_CHECK_OPTION_KNOWN_RULE_GEN, \
+ .details.known_rule_gen = (g) \
+ }
+
+/**
+ * Set the long-polling target KYC state to wait for.
+ *
+ * @param t long poll target
+ * @return representation of the option as a struct TALER_EXCHANGE_GetKycCheckOptionValue
+ */
+#define TALER_EXCHANGE_get_kyc_check_option_lpt(t) \
+ (const struct TALER_EXCHANGE_GetKycCheckOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_KYC_CHECK_OPTION_LPT, \
+ .details.lpt = (t) \
+ }
+
+/**
+ * Set long-polling timeout.
+ *
+ * @param t how long to wait for an answer
+ * @return representation of the option as a struct TALER_EXCHANGE_GetKycCheckOptionValue
+ */
+#define TALER_EXCHANGE_get_kyc_check_option_timeout(t) \
+ (const struct TALER_EXCHANGE_GetKycCheckOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_KYC_CHECK_OPTION_TIMEOUT, \
+ .details.timeout = (t) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param gkch the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_get_kyc_check_set_options_ (
+ struct TALER_EXCHANGE_GetKycCheckHandle *gkch,
+ unsigned int num_options,
+ const struct TALER_EXCHANGE_GetKycCheckOptionValue *options);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * It should be used with helpers that create required options, for example:
+ *
+ * TALER_EXCHANGE_get_kyc_check_set_options (
+ * gkch,
+ * TALER_EXCHANGE_get_kyc_check_option_known_rule_gen (last_gen),
+ * TALER_EXCHANGE_get_kyc_check_option_lpt (TALER_EXCHANGE_YNMS_NONE),
+ * TALER_EXCHANGE_get_kyc_check_option_timeout (timeout));
+ *
+ * @param gkch the request to set the options for
+ * @param ... the list of options, each created by a
+ * TALER_EXCHANGE_get_kyc_check_option_NAME(VALUE) helper
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_get_kyc_check_set_options(gkch,...) \
+ TALER_EXCHANGE_get_kyc_check_set_options_ ( \
+ gkch, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_GetKycCheckOptionValue[]) \
+ {__VA_ARGS__, TALER_EXCHANGE_get_kyc_check_option_end_ () } \
+ ))
+
+
+/**
+ * KYC status response.
+ */
+struct TALER_EXCHANGE_GetKycCheckResponse
+{
+ /**
+ * HTTP response data.
+ */
+ struct TALER_EXCHANGE_HttpResponse hr;
+ /**
+ * Details depending on @e hr.http_status.
+ */
+ union
+ {
/**
- * KYC is OK, affirmation returned by the exchange.
+ * KYC is satisfied; affirmation returned by the exchange.
+ * @e hr.http_status is #MHD_HTTP_OK.
*/
struct TALER_EXCHANGE_AccountKycStatus ok;
/**
- * KYC is required.
+ * KYC is required before the operation can proceed.
+ * @e hr.http_status is #MHD_HTTP_ACCEPTED.
*/
struct TALER_EXCHANGE_AccountKycStatus accepted;
/**
- * Request was forbidden.
+ * Request was forbidden (wrong authorization key).
+ * @e hr.http_status is #MHD_HTTP_FORBIDDEN.
*/
struct
{
-
/**
- * Account pub that would have been authorized.
+ * Account public key that would have been authorized.
*/
union TALER_AccountPublicKeyP expected_account_pub;
@@ -112,32 +295,92 @@ struct TALER_EXCHANGE_KycStatus
};
+
+#ifndef TALER_EXCHANGE_GET_KYC_CHECK_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetKycCheckCallback.
+ */
+#define TALER_EXCHANGE_GET_KYC_CHECK_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_KYC_CHECK_RESULT_CLOSURE */
+
/**
- * Function called with the result of a KYC check.
+ * Type of the function that receives the result of a
+ * GET /kyc-check/$H_NORMALIZED_PAYTO request.
*
* @param cls closure
- * @param ks the account's KYC status details
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetKycCheckCallback)(
+ TALER_EXCHANGE_GET_KYC_CHECK_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetKycCheckResponse *result);
+
+
+/**
+ * Start GET /kyc-check/$H_NORMALIZED_PAYTO operation.
+ *
+ * @param[in,out] gkch 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_get_kyc_check_start (
+ struct TALER_EXCHANGE_GetKycCheckHandle *gkch,
+ TALER_EXCHANGE_GetKycCheckCallback cb,
+ TALER_EXCHANGE_GET_KYC_CHECK_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /kyc-check/$H_NORMALIZED_PAYTO operation. This function must
+ * not be called by clients after the TALER_EXCHANGE_GetKycCheckCallback has
+ * been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] gkch operation to cancel
+ */
+void
+TALER_EXCHANGE_get_kyc_check_cancel (
+ struct TALER_EXCHANGE_GetKycCheckHandle *gkch);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetKycCheckResponse instead.
+ */
+struct TALER_EXCHANGE_KycStatus
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct TALER_EXCHANGE_AccountKycStatus ok;
+ struct TALER_EXCHANGE_AccountKycStatus accepted;
+ struct
+ {
+ union TALER_AccountPublicKeyP expected_account_pub;
+ } forbidden;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetKycCheckCallback instead.
*/
typedef void
(*TALER_EXCHANGE_KycStatusCallback)(
void *cls,
const struct TALER_EXCHANGE_KycStatus *ks);
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetKycCheckHandle instead.
+ */
+struct TALER_EXCHANGE_KycCheckHandle;
/**
- * Run interaction with exchange to check KYC status of a merchant
- * or wallet account.
- *
- * @param ctx CURL context
- * @param url exchange base URL
- * @param h_payto hash of the account the KYC check is about
- * @param pk private key to authorize the request with
- * @param known_rule_gen latest known AML decision, for long polling
- * @param lpt target for long polling
- * @param timeout how long to wait for an answer, including possibly long polling for the desired @a lpt status
- * @param cb function to call with the result
- * @param cb_cls closure for @a cb
- * @return NULL on error
+ * @deprecated Use #TALER_EXCHANGE_get_kyc_check_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_KycCheckHandle *
TALER_EXCHANGE_kyc_check (
@@ -151,14 +394,12 @@ TALER_EXCHANGE_kyc_check (
TALER_EXCHANGE_KycStatusCallback cb,
void *cb_cls);
-
/**
- * Cancel KYC check operation.
- *
- * @param kyc handle for operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_get_kyc_check_cancel() instead.
*/
void
TALER_EXCHANGE_kyc_check_cancel (
struct TALER_EXCHANGE_KycCheckHandle *kyc);
-#endif
+
+#endif /* _TALER_EXCHANGE__GET_KYC_CHECK_H_NORMALIZED_PAYTO_H */
diff --git a/src/include/taler/taler-exchange/get-kyc-info-ACCESS_TOKEN.h b/src/include/taler/taler-exchange/get-kyc-info-ACCESS_TOKEN.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/get-kyc-info-ACCESS_TOKEN.h
@@ -24,19 +24,12 @@
#include <taler/taler-exchange/common.h>
/**
- * Handle for a "/kyc-info/" request.
- */
-struct TALER_EXCHANGE_KycInfoHandle;
-
-
-/**
- * Information about a KYC requirement.
+ * Information about a KYC requirement the client must satisfy.
*/
struct TALER_EXCHANGE_RequirementInformation
{
-
/**
- * Which form should be run. Special values are
+ * Which form should be run. Special values are
* "INFO" (only show information, no form) and
* "LINK" (only link to "/kyc-start/$ID").
*/
@@ -53,9 +46,8 @@ struct TALER_EXCHANGE_RequirementInformation
const json_t *description_i18n;
/**
- * ID of the requirement, NULL if
- * @e form is "INFO". Used to construct
- * the "/kyc-upload/$ID" and "/kyc-start/$ID" endpoints.
+ * ID of the requirement, NULL if @e form is "INFO".
+ * Used to construct the "/kyc-upload/$ID" and "/kyc-start/$ID" endpoints.
*/
const char *id;
@@ -63,12 +55,10 @@ struct TALER_EXCHANGE_RequirementInformation
/**
- * Information about a KYC check the client may
- * try to satisfy voluntarily.
+ * Information about a KYC check the client may satisfy voluntarily.
*/
struct TALER_EXCHANGE_VoluntaryCheckInformation
{
-
/**
* Name of the check.
*/
@@ -84,61 +74,220 @@ struct TALER_EXCHANGE_VoluntaryCheckInformation
*/
const json_t *description_i18n;
- // FIXME: is the above in any way sufficient
- // to begin the check? Do we not need at least
- // something more??!?
};
/**
- * KYC info response details.
+ * Possible options we can set for the GET kyc-info request.
*/
-struct TALER_EXCHANGE_KycProcessClientInformation
+enum TALER_EXCHANGE_GetKycInfoOption
{
/**
- * HTTP response data
+ * End of list of options.
*/
- struct TALER_EXCHANGE_HttpResponse hr;
+ TALER_EXCHANGE_GET_KYC_INFO_OPTION_END = 0,
+
+ /**
+ * HTTP ETag value from a previous response, for conditional requests.
+ * If the server's current ETag matches, it will respond with
+ * #MHD_HTTP_NOT_MODIFIED instead of repeating the full response.
+ * Combined with TIMEOUT to implement efficient long polling.
+ */
+ TALER_EXCHANGE_GET_KYC_INFO_OPTION_IF_NONE_MATCH,
+
+ /**
+ * How long to wait for a change relative to @e if_none_match,
+ * enabling long polling. Default is zero (no long polling).
+ */
+ TALER_EXCHANGE_GET_KYC_INFO_OPTION_TIMEOUT
+
+};
+
+/**
+ * Value for an option for the GET kyc-info request.
+ */
+struct TALER_EXCHANGE_GetKycInfoOptionValue
+{
/**
- * Details depending on @e http_status.
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_GetKycInfoOption option;
+
+ /**
+ * Specific option value.
*/
union
{
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_KYC_INFO_OPTION_IF_NONE_MATCH.
+ * HTTP ETag from a previous response. The string must remain valid
+ * for the lifetime of the operation.
+ */
+ const char *if_none_match;
/**
- * @e http_status is OK.
+ * Value if @e option is TALER_EXCHANGE_GET_KYC_INFO_OPTION_TIMEOUT.
+ */
+ struct GNUNET_TIME_Relative timeout;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to GET /kyc-info/$ACCESS_TOKEN.
+ */
+struct TALER_EXCHANGE_GetKycInfoHandle;
+
+
+/**
+ * Set up GET /kyc-info/$ACCESS_TOKEN operation.
+ * Note that you must explicitly start the operation after
+ * possibly setting options.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param token access token of the client
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetKycInfoHandle *
+TALER_EXCHANGE_get_kyc_info_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_AccountAccessTokenP *token);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_GetKycInfoOptionValue
+ */
+#define TALER_EXCHANGE_get_kyc_info_option_end_() \
+ (const struct TALER_EXCHANGE_GetKycInfoOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_KYC_INFO_OPTION_END \
+ }
+
+/**
+ * Set ETag for conditional request / long polling.
+ *
+ * @param e HTTP ETag string from a previous response
+ * @return representation of the option as a struct TALER_EXCHANGE_GetKycInfoOptionValue
+ */
+#define TALER_EXCHANGE_get_kyc_info_option_if_none_match(e) \
+ (const struct TALER_EXCHANGE_GetKycInfoOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_KYC_INFO_OPTION_IF_NONE_MATCH, \
+ .details.if_none_match = (e) \
+ }
+
+/**
+ * Set long-polling timeout.
+ *
+ * @param t how long to wait for a change
+ * @return representation of the option as a struct TALER_EXCHANGE_GetKycInfoOptionValue
+ */
+#define TALER_EXCHANGE_get_kyc_info_option_timeout(t) \
+ (const struct TALER_EXCHANGE_GetKycInfoOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_KYC_INFO_OPTION_TIMEOUT, \
+ .details.timeout = (t) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param gkih the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_get_kyc_info_set_options_ (
+ struct TALER_EXCHANGE_GetKycInfoHandle *gkih,
+ unsigned int num_options,
+ const struct TALER_EXCHANGE_GetKycInfoOptionValue *options);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * It should be used with helpers that create required options, for example:
+ *
+ * TALER_EXCHANGE_get_kyc_info_set_options (
+ * gkih,
+ * TALER_EXCHANGE_get_kyc_info_option_if_none_match (last_etag),
+ * TALER_EXCHANGE_get_kyc_info_option_timeout (timeout));
+ *
+ * @param gkih the request to set the options for
+ * @param ... the list of options, each created by a
+ * TALER_EXCHANGE_get_kyc_info_option_NAME(VALUE) helper
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_get_kyc_info_set_options(gkih,...) \
+ TALER_EXCHANGE_get_kyc_info_set_options_ ( \
+ gkih, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_GetKycInfoOptionValue[]) \
+ {__VA_ARGS__, TALER_EXCHANGE_get_kyc_info_option_end_ () } \
+ ))
+
+
+/**
+ * KYC info response.
+ */
+struct TALER_EXCHANGE_GetKycInfoResponse
+{
+ /**
+ * HTTP response data.
+ */
+ struct TALER_EXCHANGE_HttpResponse hr;
+
+ /**
+ * Details depending on @e hr.http_status.
+ */
+ union
+ {
+ /**
+ * Details if @e hr.http_status is #MHD_HTTP_OK.
*/
struct
{
-
/**
- * Array with information about available voluntary
- * checks.
+ * Array of KYC requirements the client must satisfy.
*/
const struct TALER_EXCHANGE_RequirementInformation *requirements;
/**
- * Array with information about available voluntary
- * checks.
- * FIXME: not implemented until **vATTEST**.
+ * Length of the @e requirements array.
*/
- const struct TALER_EXCHANGE_VoluntaryCheckInformation *vci;
+ size_t requirements_length;
/**
- * Length of the @e requirements array.
+ * Array of optional voluntary KYC checks available to the client.
+ * Not implemented until protocol vATTEST.
*/
- unsigned int requirements_length;
+ const struct TALER_EXCHANGE_VoluntaryCheckInformation *vci;
/**
* Length of the @e vci array.
*/
- unsigned int vci_length;
+ size_t vci_length;
/**
- * True if all @e requirements are expected to be
- * required, False if only one of the requirements
- * is expected to be fulfilled.
+ * True if ALL @e requirements must be fulfilled (AND combinator),
+ * false if ANY one of the requirements suffices (OR combinator).
*/
bool is_and_combinator;
@@ -148,31 +297,94 @@ struct TALER_EXCHANGE_KycProcessClientInformation
};
+
+#ifndef TALER_EXCHANGE_GET_KYC_INFO_RESULT_CLOSURE
/**
- * Function called with the result of a KYC info request.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetKycInfoCallback.
+ */
+#define TALER_EXCHANGE_GET_KYC_INFO_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_KYC_INFO_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * GET /kyc-info/$ACCESS_TOKEN request.
*
* @param cls closure
- * @param kpci information about available KYC operations
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetKycInfoCallback)(
+ TALER_EXCHANGE_GET_KYC_INFO_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetKycInfoResponse *result);
+
+
+/**
+ * Start GET /kyc-info/$ACCESS_TOKEN operation.
+ *
+ * @param[in,out] gkih 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_get_kyc_info_start (
+ struct TALER_EXCHANGE_GetKycInfoHandle *gkih,
+ TALER_EXCHANGE_GetKycInfoCallback cb,
+ TALER_EXCHANGE_GET_KYC_INFO_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /kyc-info/$ACCESS_TOKEN operation. This function must not be
+ * called by clients after the TALER_EXCHANGE_GetKycInfoCallback has been
+ * invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] gkih operation to cancel
+ */
+void
+TALER_EXCHANGE_get_kyc_info_cancel (
+ struct TALER_EXCHANGE_GetKycInfoHandle *gkih);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetKycInfoResponse instead.
+ */
+struct TALER_EXCHANGE_KycProcessClientInformation
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ const struct TALER_EXCHANGE_RequirementInformation *requirements;
+ const struct TALER_EXCHANGE_VoluntaryCheckInformation *vci;
+ unsigned int requirements_length;
+ unsigned int vci_length;
+ bool is_and_combinator;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetKycInfoCallback instead.
*/
typedef void
(*TALER_EXCHANGE_KycInfoCallback)(
void *cls,
const struct TALER_EXCHANGE_KycProcessClientInformation *kpci);
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetKycInfoHandle instead.
+ */
+struct TALER_EXCHANGE_KycInfoHandle;
/**
- * Run interaction with exchange to check KYC
- * information for a merchant or wallet account
- * identified via a @a token.
- *
- * @param ctx CURL context
- * @param url exchange base URL
- * @param token access token of the client
- * @param if_none_match HTTP ETag from previous response
- * @param timeout how long to wait for a change in @a if_none_match
- * @param cb function to call with the result
- * @param cb_cls closure for @a cb
- * @return NULL on error
+ * @deprecated Use #TALER_EXCHANGE_get_kyc_info_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_KycInfoHandle *
TALER_EXCHANGE_kyc_info (
@@ -184,13 +396,12 @@ TALER_EXCHANGE_kyc_info (
TALER_EXCHANGE_KycInfoCallback cb,
void *cb_cls);
-
/**
- * Cancel KYC info operation.
- *
- * @param kih handle for operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_get_kyc_info_cancel() instead.
*/
void
-TALER_EXCHANGE_kyc_info_cancel (struct TALER_EXCHANGE_KycInfoHandle *kih);
+TALER_EXCHANGE_kyc_info_cancel (
+ struct TALER_EXCHANGE_KycInfoHandle *kih);
+
-#endif
+#endif /* _TALER_EXCHANGE__GET_KYC_INFO_ACCESS_TOKEN_H */
diff --git a/src/include/taler/taler-exchange/get-kyc-proof-PROVIDER_NAME.h b/src/include/taler/taler-exchange/get-kyc-proof-PROVIDER_NAME.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/get-kyc-proof-PROVIDER_NAME.h
@@ -24,26 +24,170 @@
#include <taler/taler-exchange/common.h>
/**
- * KYC proof response details.
+ * Possible options we can set for the GET kyc-proof request.
*/
-struct TALER_EXCHANGE_KycProofResponse
+enum TALER_EXCHANGE_GetKycProofOption
{
/**
- * HTTP response data
+ * End of list of options.
*/
- struct TALER_EXCHANGE_HttpResponse hr;
+ TALER_EXCHANGE_GET_KYC_PROOF_OPTION_END = 0,
+
+ /**
+ * Additional arguments to append to the URL (must begin with '&').
+ * Used to pass provider-specific query parameters.
+ */
+ TALER_EXCHANGE_GET_KYC_PROOF_OPTION_ARGS
+
+};
+
+/**
+ * Value for an option for the GET kyc-proof request.
+ */
+struct TALER_EXCHANGE_GetKycProofOptionValue
+{
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_GetKycProofOption option;
+
+ /**
+ * Specific option value.
+ */
union
{
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_KYC_PROOF_OPTION_ARGS.
+ * Additional query string to append to the URL. Must begin with '&'.
+ * The string must remain valid for the lifetime of the operation.
+ */
+ const char *args;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to GET /kyc-proof/$PROVIDER_NAME.
+ */
+struct TALER_EXCHANGE_GetKycProofHandle;
+
+
+/**
+ * Set up GET /kyc-proof/$PROVIDER_NAME operation.
+ * Note that you must explicitly start the operation after
+ * possibly setting options.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param h_payto hash of the payto URI identifying the target account
+ * @param logic name of the KYC logic / provider to use
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetKycProofHandle *
+TALER_EXCHANGE_get_kyc_proof_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_NormalizedPaytoHashP *h_payto,
+ const char *logic);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_GetKycProofOptionValue
+ */
+#define TALER_EXCHANGE_get_kyc_proof_option_end_() \
+ (const struct TALER_EXCHANGE_GetKycProofOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_KYC_PROOF_OPTION_END \
+ }
+
+/**
+ * Set additional query string arguments to append to the URL.
+ *
+ * @param a additional args string, must begin with '&', must remain valid
+ * for the lifetime of the operation
+ * @return representation of the option as a struct TALER_EXCHANGE_GetKycProofOptionValue
+ */
+#define TALER_EXCHANGE_get_kyc_proof_option_args(a) \
+ (const struct TALER_EXCHANGE_GetKycProofOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_KYC_PROOF_OPTION_ARGS, \
+ .details.args = (a) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param gkph the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_get_kyc_proof_set_options_ (
+ struct TALER_EXCHANGE_GetKycProofHandle *gkph,
+ unsigned int num_options,
+ const struct TALER_EXCHANGE_GetKycProofOptionValue *options);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * It should be used with helpers that create required options, for example:
+ *
+ * TALER_EXCHANGE_get_kyc_proof_set_options (
+ * gkph,
+ * TALER_EXCHANGE_get_kyc_proof_option_args ("&state=xyz"));
+ *
+ * @param gkph the request to set the options for
+ * @param ... the list of options, each created by a
+ * TALER_EXCHANGE_get_kyc_proof_option_NAME(VALUE) helper
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_get_kyc_proof_set_options(gkph,...) \
+ TALER_EXCHANGE_get_kyc_proof_set_options_ ( \
+ gkph, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_GetKycProofOptionValue[]) \
+ {__VA_ARGS__, TALER_EXCHANGE_get_kyc_proof_option_end_ () } \
+ ))
+
+/**
+ * Response from a GET /kyc-proof/$PROVIDER_NAME request.
+ */
+struct TALER_EXCHANGE_GetKycProofResponse
+{
+ /**
+ * HTTP response data.
+ */
+ struct TALER_EXCHANGE_HttpResponse hr;
+
+ /**
+ * Details depending on HTTP status.
+ */
+ union
+ {
/**
- * KYC is OK, affirmation returned by the exchange.
+ * Details on #MHD_HTTP_FOUND (redirect).
*/
struct
{
-
/**
- * Where to redirect the client next.
+ * URL to redirect the client to next.
*/
const char *redirect_url;
@@ -53,36 +197,90 @@ struct TALER_EXCHANGE_KycProofResponse
};
+
+#ifndef TALER_EXCHANGE_GET_KYC_PROOF_RESULT_CLOSURE
/**
- * Function called with the result of a KYC check.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetKycProofCallback.
+ */
+#define TALER_EXCHANGE_GET_KYC_PROOF_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_KYC_PROOF_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * GET /kyc-proof/$PROVIDER_NAME request.
*
* @param cls closure
- * @param kpr the account's KYC status details
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetKycProofCallback)(
+ TALER_EXCHANGE_GET_KYC_PROOF_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetKycProofResponse *result);
+
+
+/**
+ * Start GET /kyc-proof/$PROVIDER_NAME operation.
+ *
+ * @param[in,out] gkph 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_get_kyc_proof_start (
+ struct TALER_EXCHANGE_GetKycProofHandle *gkph,
+ TALER_EXCHANGE_GetKycProofCallback cb,
+ TALER_EXCHANGE_GET_KYC_PROOF_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /kyc-proof/$PROVIDER_NAME operation. This function must not
+ * be called by clients after the TALER_EXCHANGE_GetKycProofCallback has been
+ * invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] gkph operation to cancel
+ */
+void
+TALER_EXCHANGE_get_kyc_proof_cancel (
+ struct TALER_EXCHANGE_GetKycProofHandle *gkph);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetKycProofResponse instead.
+ */
+struct TALER_EXCHANGE_KycProofResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ const char *redirect_url;
+ } found;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetKycProofCallback instead.
*/
typedef void
(*TALER_EXCHANGE_KycProofCallback)(
void *cls,
const struct TALER_EXCHANGE_KycProofResponse *kpr);
-
/**
- * Handle for a /kyc-proof operation.
+ * @deprecated Use #TALER_EXCHANGE_GetKycProofHandle instead.
*/
struct TALER_EXCHANGE_KycProofHandle;
-
/**
- * Run interaction with exchange to provide proof of KYC status.
- *
- * @param ctx CURL context
- * @param url exchange base URL
- * @param h_payto hash of payto URI identifying the target account
- * @param logic name of the KYC logic to run
- * @param args additional args to pass, can be NULL
- * or a string to append to the URL. Must then begin with '&'.
- * @param cb function to call with the result
- * @param cb_cls closure for @a cb
- * @return NULL on error
+ * @deprecated Use #TALER_EXCHANGE_get_kyc_proof_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_KycProofHandle *
TALER_EXCHANGE_kyc_proof (
@@ -94,13 +292,12 @@ TALER_EXCHANGE_kyc_proof (
TALER_EXCHANGE_KycProofCallback cb,
void *cb_cls);
-
/**
- * Cancel KYC proof operation.
- *
- * @param kph handle for operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_get_kyc_proof_cancel() instead.
*/
void
-TALER_EXCHANGE_kyc_proof_cancel (struct TALER_EXCHANGE_KycProofHandle *kph);
+TALER_EXCHANGE_kyc_proof_cancel (
+ struct TALER_EXCHANGE_KycProofHandle *kph);
+
-#endif
+#endif /* _TALER_EXCHANGE__GET_KYC_PROOF_PROVIDER_NAME_H */
diff --git a/src/include/taler/taler-exchange/get-kyc-spa-ACCESS_TOKEN.h b/src/include/taler/taler-exchange/get-kyc-spa-ACCESS_TOKEN.h
@@ -0,0 +1,40 @@
+/*
+ This file is part of TALER
+ Copyright (C) 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/taler-exchange/get-kyc-spa-ACCESS_TOKEN.h
+ * @brief C interface for GET /kyc-spa/$ACCESS_TOKEN
+ * @author Christian Grothoff
+ */
+#ifndef _TALER_EXCHANGE__GET_KYC_SPA_ACCESS_TOKEN_H
+#define _TALER_EXCHANGE__GET_KYC_SPA_ACCESS_TOKEN_H
+
+/*
+ * The GET /kyc-spa/$ACCESS_TOKEN endpoint serves a browser-facing
+ * Single Page Application (SPA) for KYC. The SPA uses the $ACCESS_TOKEN
+ * to initialize itself via GET /kyc-info/$ACCESS_TOKEN. Additional
+ * SPA resources may be downloaded via GET /kyc-spa/$FILENAME.
+ *
+ * This endpoint is intended for browser clients. There is no C
+ * client library API for this endpoint, as it returns HTML/JavaScript
+ * rather than JSON.
+ *
+ * Introduced in protocol v20.
+ *
+ * See get-kyc-info-ACCESS_TOKEN.h for the API that the SPA uses
+ * to determine what KYC checks need to be performed.
+ */
+
+#endif /* _TALER_EXCHANGE__GET_KYC_SPA_ACCESS_TOKEN_H */
diff --git a/src/include/taler/taler-exchange/get-management-keys.h b/src/include/taler/taler-exchange/get-management-keys.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/get-management-keys.h
@@ -23,16 +23,19 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /management *********************** */
+/**
+ * Handle for an operation to GET /management/keys.
+ */
+struct TALER_EXCHANGE_GetManagementKeysHandle;
/**
- * @brief Future Exchange's signature key
+ * @brief Future signing public key of the exchange.
*/
struct TALER_EXCHANGE_FutureSigningPublicKey
{
/**
- * The signing public key
+ * The signing public key.
*/
struct TALER_ExchangePublicKeyP key;
@@ -42,7 +45,7 @@ struct TALER_EXCHANGE_FutureSigningPublicKey
struct TALER_SecurityModuleSignatureP signkey_secmod_sig;
/**
- * Validity start time
+ * Validity start time.
*/
struct GNUNET_TIME_Timestamp valid_from;
@@ -59,12 +62,12 @@ struct TALER_EXCHANGE_FutureSigningPublicKey
/**
- * @brief Public information about a future exchange's denomination key
+ * @brief Public information about a future denomination key of the exchange.
*/
struct TALER_EXCHANGE_FutureDenomPublicKey
{
/**
- * The public key
+ * The public key.
*/
struct TALER_DenominationPublicKey key;
@@ -74,13 +77,13 @@ struct TALER_EXCHANGE_FutureDenomPublicKey
struct TALER_SecurityModuleSignatureP denom_secmod_sig;
/**
- * Timestamp indicating when the denomination key becomes valid
+ * Timestamp indicating when the denomination key becomes valid.
*/
struct GNUNET_TIME_Timestamp valid_from;
/**
- * Timestamp indicating when the denomination key can’t be used anymore to
- * withdraw new coins.
+ * Timestamp indicating when the denomination key can no longer
+ * be used for new withdrawals.
*/
struct GNUNET_TIME_Timestamp withdraw_valid_until;
@@ -91,35 +94,32 @@ struct TALER_EXCHANGE_FutureDenomPublicKey
/**
* When do signatures with this denomination key become invalid?
- * After this point, these signatures cannot be used in (legal)
- * disputes anymore, as the Exchange is then allowed to destroy its side
- * of the evidence. @e expire_legal is expected to be significantly
- * larger than @e expire_deposit (by a year or more).
+ * After this point these signatures cannot be used in legal disputes.
*/
struct GNUNET_TIME_Timestamp expire_legal;
/**
- * The value of this denomination
+ * The value of this denomination.
*/
struct TALER_Amount value;
/**
- * The applicable fee for withdrawing a coin of this denomination
+ * The applicable fee for withdrawing a coin of this denomination.
*/
struct TALER_Amount fee_withdraw;
/**
- * The applicable fee to spend a coin of this denomination
+ * The applicable fee to spend a coin of this denomination.
*/
struct TALER_Amount fee_deposit;
/**
- * The applicable fee to melt/refresh a coin of this denomination
+ * The applicable fee to melt/refresh a coin of this denomination.
*/
struct TALER_Amount fee_refresh;
/**
- * The applicable fee to refund a coin of this denomination
+ * The applicable fee to refund a coin of this denomination.
*/
struct TALER_Amount fee_refund;
@@ -131,14 +131,13 @@ struct TALER_EXCHANGE_FutureDenomPublicKey
*/
struct TALER_EXCHANGE_FutureKeys
{
-
/**
- * Array of the exchange's online signing keys.
+ * Array of the exchange's future online signing keys.
*/
struct TALER_EXCHANGE_FutureSigningPublicKey *sign_keys;
/**
- * Array of the exchange's denomination keys.
+ * Array of the exchange's future denomination keys.
*/
struct TALER_EXCHANGE_FutureDenomPublicKey *denom_keys;
@@ -163,7 +162,7 @@ struct TALER_EXCHANGE_FutureKeys
struct TALER_MasterPublicKeyP master_pub;
/**
- * Length of the @e sign_keys array (number of valid entries).
+ * Length of the @e sign_keys array.
*/
unsigned int num_sign_keys;
@@ -176,12 +175,12 @@ struct TALER_EXCHANGE_FutureKeys
/**
- * Response from a /management/keys request.
+ * Response from a GET /management/keys request.
*/
-struct TALER_EXCHANGE_ManagementGetKeysResponse
+struct TALER_EXCHANGE_GetManagementKeysResponse
{
/**
- * HTTP response data
+ * HTTP response data.
*/
struct TALER_EXCHANGE_HttpResponse hr;
@@ -196,8 +195,7 @@ struct TALER_EXCHANGE_ManagementGetKeysResponse
struct
{
/**
- * information about the various keys used
- * by the exchange
+ * Information about the various future keys used by the exchange.
*/
struct TALER_EXCHANGE_FutureKeys keys;
@@ -207,49 +205,107 @@ struct TALER_EXCHANGE_ManagementGetKeysResponse
};
+#ifndef TALER_EXCHANGE_GET_MANAGEMENT_KEYS_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetManagementKeysCallback.
+ */
+#define TALER_EXCHANGE_GET_MANAGEMENT_KEYS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_MANAGEMENT_KEYS_RESULT_CLOSURE */
+
/**
- * Function called with information about future keys.
+ * Type of the function that receives the result of a
+ * GET /management/keys request.
*
* @param cls closure
- * @param mgr HTTP response data
+ * @param result result returned by the HTTP server
*/
typedef void
-(*TALER_EXCHANGE_ManagementGetKeysCallback) (
- void *cls,
- const struct TALER_EXCHANGE_ManagementGetKeysResponse *mgr);
+(*TALER_EXCHANGE_GetManagementKeysCallback)(
+ TALER_EXCHANGE_GET_MANAGEMENT_KEYS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetManagementKeysResponse *result);
/**
- * @brief Handle for a GET /management/keys request.
+ * Set up GET /management/keys operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @return handle to operation
*/
-struct TALER_EXCHANGE_ManagementGetKeysHandle;
+struct TALER_EXCHANGE_GetManagementKeysHandle *
+TALER_EXCHANGE_get_management_keys_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url);
/**
- * Request future keys from the exchange. The obtained information will be
- * passed to the @a cb.
+ * Start GET /management/keys operation.
*
- * @param ctx the context
- * @param url HTTP base URL for the exchange
- * @param cb function to call with the exchange's future keys result
+ * @param[in,out] gmkh operation to start
+ * @param cb function to call with the exchange's result
* @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @return status code, #TALER_EC_NONE on success
*/
-struct TALER_EXCHANGE_ManagementGetKeysHandle *
-TALER_EXCHANGE_get_management_keys (
- struct GNUNET_CURL_Context *ctx,
- const char *url,
- TALER_EXCHANGE_ManagementGetKeysCallback cb,
- void *cb_cls);
+enum TALER_ErrorCode
+TALER_EXCHANGE_get_management_keys_start (
+ struct TALER_EXCHANGE_GetManagementKeysHandle *gmkh,
+ TALER_EXCHANGE_GetManagementKeysCallback cb,
+ TALER_EXCHANGE_GET_MANAGEMENT_KEYS_RESULT_CLOSURE *cb_cls);
/**
- * Cancel #TALER_EXCHANGE_get_management_keys() operation.
+ * Cancel GET /management/keys operation. This function must not be called
+ * by clients after the TALER_EXCHANGE_GetManagementKeysCallback has been
+ * invoked (as in those cases it'll be called internally by the
+ * implementation already).
*
- * @param gh handle of the operation to cancel
+ * @param[in] gmkh operation to cancel
*/
void
TALER_EXCHANGE_get_management_keys_cancel (
- struct TALER_EXCHANGE_ManagementGetKeysHandle *gh);
+ struct TALER_EXCHANGE_GetManagementKeysHandle *gmkh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetManagementKeysResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementGetKeysResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct TALER_EXCHANGE_FutureKeys keys;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetManagementKeysCallback instead.
+ */
+typedef void
+(*TALER_EXCHANGE_ManagementGetKeysCallback) (
+ void *cls,
+ const struct TALER_EXCHANGE_ManagementGetKeysResponse *mgr);
+
+
+/**
+ * @deprecated
+ */
+TALER_EXCHANGE_GetManagementKeysHandle *
+TALER_EXCHANGE_get_management_keys (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ TALER_EXCHANGE_ManagementGetKeysCallback cb,
+ void *cb_cls);
+
+/* Note: cancel uses TALER_EXCHANGE_get_management_keys_cancel() declared above. */
+
-#endif
+#endif /* _TALER_EXCHANGE__GET_MANAGEMENT_KEYS_H */
diff --git a/src/include/taler/taler-exchange/get-purses-PURSE_PUB-merge.h b/src/include/taler/taler-exchange/get-purses-PURSE_PUB-merge.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/get-purses-PURSE_PUB-merge.h
@@ -24,12 +24,179 @@
#include <taler/taler-exchange/common.h>
/**
- * Response generated for a purse get request.
+ * Possible options we can set for the GET purses/merge request.
*/
-struct TALER_EXCHANGE_PurseGetResponse
+enum TALER_EXCHANGE_GetPursesOption
+{
+ /**
+ * End of list of options.
+ */
+ TALER_EXCHANGE_GET_PURSES_OPTION_END = 0,
+
+ /**
+ * How long to wait for a change to happen, enabling long polling.
+ * Default is zero (no long polling).
+ */
+ TALER_EXCHANGE_GET_PURSES_OPTION_TIMEOUT,
+
+ /**
+ * If set to true, wait for a merge event (the purse becoming merged).
+ * If set to false (the default), wait for a deposit event
+ * (sufficient funds being deposited into the purse).
+ */
+ TALER_EXCHANGE_GET_PURSES_OPTION_WAIT_FOR_MERGE
+
+};
+
+
+/**
+ * Value for an option for the GET purses/merge request.
+ */
+struct TALER_EXCHANGE_GetPursesOptionValue
{
/**
- * Full HTTP response.
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_GetPursesOption option;
+
+ /**
+ * Specific option value.
+ */
+ union
+ {
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_PURSES_OPTION_TIMEOUT.
+ */
+ struct GNUNET_TIME_Relative timeout;
+
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_PURSES_OPTION_WAIT_FOR_MERGE.
+ * True to wait for merge, false to wait for deposit (default).
+ */
+ bool wait_for_merge;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to GET /purses/$PURSE_PUB/merge.
+ */
+struct TALER_EXCHANGE_GetPursesHandle;
+
+
+/**
+ * Set up GET /purses/$PURSE_PUB/merge operation.
+ * Note that you must explicitly start the operation after
+ * possibly setting options.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param keys exchange keys for signature verification
+ * @param purse_pub public key of the purse to query
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetPursesHandle *
+TALER_EXCHANGE_get_purses_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_PurseContractPublicKeyP *purse_pub);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_GetPursesOptionValue
+ */
+#define TALER_EXCHANGE_get_purses_option_end_() \
+ (const struct TALER_EXCHANGE_GetPursesOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_PURSES_OPTION_END \
+ }
+
+/**
+ * Set long-polling timeout.
+ *
+ * @param t how long to wait for a change to happen
+ * @return representation of the option as a struct TALER_EXCHANGE_GetPursesOptionValue
+ */
+#define TALER_EXCHANGE_get_purses_option_timeout(t) \
+ (const struct TALER_EXCHANGE_GetPursesOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_PURSES_OPTION_TIMEOUT, \
+ .details.timeout = (t) \
+ }
+
+/**
+ * Set whether to wait for a merge event (true) or a deposit event (false).
+ *
+ * @param w true to wait for merge, false to wait for deposit
+ * @return representation of the option as a struct TALER_EXCHANGE_GetPursesOptionValue
+ */
+#define TALER_EXCHANGE_get_purses_option_wait_for_merge(w) \
+ (const struct TALER_EXCHANGE_GetPursesOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_PURSES_OPTION_WAIT_FOR_MERGE, \
+ .details.wait_for_merge = (w) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param gph the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_get_purses_set_options_ (
+ struct TALER_EXCHANGE_GetPursesHandle *gph,
+ unsigned int num_options,
+ const struct TALER_EXCHANGE_GetPursesOptionValue *options);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * It should be used with helpers that create required options, for example:
+ *
+ * TALER_EXCHANGE_get_purses_set_options (
+ * gph,
+ * TALER_EXCHANGE_get_purses_option_timeout (timeout),
+ * TALER_EXCHANGE_get_purses_option_wait_for_merge (true));
+ *
+ * @param gph the request to set the options for
+ * @param ... the list of options, each created by a
+ * TALER_EXCHANGE_get_purses_option_NAME(VALUE) helper
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_get_purses_set_options(gph,...) \
+ TALER_EXCHANGE_get_purses_set_options_ ( \
+ gph, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_GetPursesOptionValue[]) \
+ {__VA_ARGS__, TALER_EXCHANGE_get_purses_option_end_ () } \
+ ))
+
+
+/**
+ * Response from a GET /purses/$PURSE_PUB/merge request.
+ */
+struct TALER_EXCHANGE_GetPursesResponse
+{
+ /**
+ * HTTP response data.
*/
struct TALER_EXCHANGE_HttpResponse hr;
@@ -43,23 +210,19 @@ struct TALER_EXCHANGE_PurseGetResponse
*/
struct
{
-
/**
- * Time when the purse was merged (or zero if it
- * was not merged).
+ * Time when the purse was merged (or zero if not merged yet).
*/
struct GNUNET_TIME_Timestamp merge_timestamp;
/**
- * Time when the full amount was deposited into
- * the purse (or zero if a sufficient amount
- * was not yet deposited).
+ * Time when the full amount was deposited into the purse
+ * (or zero if a sufficient amount was not yet deposited).
*/
struct GNUNET_TIME_Timestamp deposit_timestamp;
/**
- * Reserve balance (how much was deposited in
- * total into the reserve, minus deposit fees).
+ * Reserve balance (total deposited minus deposit fees).
*/
struct TALER_Amount balance;
@@ -75,36 +238,92 @@ struct TALER_EXCHANGE_PurseGetResponse
};
+#ifndef TALER_EXCHANGE_GET_PURSES_RESULT_CLOSURE
/**
- * Function called with information about the a purse.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetPursesCallback.
+ */
+#define TALER_EXCHANGE_GET_PURSES_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_PURSES_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * GET /purses/$PURSE_PUB/merge request.
*
* @param cls closure
- * @param pgr HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetPursesCallback)(
+ TALER_EXCHANGE_GET_PURSES_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetPursesResponse *result);
+
+
+/**
+ * Start GET /purses/$PURSE_PUB/merge operation.
+ *
+ * @param[in,out] gph 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_get_purses_start (
+ struct TALER_EXCHANGE_GetPursesHandle *gph,
+ TALER_EXCHANGE_GetPursesCallback cb,
+ TALER_EXCHANGE_GET_PURSES_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /purses/$PURSE_PUB/merge operation. This function must not be
+ * called by clients after the TALER_EXCHANGE_GetPursesCallback has been
+ * invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] gph operation to cancel
+ */
+void
+TALER_EXCHANGE_get_purses_cancel (
+ struct TALER_EXCHANGE_GetPursesHandle *gph);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetPursesResponse instead.
+ */
+struct TALER_EXCHANGE_PurseGetResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct GNUNET_TIME_Timestamp merge_timestamp;
+ struct GNUNET_TIME_Timestamp deposit_timestamp;
+ struct TALER_Amount balance;
+ struct GNUNET_TIME_Timestamp purse_expiration;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetPursesCallback instead.
*/
typedef void
(*TALER_EXCHANGE_PurseGetCallback) (
void *cls,
const struct TALER_EXCHANGE_PurseGetResponse *pgr);
-
/**
- * @brief Handle for a GET /purses/$PPUB request.
+ * @deprecated Use #TALER_EXCHANGE_GetPursesHandle instead.
*/
struct TALER_EXCHANGE_PurseGetHandle;
-
/**
- * Request information about a purse from the exchange.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param purse_pub public key of the purse
- * @param timeout how long to wait for a change to happen
- * @param wait_for_merge true to wait for a merge event, otherwise wait for a deposit event
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_get_purses_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_PurseGetHandle *
TALER_EXCHANGE_purse_get (
@@ -117,14 +336,12 @@ TALER_EXCHANGE_purse_get (
TALER_EXCHANGE_PurseGetCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_purse_get() operation.
- *
- * @param pgh handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_get_purses_cancel() instead.
*/
void
TALER_EXCHANGE_purse_get_cancel (
struct TALER_EXCHANGE_PurseGetHandle *pgh);
-#endif
+
+#endif /* _TALER_EXCHANGE__GET_PURSES_PURSE_PUB_MERGE_H */
diff --git a/src/include/taler/taler-exchange/get-reserves-RESERVE_PUB-history.h b/src/include/taler/taler-exchange/get-reserves-RESERVE_PUB-history.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/get-reserves-RESERVE_PUB-history.h
@@ -22,42 +22,175 @@
#define _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_HISTORY_H
#include <taler/taler-exchange/common.h>
-
-/* ********************* GET /reserves/$RESERVE_PUB/history *********************** */
+#include <taler/taler-exchange/get-reserves-RESERVE_PUB.h>
/**
- * @brief A /reserves/$RID/history Handle
+ * Possible options we can set for the GET reserves history request.
*/
-struct TALER_EXCHANGE_ReservesHistoryHandle;
+enum TALER_EXCHANGE_GetReservesHistoryOption
+{
+ /**
+ * End of list of options.
+ */
+ TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_END = 0,
+
+ /**
+ * Only return entries with offset strictly greater than this value.
+ * Defaults to 0 (return all entries).
+ * The offset corresponds to the etag / last entry offset from a
+ * previous response.
+ */
+ TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_START_OFF
+
+};
/**
- * @brief Reserve history details.
+ * Value for an option for the GET reserves history request.
*/
-struct TALER_EXCHANGE_ReserveHistory
+struct TALER_EXCHANGE_GetReservesHistoryOptionValue
{
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_GetReservesHistoryOption option;
/**
- * High-level HTTP response details.
+ * Specific option value.
+ */
+ union
+ {
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_START_OFF.
+ */
+ uint64_t start_off;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to GET /reserves/$RESERVE_PUB/history.
+ */
+struct TALER_EXCHANGE_GetReservesHistoryHandle;
+
+
+/**
+ * Set up GET /reserves/$RESERVE_PUB/history operation.
+ * Note that you must explicitly start the operation after
+ * possibly setting options.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param keys exchange keys for signature verification
+ * @param reserve_priv private key of the reserve to inspect
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetReservesHistoryHandle *
+TALER_EXCHANGE_get_reserves_history_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_ReservePrivateKeyP *reserve_priv);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_GetReservesHistoryOptionValue
+ */
+#define TALER_EXCHANGE_get_reserves_history_option_end_() \
+ (const struct TALER_EXCHANGE_GetReservesHistoryOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_END \
+ }
+
+/**
+ * Set starting offset for partial history fetch.
+ *
+ * @param o offset: only return entries with offset > this value.
+ * Use the etag value from a previous response.
+ * @return representation of the option as a struct TALER_EXCHANGE_GetReservesHistoryOptionValue
+ */
+#define TALER_EXCHANGE_get_reserves_history_option_start_off(o) \
+ (const struct TALER_EXCHANGE_GetReservesHistoryOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_START_OFF, \
+ .details.start_off = (o) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param grhh the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_get_reserves_history_set_options_ (
+ struct TALER_EXCHANGE_GetReservesHistoryHandle *grhh,
+ unsigned int num_options,
+ const struct TALER_EXCHANGE_GetReservesHistoryOptionValue *options);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * It should be used with helpers that create required options, for example:
+ *
+ * TALER_EXCHANGE_get_reserves_history_set_options (
+ * grhh,
+ * TALER_EXCHANGE_get_reserves_history_option_start_off (last_etag));
+ *
+ * @param grhh the request to set the options for
+ * @param ... the list of options, each created by a
+ * TALER_EXCHANGE_get_reserves_history_option_NAME(VALUE) helper
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_get_reserves_history_set_options(grhh,...) \
+ TALER_EXCHANGE_get_reserves_history_set_options_ ( \
+ grhh, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_GetReservesHistoryOptionValue[]) \
+ {__VA_ARGS__, \
+ TALER_EXCHANGE_get_reserves_history_option_end_ () } \
+ ))
+
+
+/**
+ * @brief Reserve history response.
+ */
+struct TALER_EXCHANGE_GetReservesHistoryResponse
+{
+ /**
+ * HTTP response data.
*/
struct TALER_EXCHANGE_HttpResponse hr;
/**
- * Details depending on @e hr.http_history.
+ * Details depending on @e hr.http_status.
*/
union
{
-
/**
- * Information returned on success, if
- * @e hr.http_history is #MHD_HTTP_OK
+ * Information returned on #MHD_HTTP_OK.
*/
struct
{
-
/**
- * Current reserve balance. May not be the difference between
- * @e total_in and @e total_out because the @e may be truncated.
+ * Current reserve balance. May differ from total_in - total_out
+ * if the history is truncated.
*/
struct TALER_Amount balance;
@@ -72,21 +205,21 @@ struct TALER_EXCHANGE_ReserveHistory
struct TALER_Amount total_out;
/**
- * Current etag / last entry in the history.
- * Useful to filter requests by starting offset.
+ * Current etag / last entry offset in the history.
+ * Use this as the start_off option for incremental fetches.
* Offsets are not necessarily contiguous.
*/
uint64_t etag;
/**
- * Reserve history.
+ * Reserve transaction history.
*/
const struct TALER_EXCHANGE_ReserveHistoryEntry *history;
/**
* Length of the @e history array.
*/
- unsigned int history_len;
+ size_t history_len;
} ok;
@@ -95,31 +228,94 @@ struct TALER_EXCHANGE_ReserveHistory
};
+#ifndef TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetReservesHistoryCallback.
+ */
+#define TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE */
+
/**
- * Callbacks of this type are used to serve the result of submitting a
- * reserve history request to a exchange.
+ * Type of the function that receives the result of a
+ * GET /reserves/$RESERVE_PUB/history request.
*
* @param cls closure
- * @param rs HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetReservesHistoryCallback)(
+ TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetReservesHistoryResponse *result);
+
+
+/**
+ * Start GET /reserves/$RESERVE_PUB/history operation.
+ *
+ * @param[in,out] grhh 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_get_reserves_history_start (
+ struct TALER_EXCHANGE_GetReservesHistoryHandle *grhh,
+ TALER_EXCHANGE_GetReservesHistoryCallback cb,
+ TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /reserves/$RESERVE_PUB/history operation. This function must
+ * not be called by clients after the TALER_EXCHANGE_GetReservesHistoryCallback
+ * has been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] grhh operation to cancel
+ */
+void
+TALER_EXCHANGE_get_reserves_history_cancel (
+ struct TALER_EXCHANGE_GetReservesHistoryHandle *grhh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetReservesHistoryResponse instead.
+ */
+struct TALER_EXCHANGE_ReserveHistory
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct TALER_Amount balance;
+ struct TALER_Amount total_in;
+ struct TALER_Amount total_out;
+ uint64_t etag;
+ const struct TALER_EXCHANGE_ReserveHistoryEntry *history;
+ unsigned int history_len;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetReservesHistoryCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ReservesHistoryCallback) (
void *cls,
const struct TALER_EXCHANGE_ReserveHistory *rs);
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetReservesHistoryHandle instead.
+ */
+struct TALER_EXCHANGE_ReservesHistoryHandle;
/**
- * Submit a request to obtain the reserve history.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param reserve_priv private key of the reserve to inspect
- * @param start_off offset of the oldest history entry to exclude from the response
- * @param cb the callback to call when a reply for this request is available
- * @param cb_cls closure for the above callback
- * @return a handle for this request; NULL if the inputs are invalid (i.e.
- * signatures fail to verify). In this case, the callback is not called.
+ * @deprecated Use #TALER_EXCHANGE_get_reserves_history_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ReservesHistoryHandle *
TALER_EXCHANGE_reserves_history (
@@ -131,15 +327,12 @@ TALER_EXCHANGE_reserves_history (
TALER_EXCHANGE_ReservesHistoryCallback cb,
void *cb_cls);
-
/**
- * Cancel a reserve history request. This function cannot be used
- * on a request handle if a response is already served for it.
- *
- * @param rsh the reserve request handle
+ * @deprecated Use #TALER_EXCHANGE_get_reserves_history_cancel() instead.
*/
void
TALER_EXCHANGE_reserves_history_cancel (
struct TALER_EXCHANGE_ReservesHistoryHandle *rsh);
-#endif
+
+#endif /* _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_HISTORY_H */
diff --git a/src/include/taler/taler-exchange/get-reserves-RESERVE_PUB.h b/src/include/taler/taler-exchange/get-reserves-RESERVE_PUB.h
@@ -1,21 +1,21 @@
/*
- This file is part of TALER
- Copyright (C) 2025 Taler Systems SA
+ This file is part of TALER
+ Copyright (C) 2025, 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 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.
+ 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/>
+ 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/taler-exchange/get-reserves-RESERVE_PUB.h
- * @brief C interface for the GET /reserves/$RESERVE_PUB endpoint
+ * @brief C interface for GET /reserves/$RESERVE_PUB
* @author Christian Grothoff
*/
#ifndef _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_H
@@ -114,61 +114,59 @@ struct TALER_EXCHANGE_ReserveHistoryEntry
} in_details;
/**
- * Information about withdraw operation with age-restriction.
+ * Information about a withdrawal operation.
* @e type is #TALER_EXCHANGE_RTT_WITHDRAWAL.
*/
struct
{
/**
- * Signature authorizing the withdrawal for outgoing transaction.
+ * Signature authorizing the withdrawal.
*/
json_t *out_authorization_sig;
/**
- * The running hash over all hashes of blinded planchets of the withrdawal
+ * Running hash over all hashes of blinded planchets of the withdrawal.
*/
struct TALER_HashBlindedPlanchetsP planchets_h;
/**
- * If age restriction was required during the protocol
+ * True if age restriction was required during the protocol.
*/
bool age_restricted;
/**
- * Maximum age committed, if age_restricted is true
+ * Maximum age committed, if @e age_restricted is true.
*/
uint8_t max_age;
/**
- * If @e age_restricted is true, the index that is not to be revealed
- * after the initial commitment in /withdraw
+ * If @e age_restricted is true, the index not to be revealed
+ * after the initial commitment in /withdraw.
*/
uint8_t noreveal_index;
/**
- * If @e age_restricted is true, the hash of the selected blinded planchets
+ * If @e age_restricted is true, hash of the selected blinded planchets.
*/
struct TALER_HashBlindedPlanchetsP selected_h;
/**
- * True, if no blinding_seed was provided. The value of
- * @e blinding_seed is then zero.
+ * True if no blinding_seed was provided.
*/
bool no_blinding_seed;
/**
- * In case of denominations of cipher type Clause-Schnorr, the
- * seed for the prior call to /blinding-prepare
+ * For CS denominations, the seed for the prior /blinding-prepare call.
*/
struct TALER_BlindingMasterSeedP blinding_seed;
/**
- * Fee that was charged for the withdrawal.
+ * Fee charged for the withdrawal.
*/
struct TALER_Amount fee;
/**
- * Number of coins withdrawn
+ * Number of coins withdrawn.
*/
uint16_t num_coins;
@@ -180,20 +178,18 @@ struct TALER_EXCHANGE_ReserveHistoryEntry
*/
struct
{
-
/**
* Public key of the coin that was paid back.
*/
struct TALER_CoinSpendPublicKeyP coin_pub;
/**
- * Signature of the coin of type
- * #TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP.
+ * Signature of type TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP.
*/
struct TALER_ExchangeSignatureP exchange_sig;
/**
- * Public key of the exchange that was used for @e exchange_sig.
+ * Public key used for @e exchange_sig.
*/
struct TALER_ExchangePublicKeyP exchange_pub;
@@ -206,12 +202,12 @@ struct TALER_EXCHANGE_ReserveHistoryEntry
/**
* Information about a close operation of the reserve.
- * @e type is #TALER_EXCHANGE_RTT_CLOSE.
+ * @e type is #TALER_EXCHANGE_RTT_CLOSING.
*/
struct
{
/**
- * Receiver account information for the outgoing wire transfer as a payto://-URI.
+ * Receiver account for the outgoing wire transfer.
*/
struct TALER_FullPayto receiver_account_details;
@@ -221,13 +217,12 @@ struct TALER_EXCHANGE_ReserveHistoryEntry
struct TALER_WireTransferIdentifierRawP wtid;
/**
- * Signature of the coin of type
- * #TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED.
+ * Signature of type TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED.
*/
struct TALER_ExchangeSignatureP exchange_sig;
/**
- * Public key of the exchange that was used for @e exchange_sig.
+ * Public key used for @e exchange_sig.
*/
struct TALER_ExchangePublicKeyP exchange_pub;
@@ -237,7 +232,7 @@ struct TALER_EXCHANGE_ReserveHistoryEntry
struct GNUNET_TIME_Timestamp timestamp;
/**
- * Fee that was charged for the closing.
+ * Fee charged for the closing.
*/
struct TALER_Amount fee;
@@ -249,7 +244,6 @@ struct TALER_EXCHANGE_ReserveHistoryEntry
*/
struct
{
-
/**
* Fee paid for the purse.
*/
@@ -276,12 +270,12 @@ struct TALER_EXCHANGE_ReserveHistoryEntry
struct TALER_ReserveSignatureP reserve_sig;
/**
- * When was the merge made.
+ * When was the merge made?
*/
struct GNUNET_TIME_Timestamp merge_timestamp;
/**
- * When was the purse set to expire.
+ * When was the purse set to expire?
*/
struct GNUNET_TIME_Timestamp purse_expiration;
@@ -296,8 +290,8 @@ struct TALER_EXCHANGE_ReserveHistoryEntry
enum TALER_WalletAccountMergeFlags flags;
/**
- * True if the purse was actually merged, false
- * if only the @e purse_fee was charged.
+ * True if the purse was actually merged, false if only the
+ * @e purse_fee was charged.
*/
bool merged;
@@ -309,84 +303,207 @@ struct TALER_EXCHANGE_ReserveHistoryEntry
*/
struct
{
-
/**
* Signature by the reserve approving the open.
*/
struct TALER_ReserveSignatureP reserve_sig;
/**
- * Amount to be paid from the reserve balance to open
- * the reserve.
+ * Amount to be paid from the reserve balance to open the reserve.
*/
struct TALER_Amount reserve_payment;
/**
- * When was the request created.
+ * When was the request created?
*/
struct GNUNET_TIME_Timestamp request_timestamp;
/**
- * For how long should the reserve be kept open.
- * (Determines amount to be paid.)
+ * For how long should the reserve be kept open?
*/
struct GNUNET_TIME_Timestamp reserve_expiration;
/**
- * How many open purses should be included with the
- * open reserve?
- * (Determines amount to be paid.)
+ * How many open purses should be included with the open reserve?
*/
uint32_t purse_limit;
} open_request;
/**
- * Information about an close request operation on the reserve.
+ * Information about a close request operation on the reserve.
* @e type is #TALER_EXCHANGE_RTT_CLOSE.
*/
struct
{
-
/**
* Signature by the reserve approving the close.
*/
struct TALER_ReserveSignatureP reserve_sig;
/**
- * When was the request created.
+ * When was the request created?
*/
struct GNUNET_TIME_Timestamp request_timestamp;
/**
- * Hash of the payto://-URI of the target account
- * for the closure, or all zeros for the reserve
- * origin account.
+ * Hash of the payto://-URI of the target account for the closure,
+ * or all zeros for the reserve origin account.
*/
struct TALER_FullPaytoHashP target_account_h_payto;
} close_request;
-
} details;
};
/**
- * @brief A /reserves/ GET Handle
+ * Possible options we can set for the GET reserves request.
*/
-struct TALER_EXCHANGE_ReservesGetHandle;
+enum TALER_EXCHANGE_GetReservesOption
+{
+ /**
+ * End of list of options.
+ */
+ TALER_EXCHANGE_GET_RESERVES_OPTION_END = 0,
+
+ /**
+ * How long to wait for a reply, enabling long polling if the reserve
+ * does not yet exist. Default is zero (no long polling).
+ */
+ TALER_EXCHANGE_GET_RESERVES_OPTION_TIMEOUT
+
+};
/**
- * @brief Reserve summary.
+ * Value for an option for the GET reserves request.
*/
-struct TALER_EXCHANGE_ReserveSummary
+struct TALER_EXCHANGE_GetReservesOptionValue
{
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_GetReservesOption option;
/**
- * High-level HTTP response details.
+ * Specific option value.
+ */
+ union
+ {
+ /**
+ * Value if @e option is TALER_EXCHANGE_GET_RESERVES_OPTION_TIMEOUT.
+ */
+ struct GNUNET_TIME_Relative timeout;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to GET /reserves/$RESERVE_PUB.
+ */
+struct TALER_EXCHANGE_GetReservesHandle;
+
+
+/**
+ * Set up GET /reserves/$RESERVE_PUB operation.
+ * Note that you must explicitly start the operation after
+ * possibly setting options.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param reserve_pub public key of the reserve to inspect
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetReservesHandle *
+TALER_EXCHANGE_get_reserves_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_ReservePublicKeyP *reserve_pub);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_GetReservesOptionValue
+ */
+#define TALER_EXCHANGE_get_reserves_option_end_() \
+ (const struct TALER_EXCHANGE_GetReservesOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_RESERVES_OPTION_END \
+ }
+
+/**
+ * Set long-polling timeout.
+ *
+ * @param t how long to wait for an answer (enables long polling)
+ * @return representation of the option as a struct TALER_EXCHANGE_GetReservesOptionValue
+ */
+#define TALER_EXCHANGE_get_reserves_option_timeout(t) \
+ (const struct TALER_EXCHANGE_GetReservesOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_GET_RESERVES_OPTION_TIMEOUT, \
+ .details.timeout = (t) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param grh the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_get_reserves_set_options_ (
+ struct TALER_EXCHANGE_GetReservesHandle *grh,
+ unsigned int num_options,
+ const struct TALER_EXCHANGE_GetReservesOptionValue *options);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * It should be used with helpers that create required options, for example:
+ *
+ * TALER_EXCHANGE_get_reserves_set_options (
+ * grh,
+ * TALER_EXCHANGE_get_reserves_option_timeout (timeout));
+ *
+ * @param grh the request to set the options for
+ * @param ... the list of options, each created by a
+ * TALER_EXCHANGE_get_reserves_option_NAME(VALUE) helper
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_get_reserves_set_options(grh,...) \
+ TALER_EXCHANGE_get_reserves_set_options_ ( \
+ grh, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_GetReservesOptionValue[]) \
+ {__VA_ARGS__, TALER_EXCHANGE_get_reserves_option_end_ () } \
+ ))
+
+
+/**
+ * @brief Reserve summary response.
+ */
+struct TALER_EXCHANGE_GetReservesResponse
+{
+ /**
+ * HTTP response data.
*/
struct TALER_EXCHANGE_HttpResponse hr;
@@ -395,25 +512,22 @@ struct TALER_EXCHANGE_ReserveSummary
*/
union
{
-
/**
- * Information returned on success, if
- * @e hr.http_status is #MHD_HTTP_OK
+ * Information returned on #MHD_HTTP_OK.
*/
struct
{
-
/**
- * Reserve balance.
+ * Current reserve balance.
*/
struct TALER_Amount balance;
/**
- * payto://-URI of the last bank account that wired funds
- * to the reserve, NULL for none (can happen if reserve
- * was funded via P2P merge).
+ * payto://-URI of the last bank account that wired funds to the reserve.
+ * NULL if the reserve was funded via P2P merge (no bank origin).
*/
struct TALER_FullPayto last_origin;
+
} ok;
} details;
@@ -421,37 +535,90 @@ struct TALER_EXCHANGE_ReserveSummary
};
+#ifndef TALER_EXCHANGE_GET_RESERVES_RESULT_CLOSURE
/**
- * Callbacks of this type are used to serve the result of submitting a
- * reserve status request to a exchange.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetReservesCallback.
+ */
+#define TALER_EXCHANGE_GET_RESERVES_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_RESERVES_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * GET /reserves/$RESERVE_PUB request.
*
* @param cls closure
- * @param rs HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetReservesCallback)(
+ TALER_EXCHANGE_GET_RESERVES_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetReservesResponse *result);
+
+
+/**
+ * Start GET /reserves/$RESERVE_PUB operation.
+ *
+ * @param[in,out] grh 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_get_reserves_start (
+ struct TALER_EXCHANGE_GetReservesHandle *grh,
+ TALER_EXCHANGE_GetReservesCallback cb,
+ TALER_EXCHANGE_GET_RESERVES_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /reserves/$RESERVE_PUB operation. This function must not be
+ * called by clients after the TALER_EXCHANGE_GetReservesCallback has been
+ * invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] grh operation to cancel
+ */
+void
+TALER_EXCHANGE_get_reserves_cancel (
+ struct TALER_EXCHANGE_GetReservesHandle *grh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetReservesResponse instead.
+ */
+struct TALER_EXCHANGE_ReserveSummary
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct TALER_Amount balance;
+ struct TALER_FullPayto last_origin;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetReservesCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ReservesGetCallback) (
void *cls,
const struct TALER_EXCHANGE_ReserveSummary *rs);
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetReservesHandle instead.
+ */
+struct TALER_EXCHANGE_ReservesGetHandle;
/**
- * Submit a request to obtain the transaction history of a reserve
- * from the exchange. Note that while we return the full response to the
- * caller for further processing, we do already verify that the
- * response is well-formed (i.e. that signatures included in the
- * response are all valid and add up to the balance). If the exchange's
- * reply is not well-formed, we return an HTTP status code of zero to
- * @a cb.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param reserve_pub public key of the reserve to inspect
- * @param timeout how long to wait for an affirmative reply
- * (enables long polling if the reserve does not yet exist)
- * @param cb the callback to call when a reply for this request is available
- * @param cb_cls closure for the above callback
- * @return a handle for this request; NULL if the inputs are invalid (i.e.
- * signatures fail to verify). In this case, the callback is not called.
+ * @deprecated Use #TALER_EXCHANGE_get_reserves_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ReservesGetHandle *
TALER_EXCHANGE_reserves_get (
@@ -462,15 +629,12 @@ TALER_EXCHANGE_reserves_get (
TALER_EXCHANGE_ReservesGetCallback cb,
void *cb_cls);
-
/**
- * Cancel a reserve GET request. This function cannot be used
- * on a request handle if a response is already served for it.
- *
- * @param rgh the reserve request handle
+ * @deprecated Use #TALER_EXCHANGE_get_reserves_cancel() instead.
*/
void
TALER_EXCHANGE_reserves_get_cancel (
struct TALER_EXCHANGE_ReservesGetHandle *rgh);
+
#endif /* _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_H */
diff --git a/src/include/taler/taler-exchange/get-reserves-attest-RESERVE_PUB.h b/src/include/taler/taler-exchange/get-reserves-attest-RESERVE_PUB.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/get-reserves-attest-RESERVE_PUB.h
@@ -23,23 +23,19 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /reserves/$RID/attest *********************** */
-
-
/**
- * @brief A Get /reserves/$RID/attest Handle
+ * Handle for an operation to GET /reserves/$RESERVE_PUB/attest.
*/
-struct TALER_EXCHANGE_ReservesGetAttestHandle;
+struct TALER_EXCHANGE_GetReservesAttestHandle;
/**
- * @brief Reserve GET attest result details.
+ * Response from a GET /reserves/$RESERVE_PUB/attest request.
*/
-struct TALER_EXCHANGE_ReserveGetAttestResult
+struct TALER_EXCHANGE_GetReservesAttestResponse
{
-
/**
- * High-level HTTP response details.
+ * HTTP response data.
*/
struct TALER_EXCHANGE_HttpResponse hr;
@@ -48,21 +44,18 @@ struct TALER_EXCHANGE_ReserveGetAttestResult
*/
union
{
-
/**
- * Information returned on success, if
- * @e hr.http_status is #MHD_HTTP_OK
+ * Information returned on #MHD_HTTP_OK.
*/
struct
{
-
/**
* Length of the @e attributes array.
*/
- unsigned int attributes_length;
+ size_t attributes_length;
/**
- * Array of attributes available about the user.
+ * NULL-terminated array of attribute names available about the user.
*/
const char **attributes;
@@ -73,29 +66,106 @@ struct TALER_EXCHANGE_ReserveGetAttestResult
};
+#ifndef TALER_EXCHANGE_GET_RESERVES_ATTEST_RESULT_CLOSURE
/**
- * Callbacks of this type are used to serve the result of submitting a
- * reserve attest request to a exchange.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetReservesAttestCallback.
+ */
+#define TALER_EXCHANGE_GET_RESERVES_ATTEST_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_RESERVES_ATTEST_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * GET /reserves/$RESERVE_PUB/attest request.
*
* @param cls closure
- * @param ror HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetReservesAttestCallback)(
+ TALER_EXCHANGE_GET_RESERVES_ATTEST_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetReservesAttestResponse *result);
+
+
+/**
+ * Set up GET /reserves/$RESERVE_PUB/attest operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param reserve_pub public key of the reserve to get available attributes for
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetReservesAttestHandle *
+TALER_EXCHANGE_get_reserves_attest_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_ReservePublicKeyP *reserve_pub);
+
+
+/**
+ * Start GET /reserves/$RESERVE_PUB/attest operation.
+ *
+ * @param[in,out] grah 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_get_reserves_attest_start (
+ struct TALER_EXCHANGE_GetReservesAttestHandle *grah,
+ TALER_EXCHANGE_GetReservesAttestCallback cb,
+ TALER_EXCHANGE_GET_RESERVES_ATTEST_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /reserves/$RESERVE_PUB/attest operation. This function must
+ * not be called by clients after the TALER_EXCHANGE_GetReservesAttestCallback
+ * has been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] grah operation to cancel
+ */
+void
+TALER_EXCHANGE_get_reserves_attest_cancel (
+ struct TALER_EXCHANGE_GetReservesAttestHandle *grah);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetReservesAttestResponse instead.
+ */
+struct TALER_EXCHANGE_ReserveGetAttestResult
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ unsigned int attributes_length;
+ const char **attributes;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetReservesAttestCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ReservesGetAttestCallback) (
void *cls,
const struct TALER_EXCHANGE_ReserveGetAttestResult *ror);
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetReservesAttestHandle instead.
+ */
+struct TALER_EXCHANGE_ReservesGetAttestHandle;
/**
- * Submit a request to get the list of attestable attributes for a reserve.
- *
- * @param ctx CURL context
- * @param url exchange base URL
- * @param reserve_pub public key of the reserve to get available attributes for
- * @param cb the callback to call when a reply for this request is available
- * @param cb_cls closure for the above callback
- * @return a handle for this request; NULL if the inputs are invalid (i.e.
- * signatures fail to verify). In this case, the callback is not called.
+ * @deprecated Use #TALER_EXCHANGE_get_reserves_attest_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ReservesGetAttestHandle *
TALER_EXCHANGE_reserves_get_attestable (
@@ -105,15 +175,12 @@ TALER_EXCHANGE_reserves_get_attestable (
TALER_EXCHANGE_ReservesGetAttestCallback cb,
void *cb_cls);
-
/**
- * Cancel a request to get attestable attributes. This function cannot be used
- * on a request handle if a response is already served for it.
- *
- * @param rgah the reserve get attestable request handle
+ * @deprecated Use #TALER_EXCHANGE_get_reserves_attest_cancel() instead.
*/
void
TALER_EXCHANGE_reserves_get_attestable_cancel (
struct TALER_EXCHANGE_ReservesGetAttestHandle *rgah);
-#endif
+
+#endif /* _TALER_EXCHANGE__GET_RESERVES_ATTEST_RESERVE_PUB_H */
diff --git a/src/include/taler/taler-exchange/get-seed.h b/src/include/taler/taler-exchange/get-seed.h
@@ -0,0 +1,135 @@
+/*
+ This file is part of TALER
+ Copyright (C) 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/taler-exchange/get-seed.h
+ * @brief C interface for GET /seed
+ * @author Christian Grothoff
+ */
+#ifndef _TALER_EXCHANGE__GET_SEED_H
+#define _TALER_EXCHANGE__GET_SEED_H
+
+#include <taler/taler-exchange/common.h>
+
+/**
+ * Handle for an operation to GET /seed.
+ */
+struct TALER_EXCHANGE_GetSeedHandle;
+
+
+/**
+ * Response from a GET /seed request.
+ * The response body is raw binary entropy, not JSON.
+ * Wallets MUST mix the returned value with locally generated entropy.
+ */
+struct TALER_EXCHANGE_GetSeedResponse
+{
+ /**
+ * HTTP response data.
+ */
+ struct TALER_EXCHANGE_HttpResponse hr;
+
+ /**
+ * Response details depending on HTTP status.
+ */
+ union
+ {
+ /**
+ * Details if HTTP status is #MHD_HTTP_OK.
+ */
+ struct
+ {
+ /**
+ * High-entropy seed data returned by the exchange.
+ * Must be mixed with locally generated entropy.
+ * Only valid while the callback is executing.
+ */
+ const void *seed;
+
+ /**
+ * Number of bytes in @e seed.
+ */
+ size_t seed_size;
+
+ } ok;
+ } details;
+
+};
+
+
+#ifndef TALER_EXCHANGE_GET_SEED_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetSeedCallback.
+ */
+#define TALER_EXCHANGE_GET_SEED_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_SEED_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * GET /seed request.
+ *
+ * @param cls closure
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetSeedCallback)(
+ TALER_EXCHANGE_GET_SEED_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetSeedResponse *result);
+
+
+/**
+ * Set up GET /seed operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetSeedHandle *
+TALER_EXCHANGE_get_seed_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url);
+
+
+/**
+ * Start GET /seed operation.
+ *
+ * @param[in,out] gsh 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_get_seed_start (
+ struct TALER_EXCHANGE_GetSeedHandle *gsh,
+ TALER_EXCHANGE_GetSeedCallback cb,
+ TALER_EXCHANGE_GET_SEED_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /seed operation. This function must not be called
+ * by clients after the TALER_EXCHANGE_GetSeedCallback has been invoked
+ * (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] gsh operation to cancel
+ */
+void
+TALER_EXCHANGE_get_seed_cancel (
+ struct TALER_EXCHANGE_GetSeedHandle *gsh);
+
+
+#endif /* _TALER_EXCHANGE__GET_SEED_H */
diff --git a/src/include/taler/taler-exchange/get-transfers-WTID.h b/src/include/taler/taler-exchange/get-transfers-WTID.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/get-transfers-WTID.h
@@ -23,12 +23,10 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /transfers/$WTID *********************** */
-
/**
- * @brief A /transfers/$WTID Handle
+ * Handle for an operation to GET /transfers/$WTID.
*/
-struct TALER_EXCHANGE_TransfersGetHandle;
+struct TALER_EXCHANGE_GetTransfersHandle;
/**
@@ -36,24 +34,23 @@ struct TALER_EXCHANGE_TransfersGetHandle;
*/
struct TALER_EXCHANGE_TransferData
{
-
/**
- * exchange key used to sign
+ * Exchange key used to sign.
*/
struct TALER_ExchangePublicKeyP exchange_pub;
/**
- * exchange signature over the transfer data
+ * Exchange signature over the transfer data.
*/
struct TALER_ExchangeSignatureP exchange_sig;
/**
- * hash of the payto:// URI the transfer went to
+ * Hash of the payto:// URI the transfer went to.
*/
struct TALER_FullPaytoHashP h_payto;
/**
- * time when the exchange claims to have performed the wire transfer
+ * Time when the exchange claims to have performed the wire transfer.
*/
struct GNUNET_TIME_Timestamp execution_time;
@@ -63,22 +60,22 @@ struct TALER_EXCHANGE_TransferData
struct TALER_Amount total_amount;
/**
- * wire fee that was charged by the exchange
+ * Wire fee that was charged by the exchange.
*/
struct TALER_Amount wire_fee;
/**
- * length of the @e details array
+ * Length of the @e details array.
*/
unsigned int details_length;
/**
- * array with details about the combined transactions
+ * Array with details about the combined transactions.
*/
const struct TALER_TrackTransferDetails *details;
/**
- * Hash over all of the @e details. For signature verification.
+ * Hash over all of the @e details, for signature verification.
*/
struct GNUNET_HashCode h_details;
@@ -86,12 +83,12 @@ struct TALER_EXCHANGE_TransferData
/**
- * Response for a GET /transfers request.
+ * Response from a GET /transfers/$WTID request.
*/
-struct TALER_EXCHANGE_TransfersGetResponse
+struct TALER_EXCHANGE_GetTransfersResponse
{
/**
- * HTTP response.
+ * HTTP response data.
*/
struct TALER_EXCHANGE_HttpResponse hr;
@@ -101,41 +98,122 @@ struct TALER_EXCHANGE_TransfersGetResponse
union
{
/**
- * Details if status code is #MHD_HTTP_OK.
+ * Details if HTTP status is #MHD_HTTP_OK.
*/
struct
{
+ /**
+ * Transfer details.
+ */
struct TALER_EXCHANGE_TransferData td;
} ok;
} details;
+
};
+#ifndef TALER_EXCHANGE_GET_TRANSFERS_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetTransfersCallback.
+ */
+#define TALER_EXCHANGE_GET_TRANSFERS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_TRANSFERS_RESULT_CLOSURE */
+
/**
- * Function called with detailed wire transfer data, including all
- * of the coin transactions that were combined into the wire transfer.
+ * Type of the function that receives the result of a
+ * GET /transfers/$WTID request.
*
* @param cls closure
- * @param tgr response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetTransfersCallback)(
+ TALER_EXCHANGE_GET_TRANSFERS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetTransfersResponse *result);
+
+
+/**
+ * Set up GET /transfers/$WTID operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param keys exchange keys for signature verification
+ * @param wtid raw wire transfer identifier to look up
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetTransfersHandle *
+TALER_EXCHANGE_get_transfers_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_WireTransferIdentifierRawP *wtid);
+
+
+/**
+ * Start GET /transfers/$WTID operation.
+ *
+ * @param[in,out] gth 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_get_transfers_start (
+ struct TALER_EXCHANGE_GetTransfersHandle *gth,
+ TALER_EXCHANGE_GetTransfersCallback cb,
+ TALER_EXCHANGE_GET_TRANSFERS_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /transfers/$WTID operation. This function must not be called
+ * by clients after the TALER_EXCHANGE_GetTransfersCallback has been invoked
+ * (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] gth operation to cancel
+ */
+void
+TALER_EXCHANGE_get_transfers_cancel (
+ struct TALER_EXCHANGE_GetTransfersHandle *gth);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetTransfersResponse instead.
+ */
+struct TALER_EXCHANGE_TransfersGetResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct TALER_EXCHANGE_TransferData td;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetTransfersCallback instead.
*/
typedef void
(*TALER_EXCHANGE_TransfersGetCallback)(
void *cls,
const struct TALER_EXCHANGE_TransfersGetResponse *tgr);
+/**
+ * @deprecated Use #TALER_EXCHANGE_GetTransfersHandle instead.
+ */
+struct TALER_EXCHANGE_TransfersGetHandle;
/**
- * Query the exchange about which transactions were combined
- * to create a wire transfer.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param wtid raw wire transfer identifier to get information about
- * @param cb callback to call
- * @param cb_cls closure for @a cb
- * @return handle to cancel operation
+ * @deprecated Use #TALER_EXCHANGE_get_transfers_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_TransfersGetHandle *
TALER_EXCHANGE_transfers_get (
@@ -146,15 +224,12 @@ TALER_EXCHANGE_transfers_get (
TALER_EXCHANGE_TransfersGetCallback cb,
void *cb_cls);
-
/**
- * Cancel wire deposits request. This function cannot be used on a request
- * handle if a response is already served for it.
- *
- * @param wdh the wire deposits request handle
+ * @deprecated Use #TALER_EXCHANGE_get_transfers_cancel() instead.
*/
void
TALER_EXCHANGE_transfers_get_cancel (
struct TALER_EXCHANGE_TransfersGetHandle *wdh);
-#endif
+
+#endif /* _TALER_EXCHANGE__GET_TRANSFERS_WTID_H */
diff --git a/src/include/taler/taler-exchange/get-wads-WAD_ID.h b/src/include/taler/taler-exchange/get-wads-WAD_ID.h
@@ -0,0 +1,218 @@
+/*
+ This file is part of TALER
+ Copyright (C) 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/taler-exchange/get-wads-WAD_ID.h
+ * @brief C interface for GET /wads/$WAD_ID
+ * @author Christian Grothoff
+ */
+#ifndef _TALER_EXCHANGE__GET_WADS_WAD_ID_H
+#define _TALER_EXCHANGE__GET_WADS_WAD_ID_H
+
+#include <taler/taler-exchange/common.h>
+
+/**
+ * Handle for an operation to GET /wads/$WAD_ID.
+ */
+struct TALER_EXCHANGE_GetWadsHandle;
+
+
+/**
+ * A single item in the wad (one purse that was merged into the wad).
+ */
+struct TALER_EXCHANGE_GetWadsWadItem
+{
+ /**
+ * Amount in the purse.
+ */
+ struct TALER_Amount amount;
+
+ /**
+ * Normalized payto URI of the account the purse is to be merged into.
+ * Must be of the form: 'payto://taler/EXCHANGE_URL/RESERVE_PUB'.
+ */
+ const char *payto_uri;
+
+ /**
+ * Purse public key.
+ */
+ struct TALER_PurseContractPublicKeyP purse_pub;
+
+ /**
+ * Hash of the contract.
+ */
+ struct TALER_PrivateContractHashP h_contract;
+
+ /**
+ * Indicative time by which the purse should expire if not paid.
+ */
+ struct GNUNET_TIME_Timestamp purse_expiration;
+
+ /**
+ * Client-side timestamp of when the merge request was made.
+ */
+ struct GNUNET_TIME_Timestamp merge_timestamp;
+
+ /**
+ * Signature created with the reserve's private key.
+ * Must be of purpose TALER_SIGNATURE_ACCOUNT_MERGE
+ * and over TALER_AccountMergeSignaturePS.
+ */
+ struct TALER_ReserveSignatureP reserve_sig;
+
+ /**
+ * Signature created with the purse's private key.
+ * Must be of purpose TALER_SIGNATURE_PURSE_MERGE
+ * and over TALER_PurseMergeSignaturePS.
+ */
+ struct TALER_PurseContractSignatureP purse_sig;
+
+ /**
+ * Deposit fees charged to the purse.
+ */
+ struct TALER_Amount deposit_fees;
+
+ /**
+ * Wad fees charged to the purse.
+ */
+ struct TALER_Amount wad_fees;
+
+};
+
+
+/**
+ * Response from a GET /wads/$WAD_ID request.
+ */
+struct TALER_EXCHANGE_GetWadsResponse
+{
+ /**
+ * HTTP response data.
+ */
+ struct TALER_EXCHANGE_HttpResponse hr;
+
+ /**
+ * Response details depending on HTTP status.
+ */
+ union
+ {
+ /**
+ * Details if HTTP status is #MHD_HTTP_OK.
+ */
+ struct
+ {
+ /**
+ * Total transfer amount claimed by the exchange.
+ */
+ struct TALER_Amount total;
+
+ /**
+ * Indicative time when the wad was handed to the bank.
+ */
+ struct GNUNET_TIME_Timestamp wad_execution_time;
+
+ /**
+ * Array of transfers (purses) aggregated in the wad.
+ */
+ const struct TALER_EXCHANGE_GetWadsWadItem *items;
+
+ /**
+ * Length of the @e items array.
+ */
+ size_t items_length;
+
+ /**
+ * Exchange signature over the wad data.
+ * Of purpose TALER_SIGNATURE_WAD_DATA, over TALER_WadDataSignaturePS.
+ */
+ struct TALER_ExchangeSignatureP exchange_sig;
+
+ /**
+ * Exchange public key used to create @e exchange_sig.
+ */
+ struct TALER_ExchangePublicKeyP exchange_pub;
+
+ } ok;
+
+ } details;
+
+};
+
+
+#ifndef TALER_EXCHANGE_GET_WADS_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_GetWadsCallback.
+ */
+#define TALER_EXCHANGE_GET_WADS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_GET_WADS_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * GET /wads/$WAD_ID request.
+ *
+ * @param cls closure
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_GetWadsCallback)(
+ TALER_EXCHANGE_GET_WADS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_GetWadsResponse *result);
+
+
+/**
+ * Set up GET /wads/$WAD_ID operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url base URL of the exchange
+ * @param wad_id identifier of the wad to look up
+ * @return handle to operation
+ */
+struct TALER_EXCHANGE_GetWadsHandle *
+TALER_EXCHANGE_get_wads_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_WireTransferIdentifierRawP *wad_id);
+
+
+/**
+ * Start GET /wads/$WAD_ID operation.
+ *
+ * @param[in,out] gwh 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_get_wads_start (
+ struct TALER_EXCHANGE_GetWadsHandle *gwh,
+ TALER_EXCHANGE_GetWadsCallback cb,
+ TALER_EXCHANGE_GET_WADS_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel GET /wads/$WAD_ID operation. This function must not be called
+ * by clients after the TALER_EXCHANGE_GetWadsCallback has been invoked
+ * (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] gwh operation to cancel
+ */
+void
+TALER_EXCHANGE_get_wads_cancel (
+ struct TALER_EXCHANGE_GetWadsHandle *gwh);
+
+
+#endif /* _TALER_EXCHANGE__GET_WADS_WAD_ID_H */
diff --git a/src/include/taler/taler-exchange/post-aml-OFFICER_PUB-decision.h b/src/include/taler/taler-exchange/post-aml-OFFICER_PUB-decision.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-aml-OFFICER_PUB-decision.h
@@ -25,36 +25,6 @@
/**
- * @brief Handle for a POST /aml/$OFFICER_PUB/decision request.
- */
-struct TALER_EXCHANGE_AddAmlDecision;
-
-
-/**
- * Response when making an AML decision.
- */
-struct TALER_EXCHANGE_AddAmlDecisionResponse
-{
- /**
- * HTTP response data.
- */
- struct TALER_EXCHANGE_HttpResponse hr;
-};
-
-
-/**
- * Function called with information about storing an an AML decision.
- *
- * @param cls closure
- * @param adr response data
- */
-typedef void
-(*TALER_EXCHANGE_AddAmlDecisionCallback) (
- void *cls,
- const struct TALER_EXCHANGE_AddAmlDecisionResponse *adr);
-
-
-/**
* Rule that applies for an account, specifies the
* trigger and measures to apply.
*/
@@ -129,34 +99,339 @@ struct TALER_EXCHANGE_AccountRule
/**
- * Inform the exchange that an AML decision has been taken.
+ * Possible options we can set for the POST /aml/$OFFICER_PUB/decision request.
+ */
+enum TALER_EXCHANGE_PostAmlDecisionOption
+{
+ /**
+ * End of list of options.
+ */
+ TALER_EXCHANGE_POST_AML_DECISION_OPTION_END = 0,
+
+ /**
+ * Full payto URI of the account the decision is about.
+ * Needed only if the exchange does not yet know the account.
+ */
+ TALER_EXCHANGE_POST_AML_DECISION_OPTION_PAYTO_URI,
+
+ /**
+ * Space-separated list of measures to trigger immediately;
+ * "+" prefixed for AND combination.
+ */
+ TALER_EXCHANGE_POST_AML_DECISION_OPTION_NEW_MEASURES,
+
+ /**
+ * JSON object with account properties to set.
+ */
+ TALER_EXCHANGE_POST_AML_DECISION_OPTION_PROPERTIES,
+
+ /**
+ * Array of event names to trigger.
+ */
+ TALER_EXCHANGE_POST_AML_DECISION_OPTION_EVENTS
+
+};
+
+
+/**
+ * Value for an option we can set for the POST /aml/$OFFICER_PUB/decision request.
+ */
+struct TALER_EXCHANGE_PostAmlDecisionOptionValue
+{
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_PostAmlDecisionOption option;
+
+ /**
+ * Specific option value.
+ */
+ union
+ {
+ /**
+ * Value if @e option is
+ * #TALER_EXCHANGE_POST_AML_DECISION_OPTION_PAYTO_URI.
+ */
+ struct TALER_FullPayto payto_uri;
+
+ /**
+ * Value if @e option is
+ * #TALER_EXCHANGE_POST_AML_DECISION_OPTION_NEW_MEASURES.
+ * May be NULL for none.
+ */
+ const char *new_measures;
+
+ /**
+ * Value if @e option is
+ * #TALER_EXCHANGE_POST_AML_DECISION_OPTION_PROPERTIES.
+ * JSON object with account properties.
+ */
+ const json_t *properties;
+
+ /**
+ * Value if @e option is
+ * #TALER_EXCHANGE_POST_AML_DECISION_OPTION_EVENTS.
+ */
+ struct
+ {
+ /**
+ * Length of the @e events array.
+ */
+ unsigned int num_events;
+
+ /**
+ * Array of event names to trigger.
+ */
+ const char **events;
+ } events;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to POST /aml/$OFFICER_PUB/decision.
+ */
+struct TALER_EXCHANGE_PostAmlDecisionHandle;
+
+#if NEW_API
+
+
+/**
+ * Set up POST /aml/$OFFICER_PUB/decision operation.
+ * Note that you must explicitly start the operation after setup.
*
* @param ctx the context
* @param url HTTP base URL for the exchange
- * @param h_payto payto URI hash of the account the
- * decision is about
- * @param payto_uri payto URI of the account, can
- * be NULL if the exchange already knows the account
+ * @param h_payto payto URI hash of the account the decision is about
* @param decision_time when was the decision made
* @param successor_measure measure to activate after @a expiration_time if no rule applied
- * @param new_measures space-separated list of measures
- * to trigger immediately;
- " "+" prefixed for AND combination;
- * NULL for none
* @param expiration_time when do the new rules expire
* @param num_rules length of the @a rules array
* @param rules new rules for the account
* @param num_measures length of the @a measures array
* @param measures possible custom measures
- * @param properties properties for the account
* @param keep_investigating true to keep the investigation open
* @param justification human-readable justification
* @param officer_priv private key of the deciding AML officer
- * @param num_events length of the @a events array
- * @param events array of events to trigger
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostAmlDecisionHandle *
+TALER_EXCHANGE_post_aml_decision_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_NormalizedPaytoHashP *h_payto,
+ struct GNUNET_TIME_Timestamp decision_time,
+ const char *successor_measure,
+ struct GNUNET_TIME_Timestamp expiration_time,
+ unsigned int num_rules,
+ const struct TALER_EXCHANGE_AccountRule rules[static num_rules],
+ unsigned int num_measures,
+ const struct TALER_EXCHANGE_MeasureInformation measures[static num_measures],
+ bool keep_investigating,
+ const char *justification,
+ const struct TALER_AmlOfficerPrivateKeyP *officer_priv);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_PostAmlDecisionOptionValue
+ */
+#define TALER_EXCHANGE_post_aml_decision_option_end_() \
+ (const struct TALER_EXCHANGE_PostAmlDecisionOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_AML_DECISION_OPTION_END \
+ }
+
+/**
+ * Set the payto URI of the account (needed if exchange does not yet know it).
+ *
+ * @param p the full payto URI
+ * @return representation of the option as a struct TALER_EXCHANGE_PostAmlDecisionOptionValue
+ */
+#define TALER_EXCHANGE_post_aml_decision_option_payto_uri(p) \
+ (const struct TALER_EXCHANGE_PostAmlDecisionOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_AML_DECISION_OPTION_PAYTO_URI, \
+ .details.payto_uri = (p) \
+ }
+
+/**
+ * Set the new measures to trigger immediately.
+ *
+ * @param m space-separated list of measures, "+" prefixed for AND combination,
+ * or NULL for none
+ * @return representation of the option as a struct TALER_EXCHANGE_PostAmlDecisionOptionValue
+ */
+#define TALER_EXCHANGE_post_aml_decision_option_new_measures(m) \
+ (const struct TALER_EXCHANGE_PostAmlDecisionOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_AML_DECISION_OPTION_NEW_MEASURES, \
+ .details.new_measures = (m) \
+ }
+
+/**
+ * Set the account properties.
+ *
+ * @param p JSON object with account properties
+ * @return representation of the option as a struct TALER_EXCHANGE_PostAmlDecisionOptionValue
+ */
+#define TALER_EXCHANGE_post_aml_decision_option_properties(p) \
+ (const struct TALER_EXCHANGE_PostAmlDecisionOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_AML_DECISION_OPTION_PROPERTIES, \
+ .details.properties = (p) \
+ }
+
+/**
+ * Set the events to trigger.
+ *
+ * @param n number of events
+ * @param e array of event name strings
+ * @return representation of the option as a struct TALER_EXCHANGE_PostAmlDecisionOptionValue
+ */
+#define TALER_EXCHANGE_post_aml_decision_option_events(n,e) \
+ (const struct TALER_EXCHANGE_PostAmlDecisionOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_AML_DECISION_OPTION_EVENTS, \
+ .details.events.num_events = (n), \
+ .details.events.events = (e) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param padh the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_post_aml_decision_set_options_ (
+ struct TALER_EXCHANGE_PostAmlDecisionHandle *padh,
+ unsigned int num_options,
+ struct TALER_EXCHANGE_PostAmlDecisionOptionValue options[
+ static num_options]);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param padh the request to set the options for
+ * @param ... the list of the options, each option must be created
+ * by helpers TALER_EXCHANGE_post_aml_decision_option_NAME(VALUE)
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_post_aml_decision_set_options(padh,...) \
+ TALER_EXCHANGE_post_aml_decision_set_options_ ( \
+ padh, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_PostAmlDecisionOptionValue[]) \
+ {__VA_ARGS__, \
+ TALER_EXCHANGE_post_aml_decision_option_end_ ()} \
+ ))
+
+
+/**
+ * Response when making an AML decision.
+ */
+struct TALER_EXCHANGE_PostAmlDecisionResponse
+{
+ /**
+ * HTTP response data.
+ */
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+
+#ifndef TALER_EXCHANGE_POST_AML_DECISION_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostAmlDecisionCallback.
+ */
+#define TALER_EXCHANGE_POST_AML_DECISION_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_AML_DECISION_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /aml/$OFFICER_PUB/decision request.
+ *
+ * @param cls closure
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostAmlDecisionCallback)(
+ TALER_EXCHANGE_POST_AML_DECISION_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostAmlDecisionResponse *result);
+
+
+/**
+ * Start POST /aml/$OFFICER_PUB/decision operation.
+ *
+ * @param[in,out] padh operation to start
* @param cb function to call with the exchange's result
* @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @return status code, #TALER_EC_NONE on success
+ */
+enum TALER_ErrorCode
+TALER_EXCHANGE_post_aml_decision_start (
+ struct TALER_EXCHANGE_PostAmlDecisionHandle *padh,
+ TALER_EXCHANGE_PostAmlDecisionCallback cb,
+ TALER_EXCHANGE_POST_AML_DECISION_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /aml/$OFFICER_PUB/decision operation. This function must not
+ * be called by clients after the TALER_EXCHANGE_PostAmlDecisionCallback has
+ * been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] padh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_aml_decision_cancel (
+ struct TALER_EXCHANGE_PostAmlDecisionHandle *padh);
+
+#endif
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated
+ */
+struct TALER_EXCHANGE_AddAmlDecision;
+
+
+/**
+ * @deprecated
+ */
+struct TALER_EXCHANGE_AddAmlDecisionResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated
+ */
+typedef void
+(*TALER_EXCHANGE_AddAmlDecisionCallback) (
+ void *cls,
+ const struct TALER_EXCHANGE_AddAmlDecisionResponse *adr);
+
+/**
+ * @deprecated
*/
struct TALER_EXCHANGE_AddAmlDecision *
TALER_EXCHANGE_post_aml_decision (
@@ -181,14 +456,17 @@ TALER_EXCHANGE_post_aml_decision (
TALER_EXCHANGE_AddAmlDecisionCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_post_aml_decision() operation.
+ * Cancel POST /aml/$OFFICER_PUB/decision operation. This function must not
+ * be called by clients after the TALER_EXCHANGE_PostAmlDecisionCallback has
+ * been invoked (as in those cases it'll be called internally by the
+ * implementation already).
*
- * @param rh handle of the operation to cancel
+ * @param[in] padh operation to cancel
*/
void
TALER_EXCHANGE_post_aml_decision_cancel (
- struct TALER_EXCHANGE_AddAmlDecision *rh);
+ struct TALER_EXCHANGE_AddAmlDecision *padh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_AML_OFFICER_PUB_DECISION_H */
diff --git a/src/include/taler/taler-exchange/post-auditors-AUDITOR_PUB-H_DENOM_PUB.h b/src/include/taler/taler-exchange/post-auditors-AUDITOR_PUB-H_DENOM_PUB.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-auditors-AUDITOR_PUB-H_DENOM_PUB.h
@@ -24,9 +24,36 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST /auditors/$AUDITOR_PUB/$H_DENOM_PUB.
+ */
+struct TALER_EXCHANGE_PostAuditorsHandle;
+
+
+/**
+ * Set up POST /auditors/$AUDITOR_PUB/$H_DENOM_PUB operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url HTTP base URL for the exchange
+ * @param h_denom_pub hash of the public key of the denomination
+ * @param auditor_pub public key of the auditor
+ * @param auditor_sig signature of the auditor, of
+ * purpose #TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostAuditorsHandle *
+TALER_EXCHANGE_post_auditors_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_DenominationHashP *h_denom_pub,
+ const struct TALER_AuditorPublicKeyP *auditor_pub,
+ const struct TALER_AuditorSignatureP *auditor_sig);
+
+
+/**
* Response when adding denomination signature by auditor.
*/
-struct TALER_EXCHANGE_AuditorAddDenominationResponse
+struct TALER_EXCHANGE_PostAuditorsResponse
{
/**
* HTTP response data.
@@ -35,37 +62,82 @@ struct TALER_EXCHANGE_AuditorAddDenominationResponse
};
+#ifndef TALER_EXCHANGE_POST_AUDITORS_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostAuditorsCallback.
+ */
+#define TALER_EXCHANGE_POST_AUDITORS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_AUDITORS_RESULT_CLOSURE */
+
/**
- * Function called with information about the POST
- * /auditor/$AUDITOR_PUB/$H_DENOM_PUB operation result.
+ * Type of the function that receives the result of a
+ * POST /auditors/$AUDITOR_PUB/$H_DENOM_PUB request.
*
* @param cls closure
- * @param adr HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostAuditorsCallback)(
+ TALER_EXCHANGE_POST_AUDITORS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostAuditorsResponse *result);
+
+
+/**
+ * Start POST /auditors/$AUDITOR_PUB/$H_DENOM_PUB operation.
+ *
+ * @param[in,out] pah 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_auditors_start (
+ struct TALER_EXCHANGE_PostAuditorsHandle *pah,
+ TALER_EXCHANGE_PostAuditorsCallback cb,
+ TALER_EXCHANGE_POST_AUDITORS_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /auditors/$AUDITOR_PUB/$H_DENOM_PUB operation. This function
+ * must not be called by clients after the
+ * TALER_EXCHANGE_PostAuditorsCallback has been invoked (as in those cases
+ * it'll be called internally by the implementation already).
+ *
+ * @param[in] pah operation to cancel
+ */
+void
+TALER_EXCHANGE_post_auditors_cancel (
+ struct TALER_EXCHANGE_PostAuditorsHandle *pah);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostAuditorsResponse instead.
+ */
+struct TALER_EXCHANGE_AuditorAddDenominationResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostAuditorsCallback instead.
*/
typedef void
(*TALER_EXCHANGE_AuditorAddDenominationCallback) (
void *cls,
const struct TALER_EXCHANGE_AuditorAddDenominationResponse *adr);
-
/**
- * @brief Handle for a POST /auditor/$AUDITOR_PUB/$H_DENOM_PUB request.
+ * @deprecated Use #TALER_EXCHANGE_PostAuditorsHandle instead.
*/
struct TALER_EXCHANGE_AuditorAddDenominationHandle;
-
/**
- * Provide auditor signatures for a denomination to the exchange.
- *
- * @param ctx the context
- * @param url HTTP base URL for the exchange
- * @param h_denom_pub hash of the public key of the denomination
- * @param auditor_pub public key of the auditor
- * @param auditor_sig signature of the auditor, of
- * purpose #TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_auditors_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_AuditorAddDenominationHandle *
TALER_EXCHANGE_add_auditor_denomination (
@@ -77,14 +149,12 @@ TALER_EXCHANGE_add_auditor_denomination (
TALER_EXCHANGE_AuditorAddDenominationCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_add_auditor_denomination() operation.
- *
- * @param ah handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_auditors_cancel() instead.
*/
void
TALER_EXCHANGE_add_auditor_denomination_cancel (
struct TALER_EXCHANGE_AuditorAddDenominationHandle *ah);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_AUDITORS_AUDITOR_PUB_H_DENOM_PUB_H */
diff --git a/src/include/taler/taler-exchange/post-batch-deposit.h b/src/include/taler/taler-exchange/post-batch-deposit.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-batch-deposit.h
@@ -23,15 +23,11 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /coins/$COIN_PUB/deposit *********************** */
-
-
/**
* Information needed for a coin to be deposited.
*/
struct TALER_EXCHANGE_CoinDepositDetail
{
-
/**
* The amount to be deposited.
*/
@@ -43,18 +39,18 @@ struct TALER_EXCHANGE_CoinDepositDetail
struct TALER_AgeCommitmentHashP h_age_commitment;
/**
- * The coin’s public key.
+ * The coin's public key.
*/
struct TALER_CoinSpendPublicKeyP coin_pub;
/**
* The signature made with purpose #TALER_SIGNATURE_WALLET_COIN_DEPOSIT made
- * by the customer with the coin’s private key.
+ * by the customer with the coin's private key.
*/
struct TALER_CoinSpendSignatureP coin_sig;
/**
- * Exchange’s unblinded signature of the coin.
+ * Exchange's unblinded signature of the coin.
*/
struct TALER_DenominationSignature denom_sig;
@@ -71,7 +67,6 @@ struct TALER_EXCHANGE_CoinDepositDetail
*/
struct TALER_EXCHANGE_DepositContractDetail
{
-
/**
* Hash of the contact of the merchant with the customer (further details
* are never disclosed to the exchange)
@@ -123,7 +118,7 @@ struct TALER_EXCHANGE_DepositContractDetail
struct GNUNET_TIME_Timestamp wallet_timestamp;
/**
- * The merchant’s account details, in the payto://-format supported by the
+ * The merchant's account details, in the payto://-format supported by the
* exchange.
*/
struct TALER_FullPayto merchant_payto_uri;
@@ -137,16 +132,54 @@ struct TALER_EXCHANGE_DepositContractDetail
/**
- * @brief A Batch Deposit Handle
+ * Handle for an operation to POST /batch-deposit.
*/
-struct TALER_EXCHANGE_BatchDepositHandle;
+struct TALER_EXCHANGE_PostBatchDepositHandle;
/**
- * Structure with information about a batch deposit
- * operation's result.
+ * Set up POST /batch-deposit operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * This API is typically used by a merchant.
+ *
+ * @param ctx curl context
+ * @param url exchange base URL
+ * @param keys exchange keys
+ * @param dcd details about the contract the deposit is for
+ * @param num_cdds length of the @a cdds array
+ * @param cdds array with details about the coins to be deposited
+ * @param[out] ec if NULL is returned, set to the error code explaining why
+ * the operation failed
+ * @return handle to operation, NULL if inputs are invalid (in this case
+ * @a ec is set to the error code)
*/
-struct TALER_EXCHANGE_BatchDepositResult
+struct TALER_EXCHANGE_PostBatchDepositHandle *
+TALER_EXCHANGE_post_batch_deposit_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_EXCHANGE_DepositContractDetail *dcd,
+ unsigned int num_cdds,
+ const struct TALER_EXCHANGE_CoinDepositDetail cdds[static num_cdds],
+ enum TALER_ErrorCode *ec);
+
+
+/**
+ * Change the chance that our deposit confirmation will be given to the
+ * auditor to 100%.
+ *
+ * @param[in,out] pbdh the batch deposit handle
+ */
+void
+TALER_EXCHANGE_post_batch_deposit_force_dc (
+ struct TALER_EXCHANGE_PostBatchDepositHandle *pbdh);
+
+
+/**
+ * Structure with information about a POST /batch-deposit operation's result.
+ */
+struct TALER_EXCHANGE_PostBatchDepositResponse
{
/**
* HTTP response data
@@ -155,10 +188,8 @@ struct TALER_EXCHANGE_BatchDepositResult
union
{
-
/**
- * Information returned if the HTTP status is
- * #MHD_HTTP_OK.
+ * Information returned if the HTTP status is #MHD_HTTP_OK.
*/
struct
{
@@ -186,8 +217,7 @@ struct TALER_EXCHANGE_BatchDepositResult
} ok;
/**
- * Information returned if the HTTP status is
- * #MHD_HTTP_CONFLICT.
+ * Information returned if the HTTP status is #MHD_HTTP_CONFLICT.
*/
struct
{
@@ -233,44 +263,105 @@ struct TALER_EXCHANGE_BatchDepositResult
};
+#ifndef TALER_EXCHANGE_POST_BATCH_DEPOSIT_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostBatchDepositCallback.
+ */
+#define TALER_EXCHANGE_POST_BATCH_DEPOSIT_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_BATCH_DEPOSIT_RESULT_CLOSURE */
+
/**
- * Callbacks of this type are used to serve the result of submitting a
- * deposit permission request to a exchange.
+ * Type of the function that receives the result of a
+ * POST /batch-deposit request.
*
* @param cls closure
- * @param dr deposit response details
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostBatchDepositCallback)(
+ TALER_EXCHANGE_POST_BATCH_DEPOSIT_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostBatchDepositResponse *result);
+
+
+/**
+ * Start POST /batch-deposit operation.
+ *
+ * @param[in,out] pbdh 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_batch_deposit_start (
+ struct TALER_EXCHANGE_PostBatchDepositHandle *pbdh,
+ TALER_EXCHANGE_PostBatchDepositCallback cb,
+ TALER_EXCHANGE_POST_BATCH_DEPOSIT_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /batch-deposit operation. This function must not be called by
+ * clients after the TALER_EXCHANGE_PostBatchDepositCallback has been invoked
+ * (as in those cases it'll be called internally by the implementation
+ * already).
+ *
+ * @param[in] pbdh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_batch_deposit_cancel (
+ struct TALER_EXCHANGE_PostBatchDepositHandle *pbdh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostBatchDepositResponse instead.
+ */
+struct TALER_EXCHANGE_BatchDepositResult
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct GNUNET_TIME_Timestamp deposit_timestamp;
+ const struct TALER_ExchangeSignatureP *exchange_sig;
+ const struct TALER_ExchangePublicKeyP *exchange_pub;
+ const char *transaction_base_url;
+ } ok;
+ struct
+ {
+ union
+ {
+ struct { struct TALER_CoinSpendPublicKeyP coin_pub; } insufficient_funds
+ ;
+ struct { struct TALER_CoinSpendPublicKeyP coin_pub; }
+ coin_conflicting_age_hash;
+ struct { struct TALER_CoinSpendPublicKeyP coin_pub; }
+ coin_conflicting_denomination_key;
+ } details;
+ } conflict;
+ struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostBatchDepositCallback instead.
*/
typedef void
(*TALER_EXCHANGE_BatchDepositResultCallback) (
void *cls,
const struct TALER_EXCHANGE_BatchDepositResult *dr);
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostBatchDepositHandle instead.
+ */
+struct TALER_EXCHANGE_BatchDepositHandle;
/**
- * Submit a batch of deposit permissions to the exchange and get the
- * exchange's response. This API is typically used by a merchant. Note that
- * while we return the response verbatim to the caller for further processing,
- * we do already verify that the response is well-formed (i.e. that signatures
- * included in the response are all valid). If the exchange's reply is not
- * well-formed, we return an HTTP status code of zero to @a cb.
- *
- * We also verify that the @a cdds.coin_sig are valid for this deposit
- * request, and that the @a cdds.ub_sig are a valid signatures for @a
- * coin_pub. Also, the @a exchange must be ready to operate (i.e. have
- * finished processing the /keys reply). If either check fails, we do
- * NOT initiate the transaction with the exchange and instead return NULL.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param dcd details about the contract the deposit is for
- * @param num_cdds length of the @a cdds array
- * @param cdds array with details about the coins to be deposited
- * @param cb the callback to call when a reply for this request is available
- * @param cb_cls closure for the above callback
- * @param[out] ec if NULL is returned, set to the error code explaining why the operation failed
- * @return a handle for this request; NULL if the inputs are invalid (i.e.
- * signatures fail to verify). In this case, the callback is not called.
+ * @deprecated Use #TALER_EXCHANGE_post_batch_deposit_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_BatchDepositHandle *
TALER_EXCHANGE_batch_deposit (
@@ -284,26 +375,19 @@ TALER_EXCHANGE_batch_deposit (
void *cb_cls,
enum TALER_ErrorCode *ec);
-
/**
- * Change the chance that our deposit confirmation will be given to the
- * auditor to 100%.
- *
- * @param[in,out] deposit the batch deposit permission request handle
+ * @deprecated Use #TALER_EXCHANGE_post_batch_deposit_force_dc() instead.
*/
void
TALER_EXCHANGE_batch_deposit_force_dc (
struct TALER_EXCHANGE_BatchDepositHandle *deposit);
-
/**
- * Cancel a batch deposit permission request. This function cannot be used
- * on a request handle if a response is already served for it.
- *
- * @param[in] deposit the deposit permission request handle
+ * @deprecated Use #TALER_EXCHANGE_post_batch_deposit_cancel() instead.
*/
void
TALER_EXCHANGE_batch_deposit_cancel (
struct TALER_EXCHANGE_BatchDepositHandle *deposit);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_BATCH_DEPOSIT_H */
diff --git a/src/include/taler/taler-exchange/post-blinding-prepare.h b/src/include/taler/taler-exchange/post-blinding-prepare.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-blinding-prepare.h
@@ -23,24 +23,91 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /blinding-prepare *************** */
+/**
+ * Handle for an operation to POST /blinding-prepare.
+ */
+struct TALER_EXCHANGE_PostBlindingPrepareHandle;
+
/**
- * @brief Input for the a /blinding-prepare request
+ * Set up POST /blinding-prepare operation.
+ * Note that you must explicitly start the operation after setup.
*
- * It consists of a number of nonces needed for Clause-Schnorr signatures
- * and the corresponding denomination public keys.
+ * 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]);
+
/**
- * @brief A handle to a /blinding-prepare request
+ * 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
*/
-struct TALER_EXCHANGE_BlindingPrepareHandle;
+#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))
/**
- * Response from the exchange for a /blinding-prepare request
+ * 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
*/
-struct TALER_EXCHANGE_BlindingPrepareResponse
+#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
@@ -77,11 +144,77 @@ struct TALER_EXCHANGE_BlindingPrepareResponse
};
+#ifndef TALER_EXCHANGE_POST_BLINDING_PREPARE_RESULT_CLOSURE
/**
- * @brief Callback for the response to a /blinding-prepare request
+ * 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 provided earlier
- * @param bpr the response
+ * @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);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostBlindingPrepareResponse instead.
+ */
+struct TALER_EXCHANGE_BlindingPrepareResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ size_t num_blinding_values;
+ const struct TALER_ExchangeBlindingValues *blinding_values;
+ } ok;
+ struct { /* TODO: maybe add details for status #MHD_HTTP_GONE */ } gone;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostBlindingPrepareCallback instead.
*/
typedef void
(*TALER_EXCHANGE_BlindingPrepareCallback)(
@@ -89,22 +222,13 @@ typedef void
const struct TALER_EXCHANGE_BlindingPrepareResponse *bpr);
/**
- * Submit an blinding-prepare request to the exchange and get the exchange's
- * response.
- *
- * This API is typically used by a wallet in preparation for a withdraw
- * 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 of for melting/refresh; for withdraw otherwise
- * @param num Number of elements in @e nonces and @e denoms_h
- * @param nonce_keys Array of @e num denomination information and indices of the coins as they will appear in the subsequent operation
- * @param callback A callback for the result, maybe NULL
- * @param callback_cls A closure for @e res_cb, maybe NULL
- * @return a handle for this request on success; NULL if an argument was invalid. In this case, the callback will not be called.
+ * @deprecated Use #TALER_EXCHANGE_PostBlindingPrepareHandle instead.
+ */
+struct TALER_EXCHANGE_BlindingPrepareHandle;
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_post_blinding_prepare_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_BlindingPrepareHandle *
TALER_EXCHANGE_blinding_prepare (
@@ -117,24 +241,8 @@ TALER_EXCHANGE_blinding_prepare (
TALER_EXCHANGE_BlindingPrepareCallback callback,
void *callback_cls);
-
/**
- * Submit an blinding-prepare request for to the exchange,
- * in preparation of a request for /withdraw, and get the exchange's
- * response.
- *
- * This API is typically used by a wallet in preparation for a withdraw
- * 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 num Number of elements in @e nonces and @e denoms_h
- * @param nonce_keys Array of @e num denomination information and indices of the coins as they will appear in the subsequent operation
- * @param callback A callback for the result, maybe NULL
- * @param callback_cls A closure for @e res_cb, maybe NULL
- * @return a handle for this request on success; NULL if an argument was invalid. In this case, the callback will not be called.
+ * @deprecated Use #TALER_EXCHANGE_post_blinding_prepare_for_withdraw_create().
*/
#define TALER_EXCHANGE_blinding_prepare_for_withdraw( \
curl_ctx, \
@@ -154,22 +262,7 @@ TALER_EXCHANGE_blinding_prepare (
(callback_cls))
/**
- * Submit an blinding-prepare request for to the exchange,
- * in preparation of a request for /melt, and get the exchange's
- * response.
- *
- * This API is typically used by a wallet in preparation for a 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 num Number of elements in @e nonces and @e denoms_h
- * @param nonce_keys Array of @e num denomination information and indices of the coins as they will appear in the subsequent operation
- * @param callback A callback for the result, maybe NULL
- * @param callback_cls A closure for @e res_cb, maybe NULL
- * @return a handle for this request on success; NULL if an argument was invalid. In this case, the callback will not be called.
+ * @deprecated Use #TALER_EXCHANGE_post_blinding_prepare_for_melt_create().
*/
#define TALER_EXCHANGE_blinding_prepare_for_melt( \
curl_ctx, \
@@ -189,13 +282,11 @@ TALER_EXCHANGE_blinding_prepare (
(callback_cls))
/**
- * Cancel a blinding-prepare request. This function cannot be used
- * on a request handle if a response is already served for it.
- *
- * @param bph the blinding-preapre handle
+ * @deprecated Use #TALER_EXCHANGE_post_blinding_prepare_cancel() instead.
*/
void
TALER_EXCHANGE_blinding_prepare_cancel (
struct TALER_EXCHANGE_BlindingPrepareHandle *bph);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_BLINDING_PREPARE_H */
diff --git a/src/include/taler/taler-exchange/post-coins-COIN_PUB-refund.h b/src/include/taler/taler-exchange/post-coins-COIN_PUB-refund.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-coins-COIN_PUB-refund.h
@@ -23,17 +23,47 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /coins/$COIN_PUB/refund *********************** */
+/**
+ * Handle for an operation to POST /coins/$COIN_PUB/refund.
+ */
+struct TALER_EXCHANGE_PostCoinsRefundHandle;
+
/**
- * @brief A Refund Handle
+ * Set up POST /coins/$COIN_PUB/refund operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx curl context
+ * @param url exchange base URL
+ * @param keys exchange keys
+ * @param amount the amount to be refunded; must be larger than the refund fee
+ * (as that fee is still being subtracted), and smaller than the amount
+ * (with deposit fee) of the original deposit contribution of this coin
+ * @param h_contract_terms hash of the contract of the merchant with the
+ * customer that is being refunded
+ * @param coin_pub coin's public key of the coin from the original deposit
+ * @param rtransaction_id transaction id for the refund operation; needed to
+ * distinguish multiple partial refunds for the same deposit
+ * @param merchant_priv the private key of the merchant, used to generate
+ * signature for refund request
+ * @return handle to operation, NULL on error
*/
-struct TALER_EXCHANGE_RefundHandle;
+struct TALER_EXCHANGE_PostCoinsRefundHandle *
+TALER_EXCHANGE_post_coins_refund_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_Amount *amount,
+ const struct TALER_PrivateContractHashP *h_contract_terms,
+ const struct TALER_CoinSpendPublicKeyP *coin_pub,
+ uint64_t rtransaction_id,
+ const struct TALER_MerchantPrivateKeyP *merchant_priv);
+
/**
* Response from the /refund API.
*/
-struct TALER_EXCHANGE_RefundResponse
+struct TALER_EXCHANGE_PostCoinsRefundResponse
{
/**
* HTTP response data
@@ -64,12 +94,76 @@ struct TALER_EXCHANGE_RefundResponse
};
+#ifndef TALER_EXCHANGE_POST_COINS_REFUND_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostCoinsRefundCallback.
+ */
+#define TALER_EXCHANGE_POST_COINS_REFUND_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_COINS_REFUND_RESULT_CLOSURE */
+
/**
- * Callbacks of this type are used to serve the result of submitting a
- * refund request to an exchange.
+ * Type of the function that receives the result of a
+ * POST /coins/$COIN_PUB/refund request.
*
* @param cls closure
- * @param rr refund response
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostCoinsRefundCallback)(
+ TALER_EXCHANGE_POST_COINS_REFUND_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostCoinsRefundResponse *result);
+
+
+/**
+ * Start POST /coins/$COIN_PUB/refund operation.
+ *
+ * @param[in,out] pcrh 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_coins_refund_start (
+ struct TALER_EXCHANGE_PostCoinsRefundHandle *pcrh,
+ TALER_EXCHANGE_PostCoinsRefundCallback cb,
+ TALER_EXCHANGE_POST_COINS_REFUND_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /coins/$COIN_PUB/refund operation. This function must not be
+ * called by clients after the TALER_EXCHANGE_PostCoinsRefundCallback has been
+ * invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] pcrh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_coins_refund_cancel (
+ struct TALER_EXCHANGE_PostCoinsRefundHandle *pcrh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostCoinsRefundResponse instead.
+ */
+struct TALER_EXCHANGE_RefundResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct TALER_ExchangePublicKeyP exchange_pub;
+ struct TALER_ExchangeSignatureP exchange_sig;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostCoinsRefundCallback instead.
*/
typedef void
(*TALER_EXCHANGE_RefundCallback) (
@@ -77,34 +171,13 @@ typedef void
const struct TALER_EXCHANGE_RefundResponse *rr);
/**
- * Submit a refund request to the exchange and get the exchange's response.
- * This API is used by a merchant. Note that while we return the response
- * verbatim to the caller for further processing, we do already verify that
- * the response is well-formed (i.e. that signatures included in the response
- * are all valid). If the exchange's reply is not well-formed, we return an
- * HTTP status code of zero to @a cb.
- *
- * The @a exchange must be ready to operate (i.e. have
- * finished processing the /keys reply). If this check fails, we do
- * NOT initiate the transaction with the exchange and instead return NULL.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param amount the amount to be refunded; must be larger than the refund fee
- * (as that fee is still being subtracted), and smaller than the amount
- * (with deposit fee) of the original deposit contribution of this coin
- * @param h_contract_terms hash of the contact of the merchant with the customer that is being refunded
- * @param coin_pub coin’s public key of the coin from the original deposit operation
- * @param rtransaction_id transaction id for the transaction between merchant and customer (of refunding operation);
- * this is needed as we may first do a partial refund and later a full refund. If both
- * refunds are also over the same amount, we need the @a rtransaction_id to make the disjoint
- * refund requests different (as requests are idempotent and otherwise the 2nd refund might not work).
- * @param merchant_priv the private key of the merchant, used to generate signature for refund request
- * @param cb the callback to call when a reply for this request is available
- * @param cb_cls closure for the above callback
- * @return a handle for this request; NULL if the inputs are invalid (i.e.
- * signatures fail to verify). In this case, the callback is not called.
+ * @deprecated Use #TALER_EXCHANGE_PostCoinsRefundHandle instead.
+ */
+struct TALER_EXCHANGE_RefundHandle;
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_post_coins_refund_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_RefundHandle *
TALER_EXCHANGE_refund (
@@ -119,16 +192,11 @@ TALER_EXCHANGE_refund (
TALER_EXCHANGE_RefundCallback cb,
void *cb_cls);
-
/**
- * Cancel a refund permission request. This function cannot be used
- * on a request handle if a response is already served for it. If
- * this function is called, the refund may or may not have happened.
- * However, it is fine to try to refund the coin a second time.
- *
- * @param refund the refund request handle
+ * @deprecated Use #TALER_EXCHANGE_post_coins_refund_cancel() instead.
*/
void
TALER_EXCHANGE_refund_cancel (struct TALER_EXCHANGE_RefundHandle *refund);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_COINS_COIN_PUB_REFUND_H */
diff --git a/src/include/taler/taler-exchange/post-kyc-start-ID.h b/src/include/taler/taler-exchange/post-kyc-start-ID.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-kyc-start-ID.h
@@ -24,15 +24,31 @@
#include <taler/taler-exchange/common.h>
/**
- * Handle for an operation to start the KYC process.
+ * Handle for an operation to POST /kyc-start/$ID.
*/
-struct TALER_EXCHANGE_KycStartHandle;
+struct TALER_EXCHANGE_PostKycStartHandle;
+
+
+/**
+ * Set up POST /kyc-start/$ID operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx CURL context
+ * @param url exchange base URL
+ * @param id identifier for the KYC process to start
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostKycStartHandle *
+TALER_EXCHANGE_post_kyc_start_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const char *id);
/**
* KYC start response details.
*/
-struct TALER_EXCHANGE_KycStartResponse
+struct TALER_EXCHANGE_PostKycStartResponse
{
/**
* HTTP response data
@@ -40,17 +56,15 @@ struct TALER_EXCHANGE_KycStartResponse
struct TALER_EXCHANGE_HttpResponse hr;
/**
- * Details depending on @e http_status.
+ * Details depending on @e hr.http_status.
*/
union
{
-
/**
- * @e http_status is OK.
+ * @e hr.http_status is #MHD_HTTP_OK.
*/
struct
{
-
/**
* Which URL to redirect to to begin the KYC process.
*/
@@ -62,28 +76,89 @@ struct TALER_EXCHANGE_KycStartResponse
};
+
+#ifndef TALER_EXCHANGE_POST_KYC_START_RESULT_CLOSURE
/**
- * Function called with the result of a KYC start request.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostKycStartCallback.
+ */
+#define TALER_EXCHANGE_POST_KYC_START_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_KYC_START_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /kyc-start/$ID request.
*
* @param cls closure
- * @param ksr information about the started KYC operation
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostKycStartCallback)(
+ TALER_EXCHANGE_POST_KYC_START_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostKycStartResponse *result);
+
+
+/**
+ * Start POST /kyc-start/$ID operation.
+ *
+ * @param[in,out] pksh 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_kyc_start_start (
+ struct TALER_EXCHANGE_PostKycStartHandle *pksh,
+ TALER_EXCHANGE_PostKycStartCallback cb,
+ TALER_EXCHANGE_POST_KYC_START_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /kyc-start/$ID operation. This function must not be called by
+ * clients after the TALER_EXCHANGE_PostKycStartCallback has been invoked (as
+ * in those cases it'll be called internally by the implementation already).
+ *
+ * @param[in] pksh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_kyc_start_cancel (
+ struct TALER_EXCHANGE_PostKycStartHandle *pksh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostKycStartResponse instead.
+ */
+struct TALER_EXCHANGE_KycStartResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ const char *redirect_url;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostKycStartCallback instead.
*/
typedef void
(*TALER_EXCHANGE_KycStartCallback)(
void *cls,
const struct TALER_EXCHANGE_KycStartResponse *ksr);
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostKycStartHandle instead.
+ */
+struct TALER_EXCHANGE_KycStartHandle;
/**
- * Run interaction with exchange to check KYC information for a merchant or
- * wallet account identified via a @a id.
- *
- * @param ctx CURL context
- * @param url exchange base URL
- * @param id identifier for the KYC process to start
- * @param cb function to call with the result
- * @param cb_cls closure for @a cb
- * @return NULL on error
+ * @deprecated Use #TALER_EXCHANGE_post_kyc_start_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_KycStartHandle *
TALER_EXCHANGE_kyc_start (
@@ -93,13 +168,11 @@ TALER_EXCHANGE_kyc_start (
TALER_EXCHANGE_KycStartCallback cb,
void *cb_cls);
-
/**
- * Cancel KYC start operation.
- *
- * @param[in] ksh handle for operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_kyc_start_cancel() instead.
*/
void
TALER_EXCHANGE_kyc_start_cancel (struct TALER_EXCHANGE_KycStartHandle *ksh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_KYC_START_ID_H */
diff --git a/src/include/taler/taler-exchange/post-kyc-wallet.h b/src/include/taler/taler-exchange/post-kyc-wallet.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-kyc-wallet.h
@@ -24,31 +24,46 @@
#include <taler/taler-exchange/common.h>
/**
- * Handle for a ``/kyc-wallet`` operation.
+ * Handle for an operation to POST /kyc-wallet.
*/
-struct TALER_EXCHANGE_KycWalletHandle;
+struct TALER_EXCHANGE_PostKycWalletHandle;
/**
- * KYC status response details.
+ * Set up POST /kyc-wallet operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx CURL context
+ * @param url exchange base URL
+ * @param reserve_priv wallet private key to check
+ * @param balance balance (or balance threshold) crossed by the wallet
+ * @return handle to operation, NULL on error
*/
-struct TALER_EXCHANGE_WalletKycResponse
-{
+struct TALER_EXCHANGE_PostKycWalletHandle *
+TALER_EXCHANGE_post_kyc_wallet_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_ReservePrivateKeyP *reserve_priv,
+ const struct TALER_Amount *balance);
+
+/**
+ * KYC wallet status response details.
+ */
+struct TALER_EXCHANGE_PostKycWalletResponse
+{
/**
* HTTP response data
*/
struct TALER_EXCHANGE_HttpResponse hr;
/**
- * Variants depending on @e http_status.
+ * Variants depending on @e hr.http_status.
*/
union
{
-
struct
{
-
/**
* Above which amount does the wallet need to check
* for KYC again?
@@ -73,30 +88,92 @@ struct TALER_EXCHANGE_WalletKycResponse
};
+
+#ifndef TALER_EXCHANGE_POST_KYC_WALLET_RESULT_CLOSURE
/**
- * Function called with the result for a wallet looking
- * up its KYC payment target.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostKycWalletCallback.
+ */
+#define TALER_EXCHANGE_POST_KYC_WALLET_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_KYC_WALLET_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /kyc-wallet request.
*
* @param cls closure
- * @param ks the wallets KYC payment target details
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostKycWalletCallback)(
+ TALER_EXCHANGE_POST_KYC_WALLET_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostKycWalletResponse *result);
+
+
+/**
+ * Start POST /kyc-wallet operation.
+ *
+ * @param[in,out] pkwh 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_kyc_wallet_start (
+ struct TALER_EXCHANGE_PostKycWalletHandle *pkwh,
+ TALER_EXCHANGE_PostKycWalletCallback cb,
+ TALER_EXCHANGE_POST_KYC_WALLET_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /kyc-wallet operation. This function must not be called by
+ * clients after the TALER_EXCHANGE_PostKycWalletCallback has been invoked
+ * (as in those cases it'll be called internally by the implementation
+ * already).
+ *
+ * @param[in] pkwh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_kyc_wallet_cancel (
+ struct TALER_EXCHANGE_PostKycWalletHandle *pkwh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostKycWalletResponse instead.
+ */
+struct TALER_EXCHANGE_WalletKycResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct TALER_Amount next_threshold;
+ struct GNUNET_TIME_Timestamp expiration_time;
+ } ok;
+ struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostKycWalletCallback instead.
*/
typedef void
(*TALER_EXCHANGE_KycWalletCallback)(
void *cls,
const struct TALER_EXCHANGE_WalletKycResponse *ks);
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostKycWalletHandle instead.
+ */
+struct TALER_EXCHANGE_KycWalletHandle;
/**
- * Run interaction with exchange to find out the wallet's KYC
- * identifier.
- *
- * @param ctx CURL context
- * @param url exchange base URL
- * @param reserve_priv wallet private key to check
- * @param balance balance (or balance threshold) crossed by the wallet
- * @param cb function to call with the result
- * @param cb_cls closure for @a cb
- * @return NULL on error
+ * @deprecated Use #TALER_EXCHANGE_post_kyc_wallet_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_KycWalletHandle *
TALER_EXCHANGE_kyc_wallet (
@@ -107,13 +184,11 @@ TALER_EXCHANGE_kyc_wallet (
TALER_EXCHANGE_KycWalletCallback cb,
void *cb_cls);
-
/**
- * Cancel KYC wallet operation
- *
- * @param kwh handle for operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_kyc_wallet_cancel() instead.
*/
void
TALER_EXCHANGE_kyc_wallet_cancel (struct TALER_EXCHANGE_KycWalletHandle *kwh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_KYC_WALLET_H */
diff --git a/src/include/taler/taler-exchange/post-management-aml-officers.h b/src/include/taler/taler-exchange/post-management-aml-officers.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-aml-officers.h
@@ -24,50 +24,125 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST /management/aml-officers.
+ */
+struct TALER_EXCHANGE_PostManagementAmlOfficersHandle;
+
+
+/**
+ * Set up POST /management/aml-officers operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url HTTP base URL for the exchange
+ * @param officer_pub the public signing key of the officer
+ * @param officer_name name of the officer
+ * @param change_date when to affect the status change
+ * @param is_active true to enable the officer
+ * @param read_only true to only allow read-only access
+ * @param master_sig signature affirming the change
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementAmlOfficersHandle *
+TALER_EXCHANGE_post_management_aml_officers_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_AmlOfficerPublicKeyP *officer_pub,
+ const char *officer_name,
+ struct GNUNET_TIME_Timestamp change_date,
+ bool is_active,
+ bool read_only,
+ const struct TALER_MasterSignatureP *master_sig);
+
+
+/**
* Response from a POST /management/aml-officers request.
*/
-struct TALER_EXCHANGE_ManagementUpdateAmlOfficerResponse
+struct TALER_EXCHANGE_PostManagementAmlOfficersResponse
{
/**
* HTTP response data
*/
struct TALER_EXCHANGE_HttpResponse hr;
-
};
+
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_AML_OFFICERS_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementAmlOfficersCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_AML_OFFICERS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_AML_OFFICERS_RESULT_CLOSURE */
+
/**
- * Function called with information about the change to
- * an AML officer status.
+ * Type of the function that receives the result of a
+ * POST /management/aml-officers request.
*
* @param cls closure
- * @param hr HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementAmlOfficersCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_AML_OFFICERS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostManagementAmlOfficersResponse *result);
+
+
+/**
+ * Start POST /management/aml-officers operation.
+ *
+ * @param[in,out] pmaoh 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_management_aml_officers_start (
+ struct TALER_EXCHANGE_PostManagementAmlOfficersHandle *pmaoh,
+ TALER_EXCHANGE_PostManagementAmlOfficersCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_AML_OFFICERS_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/aml-officers operation. This function must not be
+ * called by clients after the
+ * TALER_EXCHANGE_PostManagementAmlOfficersCallback has been invoked (as in
+ * those cases it'll be called internally by the implementation already).
+ *
+ * @param[in] pmaoh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_aml_officers_cancel (
+ struct TALER_EXCHANGE_PostManagementAmlOfficersHandle *pmaoh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementAmlOfficersResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementUpdateAmlOfficerResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementAmlOfficersCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ManagementUpdateAmlOfficerCallback) (
void *cls,
const struct TALER_EXCHANGE_ManagementUpdateAmlOfficerResponse *hr);
-
/**
- * @brief Handle for a POST /management/aml-officers/$OFFICER_PUB request.
+ * @deprecated Use #TALER_EXCHANGE_PostManagementAmlOfficersHandle instead.
*/
struct TALER_EXCHANGE_ManagementUpdateAmlOfficer;
-
/**
- * Inform the exchange that the status of an AML officer has changed.
- *
- * @param ctx the context
- * @param url HTTP base URL for the exchange
- * @param officer_pub the public signing key of the officer
- * @param officer_name name of the officer
- * @param change_date when to affect the status change
- * @param is_active true to enable the officer
- * @param read_only true to only allow read-only access
- * @param master_sig signature affirming the change
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_management_aml_officers_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ManagementUpdateAmlOfficer *
TALER_EXCHANGE_management_update_aml_officer (
@@ -82,14 +157,12 @@ TALER_EXCHANGE_management_update_aml_officer (
TALER_EXCHANGE_ManagementUpdateAmlOfficerCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_management_update_aml_officer() operation.
- *
- * @param rh handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_management_aml_officers_cancel() instead.
*/
void
TALER_EXCHANGE_management_update_aml_officer_cancel (
struct TALER_EXCHANGE_ManagementUpdateAmlOfficer *rh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_AML_OFFICERS_H */
diff --git a/src/include/taler/taler-exchange/post-management-auditors-AUDITOR_PUB-disable.h b/src/include/taler/taler-exchange/post-management-auditors-AUDITOR_PUB-disable.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-auditors-AUDITOR_PUB-disable.h
@@ -24,9 +24,35 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST /management/auditors/$AUDITOR_PUB/disable.
+ */
+struct TALER_EXCHANGE_PostManagementAuditorsDisableHandle;
+
+
+/**
+ * Set up POST /management/auditors/$AUDITOR_PUB/disable operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url HTTP base URL for the exchange
+ * @param auditor_pub the public signing key of the auditor
+ * @param validity_end when was this decided?
+ * @param master_sig signature affirming the auditor disablement
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementAuditorsDisableHandle *
+TALER_EXCHANGE_post_management_auditors_disable_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_AuditorPublicKeyP *auditor_pub,
+ struct GNUNET_TIME_Timestamp validity_end,
+ const struct TALER_MasterSignatureP *master_sig);
+
+
+/**
* Response when disabling an auditor.
*/
-struct TALER_EXCHANGE_ManagementAuditorDisableResponse
+struct TALER_EXCHANGE_PostManagementAuditorsDisableResponse
{
/**
* HTTP response data.
@@ -34,35 +60,83 @@ struct TALER_EXCHANGE_ManagementAuditorDisableResponse
struct TALER_EXCHANGE_HttpResponse hr;
};
+
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_AUDITORS_DISABLE_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementAuditorsDisableCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_AUDITORS_DISABLE_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_AUDITORS_DISABLE_RESULT_CLOSURE */
+
/**
- * Function called with information about the auditor disable operation result.
+ * Type of the function that receives the result of a
+ * POST /management/auditors/$AUDITOR_PUB/disable request.
*
* @param cls closure
- * @param adr HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementAuditorsDisableCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_AUDITORS_DISABLE_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostManagementAuditorsDisableResponse *result);
+
+
+/**
+ * Start POST /management/auditors/$AUDITOR_PUB/disable operation.
+ *
+ * @param[in,out] pmadh 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_management_auditors_disable_start (
+ struct TALER_EXCHANGE_PostManagementAuditorsDisableHandle *pmadh,
+ TALER_EXCHANGE_PostManagementAuditorsDisableCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_AUDITORS_DISABLE_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/auditors/$AUDITOR_PUB/disable operation. This
+ * function must not be called by clients after the
+ * TALER_EXCHANGE_PostManagementAuditorsDisableCallback has been invoked (as
+ * in those cases it'll be called internally by the implementation already).
+ *
+ * @param[in] pmadh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_auditors_disable_cancel (
+ struct TALER_EXCHANGE_PostManagementAuditorsDisableHandle *pmadh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementAuditorsDisableResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementAuditorDisableResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementAuditorsDisableCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ManagementAuditorDisableCallback) (
void *cls,
const struct TALER_EXCHANGE_ManagementAuditorDisableResponse *adr);
-
/**
- * @brief Handle for a POST /management/auditors/$AUDITOR_PUB/disable request.
+ * @deprecated Use #TALER_EXCHANGE_PostManagementAuditorsDisableHandle instead.
*/
struct TALER_EXCHANGE_ManagementAuditorDisableHandle;
-
/**
- * Inform the exchange that an auditor should be disabled.
- *
- * @param ctx the context
- * @param url HTTP base URL for the exchange
- * @param auditor_pub the public signing key of the auditor
- * @param validity_end when was this decided?
- * @param master_sig signature affirming the auditor addition
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_management_auditors_disable_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ManagementAuditorDisableHandle *
TALER_EXCHANGE_management_disable_auditor (
@@ -74,14 +148,12 @@ TALER_EXCHANGE_management_disable_auditor (
TALER_EXCHANGE_ManagementAuditorDisableCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_management_disable_auditor() operation.
- *
- * @param ah handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_management_auditors_disable_cancel() instead.
*/
void
TALER_EXCHANGE_management_disable_auditor_cancel (
struct TALER_EXCHANGE_ManagementAuditorDisableHandle *ah);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_AUDITORS_AUDITOR_PUB_DISABLE_H */
diff --git a/src/include/taler/taler-exchange/post-management-auditors.h b/src/include/taler/taler-exchange/post-management-auditors.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-auditors.h
@@ -24,9 +24,39 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST /management/auditors.
+ */
+struct TALER_EXCHANGE_PostManagementAuditorsHandle;
+
+
+/**
+ * Set up POST /management/auditors operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url HTTP base URL for the exchange
+ * @param auditor_pub the public signing key of the auditor
+ * @param auditor_url base URL of the auditor
+ * @param auditor_name human readable name for the auditor
+ * @param validity_start when was this decided?
+ * @param master_sig signature affirming the auditor addition
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementAuditorsHandle *
+TALER_EXCHANGE_post_management_auditors_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_AuditorPublicKeyP *auditor_pub,
+ const char *auditor_url,
+ const char *auditor_name,
+ struct GNUNET_TIME_Timestamp validity_start,
+ const struct TALER_MasterSignatureP *master_sig);
+
+
+/**
* Response when enabling an auditor.
*/
-struct TALER_EXCHANGE_ManagementAuditorEnableResponse
+struct TALER_EXCHANGE_PostManagementAuditorsResponse
{
/**
* HTTP response data.
@@ -34,37 +64,83 @@ struct TALER_EXCHANGE_ManagementAuditorEnableResponse
struct TALER_EXCHANGE_HttpResponse hr;
};
+
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_AUDITORS_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementAuditorsCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_AUDITORS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_AUDITORS_RESULT_CLOSURE */
+
/**
- * Function called with information about the auditor setup operation result.
+ * Type of the function that receives the result of a
+ * POST /management/auditors request.
*
* @param cls closure
- * @param r response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementAuditorsCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_AUDITORS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostManagementAuditorsResponse *result);
+
+
+/**
+ * Start POST /management/auditors operation.
+ *
+ * @param[in,out] pmah 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_management_auditors_start (
+ struct TALER_EXCHANGE_PostManagementAuditorsHandle *pmah,
+ TALER_EXCHANGE_PostManagementAuditorsCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_AUDITORS_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/auditors operation. This function must not be
+ * called by clients after the TALER_EXCHANGE_PostManagementAuditorsCallback
+ * has been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] pmah operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_auditors_cancel (
+ struct TALER_EXCHANGE_PostManagementAuditorsHandle *pmah);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementAuditorsResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementAuditorEnableResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementAuditorsCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ManagementAuditorEnableCallback) (
void *cls,
const struct TALER_EXCHANGE_ManagementAuditorEnableResponse *r);
-
/**
- * @brief Handle for a POST /management/auditors request.
+ * @deprecated Use #TALER_EXCHANGE_PostManagementAuditorsHandle instead.
*/
struct TALER_EXCHANGE_ManagementAuditorEnableHandle;
-
/**
- * Inform the exchange that an auditor should be enable or enabled.
- *
- * @param ctx the context
- * @param url HTTP base URL for the exchange
- * @param auditor_pub the public signing key of the auditor
- * @param auditor_url base URL of the auditor
- * @param auditor_name human readable name for the auditor
- * @param validity_start when was this decided?
- * @param master_sig signature affirming the auditor addition
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_management_auditors_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ManagementAuditorEnableHandle *
TALER_EXCHANGE_management_enable_auditor (
@@ -78,14 +154,12 @@ TALER_EXCHANGE_management_enable_auditor (
TALER_EXCHANGE_ManagementAuditorEnableCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_management_enable_auditor() operation.
- *
- * @param ah handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_management_auditors_cancel() instead.
*/
void
TALER_EXCHANGE_management_enable_auditor_cancel (
struct TALER_EXCHANGE_ManagementAuditorEnableHandle *ah);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_AUDITORS_H */
diff --git a/src/include/taler/taler-exchange/post-management-denominations-H_DENOM_PUB-revoke.h b/src/include/taler/taler-exchange/post-management-denominations-H_DENOM_PUB-revoke.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-denominations-H_DENOM_PUB-revoke.h
@@ -24,46 +24,121 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST
+ * /management/denominations/$H_DENOM_PUB/revoke.
+ */
+struct TALER_EXCHANGE_PostManagementDenominationsRevokeHandle;
+
+
+/**
+ * Set up POST /management/denominations/$H_DENOM_PUB/revoke operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url HTTP base URL for the exchange
+ * @param h_denom_pub hash of the denomination public key that was revoked
+ * @param master_sig signature affirming the revocation
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementDenominationsRevokeHandle *
+TALER_EXCHANGE_post_management_denominations_revoke_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_DenominationHashP *h_denom_pub,
+ const struct TALER_MasterSignatureP *master_sig);
+
+
+/**
* Response from a POST /management/denominations/$DENOM/revoke request.
*/
-struct TALER_EXCHANGE_ManagementRevokeDenominationResponse
+struct TALER_EXCHANGE_PostManagementDenominationsRevokeResponse
{
/**
* HTTP response data
*/
struct TALER_EXCHANGE_HttpResponse hr;
-
};
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_DENOMINATIONS_REVOKE_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementDenominationsRevokeCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_DENOMINATIONS_REVOKE_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_DENOMINATIONS_REVOKE_RESULT_CLOSURE */
+
/**
- * Function called with information about the post revocation operation result.
+ * Type of the function that receives the result of a
+ * POST /management/denominations/$H_DENOM_PUB/revoke request.
*
* @param cls closure
- * @param hr HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementDenominationsRevokeCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_DENOMINATIONS_REVOKE_RESULT_CLOSURE *cls,
+ const struct
+ TALER_EXCHANGE_PostManagementDenominationsRevokeResponse *result);
+
+
+/**
+ * Start POST /management/denominations/$H_DENOM_PUB/revoke operation.
+ *
+ * @param[in,out] pmdrh 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_management_denominations_revoke_start (
+ struct TALER_EXCHANGE_PostManagementDenominationsRevokeHandle *pmdrh,
+ TALER_EXCHANGE_PostManagementDenominationsRevokeCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_DENOMINATIONS_REVOKE_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/denominations/$H_DENOM_PUB/revoke operation. This
+ * function must not be called by clients after the
+ * TALER_EXCHANGE_PostManagementDenominationsRevokeCallback has been invoked
+ * (as in those cases it'll be called internally by the implementation
+ * already).
+ *
+ * @param[in] pmdrh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_denominations_revoke_cancel (
+ struct TALER_EXCHANGE_PostManagementDenominationsRevokeHandle *pmdrh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementDenominationsRevokeResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementRevokeDenominationResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementDenominationsRevokeCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ManagementRevokeDenominationKeyCallback) (
void *cls,
const struct TALER_EXCHANGE_ManagementRevokeDenominationResponse *hr);
-
/**
- * @brief Handle for a POST /management/denominations/$H_DENOM_PUB/revoke request.
+ * @deprecated Use #TALER_EXCHANGE_PostManagementDenominationsRevokeHandle instead.
*/
struct TALER_EXCHANGE_ManagementRevokeDenominationKeyHandle;
-
/**
- * Inform the exchange that a denomination key was revoked.
- *
- * @param ctx the context
- * @param url HTTP base URL for the exchange
- * @param h_denom_pub hash of the denomination public key that was revoked
- * @param master_sig signature affirming the revocation
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use
+ * #TALER_EXCHANGE_post_management_denominations_revoke_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ManagementRevokeDenominationKeyHandle *
TALER_EXCHANGE_management_revoke_denomination_key (
@@ -74,14 +149,13 @@ TALER_EXCHANGE_management_revoke_denomination_key (
TALER_EXCHANGE_ManagementRevokeDenominationKeyCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_management_revoke_denomination_key() operation.
- *
- * @param rh handle of the operation to cancel
+ * @deprecated Use
+ * #TALER_EXCHANGE_post_management_denominations_revoke_cancel() instead.
*/
void
TALER_EXCHANGE_management_revoke_denomination_key_cancel (
struct TALER_EXCHANGE_ManagementRevokeDenominationKeyHandle *rh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_DENOMINATIONS_H_DENOM_PUB_REVOKE_H */
diff --git a/src/include/taler/taler-exchange/post-management-drain.h b/src/include/taler/taler-exchange/post-management-drain.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-drain.h
@@ -24,50 +24,125 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST /management/drain.
+ */
+struct TALER_EXCHANGE_PostManagementDrainHandle;
+
+
+/**
+ * Set up POST /management/drain operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url HTTP base URL for the exchange
+ * @param wtid wire transfer identifier to use
+ * @param amount total to transfer
+ * @param date when was the request created
+ * @param account_section configuration section identifying account to debit
+ * @param payto_uri RFC 8905 URI of the account to credit
+ * @param master_sig signature affirming the operation
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementDrainHandle *
+TALER_EXCHANGE_post_management_drain_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_WireTransferIdentifierRawP *wtid,
+ const struct TALER_Amount *amount,
+ struct GNUNET_TIME_Timestamp date,
+ const char *account_section,
+ const struct TALER_FullPayto payto_uri,
+ const struct TALER_MasterSignatureP *master_sig);
+
+
+/**
* Response from a POST /management/drain request.
*/
-struct TALER_EXCHANGE_ManagementDrainResponse
+struct TALER_EXCHANGE_PostManagementDrainResponse
{
/**
* HTTP response data
*/
struct TALER_EXCHANGE_HttpResponse hr;
-
};
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_DRAIN_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementDrainCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_DRAIN_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_DRAIN_RESULT_CLOSURE */
+
/**
- * Function called with information about the drain profits result.
+ * Type of the function that receives the result of a
+ * POST /management/drain request.
*
* @param cls closure
- * @param hr HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementDrainCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_DRAIN_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostManagementDrainResponse *result);
+
+
+/**
+ * Start POST /management/drain operation.
+ *
+ * @param[in,out] pmdh 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_management_drain_start (
+ struct TALER_EXCHANGE_PostManagementDrainHandle *pmdh,
+ TALER_EXCHANGE_PostManagementDrainCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_DRAIN_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/drain operation. This function must not be
+ * called by clients after the TALER_EXCHANGE_PostManagementDrainCallback
+ * has been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] pmdh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_drain_cancel (
+ struct TALER_EXCHANGE_PostManagementDrainHandle *pmdh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementDrainResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementDrainResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementDrainCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ManagementDrainProfitsCallback) (
void *cls,
const struct TALER_EXCHANGE_ManagementDrainResponse *hr);
-
/**
- * @brief Handle for a POST /management/drain request.
+ * @deprecated Use #TALER_EXCHANGE_PostManagementDrainHandle instead.
*/
struct TALER_EXCHANGE_ManagementDrainProfitsHandle;
-
/**
- * Uploads the drain profits request.
- *
- * @param ctx the context
- * @param url HTTP base URL for the exchange
- * @param wtid wire transfer identifier to use
- * @param amount total to transfer
- * @param date when was the request created
- * @param account_section configuration section identifying account to debit
- * @param payto_uri RFC 8905 URI of the account to credit
- * @param master_sig signature affirming the operation
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_management_drain_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ManagementDrainProfitsHandle *
TALER_EXCHANGE_management_drain_profits (
@@ -82,14 +157,12 @@ TALER_EXCHANGE_management_drain_profits (
TALER_EXCHANGE_ManagementDrainProfitsCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_management_drain_profits() operation.
- *
- * @param dp handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_management_drain_cancel() instead.
*/
void
TALER_EXCHANGE_management_drain_profits_cancel (
struct TALER_EXCHANGE_ManagementDrainProfitsHandle *dp);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_DRAIN_H */
diff --git a/src/include/taler/taler-exchange/post-management-extensions.h b/src/include/taler/taler-exchange/post-management-extensions.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-extensions.h
@@ -37,23 +37,101 @@ struct TALER_EXCHANGE_ManagementPostExtensionsData
/**
+ * Handle for an operation to POST /management/extensions.
+ */
+struct TALER_EXCHANGE_PostManagementExtensionsHandle;
+
+
+/**
+ * Set up POST /management/extensions operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url HTTP base URL for the exchange
+ * @param ped extension configuration data to POST
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementExtensionsHandle *
+TALER_EXCHANGE_post_management_extensions_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_EXCHANGE_ManagementPostExtensionsData *ped);
+
+
+/**
* Response from a POST /management/extensions request.
*/
-struct TALER_EXCHANGE_ManagementPostExtensionsResponse
+struct TALER_EXCHANGE_PostManagementExtensionsResponse
{
/**
* HTTP response data
*/
struct TALER_EXCHANGE_HttpResponse hr;
-
};
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_EXTENSIONS_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementExtensionsCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_EXTENSIONS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_EXTENSIONS_RESULT_CLOSURE */
+
/**
- * Function called with information about the post extensions operation result.
+ * Type of the function that receives the result of a
+ * POST /management/extensions request.
*
* @param cls closure
- * @param hr HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementExtensionsCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_EXTENSIONS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostManagementExtensionsResponse *result);
+
+
+/**
+ * Start POST /management/extensions operation.
+ *
+ * @param[in,out] pmeh 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_management_extensions_start (
+ struct TALER_EXCHANGE_PostManagementExtensionsHandle *pmeh,
+ TALER_EXCHANGE_PostManagementExtensionsCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_EXTENSIONS_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/extensions operation. This function must not be
+ * called by clients after the
+ * TALER_EXCHANGE_PostManagementExtensionsCallback has been invoked (as in
+ * those cases it'll be called internally by the implementation already).
+ *
+ * @param[in] pmeh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_extensions_cancel (
+ struct TALER_EXCHANGE_PostManagementExtensionsHandle *pmeh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementExtensionsResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementPostExtensionsResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementExtensionsCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ManagementPostExtensionsCallback) (
@@ -61,21 +139,13 @@ typedef void
const struct TALER_EXCHANGE_ManagementPostExtensionsResponse *hr);
/**
- * @brief Handle for a POST /management/extensions request.
+ * @deprecated Use #TALER_EXCHANGE_PostManagementExtensionsHandle instead.
*/
struct TALER_EXCHANGE_ManagementPostExtensionsHandle;
-
/**
- * Uploads the configurations of enabled extensions to the exchange, signed
- * with the master key.
- *
- * @param ctx the context
- * @param url HTTP base URL for the exchange
- * @param ped signature data to POST
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_management_extensions_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ManagementPostExtensionsHandle *
TALER_EXCHANGE_management_post_extensions (
@@ -85,14 +155,12 @@ TALER_EXCHANGE_management_post_extensions (
TALER_EXCHANGE_ManagementPostExtensionsCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_management_post_extensions() operation.
- *
- * @param ph handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_management_extensions_cancel() instead.
*/
void
TALER_EXCHANGE_management_post_extensions_cancel (
struct TALER_EXCHANGE_ManagementPostExtensionsHandle *ph);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_EXTENSIONS_H */
diff --git a/src/include/taler/taler-exchange/post-management-global-fees.h b/src/include/taler/taler-exchange/post-management-global-fees.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-global-fees.h
@@ -24,9 +24,44 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST /management/global-fees.
+ */
+struct TALER_EXCHANGE_PostManagementGlobalFeesHandle;
+
+
+/**
+ * Set up POST /management/global-fees operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param exchange_base_url HTTP base URL for the exchange
+ * @param validity_start start date for the provided global fees
+ * @param validity_end end date for the provided global fees
+ * @param fees the global fees for this time period
+ * @param purse_timeout when do purses time out
+ * @param history_expiration how long are account histories preserved
+ * @param purse_account_limit how many purses are free per account
+ * @param master_sig signature affirming the global fees;
+ * of purpose #TALER_SIGNATURE_MASTER_GLOBAL_FEES
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementGlobalFeesHandle *
+TALER_EXCHANGE_post_management_global_fees_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *exchange_base_url,
+ struct GNUNET_TIME_Timestamp validity_start,
+ struct GNUNET_TIME_Timestamp validity_end,
+ const struct TALER_GlobalFeeSet *fees,
+ struct GNUNET_TIME_Relative purse_timeout,
+ struct GNUNET_TIME_Relative history_expiration,
+ uint32_t purse_account_limit,
+ const struct TALER_MasterSignatureP *master_sig);
+
+
+/**
* Response when setting global fees.
*/
-struct TALER_EXCHANGE_ManagementSetGlobalFeeResponse
+struct TALER_EXCHANGE_PostManagementGlobalFeesResponse
{
/**
* HTTP response data.
@@ -35,40 +70,82 @@ struct TALER_EXCHANGE_ManagementSetGlobalFeeResponse
};
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_GLOBAL_FEES_RESULT_CLOSURE
/**
- * Function called with information about the global fee setting operation result.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementGlobalFeesCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_GLOBAL_FEES_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_GLOBAL_FEES_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /management/global-fees request.
*
* @param cls closure
- * @param gfr HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementGlobalFeesCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_GLOBAL_FEES_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostManagementGlobalFeesResponse *result);
+
+
+/**
+ * Start POST /management/global-fees operation.
+ *
+ * @param[in,out] pmgfh 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_management_global_fees_start (
+ struct TALER_EXCHANGE_PostManagementGlobalFeesHandle *pmgfh,
+ TALER_EXCHANGE_PostManagementGlobalFeesCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_GLOBAL_FEES_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/global-fees operation. This function must not be
+ * called by clients after the
+ * TALER_EXCHANGE_PostManagementGlobalFeesCallback has been invoked (as in
+ * those cases it'll be called internally by the implementation already).
+ *
+ * @param[in] pmgfh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_global_fees_cancel (
+ struct TALER_EXCHANGE_PostManagementGlobalFeesHandle *pmgfh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementGlobalFeesResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementSetGlobalFeeResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementGlobalFeesCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ManagementSetGlobalFeeCallback) (
void *cls,
const struct TALER_EXCHANGE_ManagementSetGlobalFeeResponse *gfr);
-
/**
- * @brief Handle for a POST /management/global-fees request.
+ * @deprecated Use #TALER_EXCHANGE_PostManagementGlobalFeesHandle instead.
*/
struct TALER_EXCHANGE_ManagementSetGlobalFeeHandle;
-
/**
- * Inform the exchange about global fees.
- *
- * @param ctx the context
- * @param exchange_base_url HTTP base URL for the exchange
- * @param validity_start start date for the provided wire fees
- * @param validity_end end date for the provided wire fees
- * @param fees the wire fees for this time period
- * @param purse_timeout when do purses time out
- * @param history_expiration how long are account histories preserved
- * @param purse_account_limit how many purses are free per account
- * @param master_sig signature affirming the wire fees;
- * of purpose #TALER_SIGNATURE_MASTER_GLOBAL_FEES
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_management_global_fees_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ManagementSetGlobalFeeHandle *
TALER_EXCHANGE_management_set_global_fees (
@@ -84,14 +161,12 @@ TALER_EXCHANGE_management_set_global_fees (
TALER_EXCHANGE_ManagementSetGlobalFeeCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_management_enable_wire() operation.
- *
- * @param sgfh handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_management_global_fees_cancel() instead.
*/
void
TALER_EXCHANGE_management_set_global_fees_cancel (
struct TALER_EXCHANGE_ManagementSetGlobalFeeHandle *sgfh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_GLOBAL_FEES_H */
diff --git a/src/include/taler/taler-exchange/post-management-keys.h b/src/include/taler/taler-exchange/post-management-keys.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-keys.h
@@ -23,6 +23,7 @@
#include <taler/taler-exchange/common.h>
+
/**
* @brief Public information about a signature on an exchange's online signing key
*/
@@ -66,7 +67,6 @@ struct TALER_EXCHANGE_DenominationKeySignature
*/
struct TALER_EXCHANGE_ManagementPostKeysData
{
-
/**
* Array of the master signatures for the exchange's online signing keys.
*/
@@ -90,45 +90,118 @@ struct TALER_EXCHANGE_ManagementPostKeysData
/**
+ * Handle for an operation to POST /management/keys.
+ */
+struct TALER_EXCHANGE_PostManagementKeysHandle;
+
+
+#if NEW_API
+
+
+/**
+ * Set up POST /management/keys operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url HTTP base URL for the exchange
+ * @param pkd signature data to POST
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementKeysHandle *
+TALER_EXCHANGE_post_management_keys_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_EXCHANGE_ManagementPostKeysData *pkd);
+
+
+/**
* Response from a POST /management/keys request.
*/
-struct TALER_EXCHANGE_ManagementPostKeysResponse
+struct TALER_EXCHANGE_PostManagementKeysResponse
{
/**
* HTTP response data
*/
struct TALER_EXCHANGE_HttpResponse hr;
-
};
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_KEYS_RESULT_CLOSURE
/**
- * Function called with information about the post keys operation result.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementKeysCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_KEYS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_KEYS_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /management/keys request.
*
* @param cls closure
- * @param mr response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementKeysCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_KEYS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostManagementKeysResponse *result);
+
+
+/**
+ * Start POST /management/keys operation.
+ *
+ * @param[in,out] pmkh 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_management_keys_start (
+ struct TALER_EXCHANGE_PostManagementKeysHandle *pmkh,
+ TALER_EXCHANGE_PostManagementKeysCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_KEYS_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/keys operation. This function must not be called
+ * by clients after the TALER_EXCHANGE_PostManagementKeysCallback has been
+ * invoked (as in those cases it'll be called internally by the implementation
+ * already).
+ *
+ * @param[in] pmkh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_keys_cancel (
+ struct TALER_EXCHANGE_PostManagementKeysHandle *pmkh);
+
+#endif
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated
+ */
+struct TALER_EXCHANGE_ManagementPostKeysResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated
*/
typedef void
(*TALER_EXCHANGE_ManagementPostKeysCallback) (
void *cls,
const struct TALER_EXCHANGE_ManagementPostKeysResponse *mr);
-
/**
- * @brief Handle for a POST /management/keys request.
+ * @deprecated
*/
struct TALER_EXCHANGE_ManagementPostKeysHandle;
-
/**
- * Provide master-key signatures to the exchange.
- *
- * @param ctx the context
- * @param url HTTP base URL for the exchange
- * @param pkd signature data to POST
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated
*/
struct TALER_EXCHANGE_ManagementPostKeysHandle *
TALER_EXCHANGE_post_management_keys (
@@ -138,14 +211,12 @@ TALER_EXCHANGE_post_management_keys (
TALER_EXCHANGE_ManagementPostKeysCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_post_management_keys() operation.
- *
- * @param ph handle of the operation to cancel
+ * @deprecated
*/
void
TALER_EXCHANGE_post_management_keys_cancel (
struct TALER_EXCHANGE_ManagementPostKeysHandle *ph);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_KEYS_H */
diff --git a/src/include/taler/taler-exchange/post-management-partners.h b/src/include/taler/taler-exchange/post-management-partners.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-partners.h
@@ -24,9 +24,43 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST /management/partners.
+ */
+struct TALER_EXCHANGE_PostManagementPartnersHandle;
+
+
+/**
+ * Set up POST /management/partners operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url HTTP base URL for the exchange
+ * @param partner_pub the offline signing key of the partner
+ * @param start_date validity period start
+ * @param end_date validity period end
+ * @param wad_frequency how often will we do wad transfers to this partner
+ * @param wad_fee what is the wad fee to this partner
+ * @param partner_base_url what is the base URL of the @a partner_pub exchange
+ * @param master_sig the signature
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementPartnersHandle *
+TALER_EXCHANGE_post_management_partners_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_MasterPublicKeyP *partner_pub,
+ struct GNUNET_TIME_Timestamp start_date,
+ struct GNUNET_TIME_Timestamp end_date,
+ struct GNUNET_TIME_Relative wad_frequency,
+ const struct TALER_Amount *wad_fee,
+ const char *partner_base_url,
+ const struct TALER_MasterSignatureP *master_sig);
+
+
+/**
* Response when adding a partner exchange.
*/
-struct TALER_EXCHANGE_ManagementAddPartnerResponse
+struct TALER_EXCHANGE_PostManagementPartnersResponse
{
/**
* HTTP response data.
@@ -34,41 +68,83 @@ struct TALER_EXCHANGE_ManagementAddPartnerResponse
struct TALER_EXCHANGE_HttpResponse hr;
};
+
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_PARTNERS_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementPartnersCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_PARTNERS_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_PARTNERS_RESULT_CLOSURE */
+
/**
- * Function called with information about the change to
- * an AML officer status.
+ * Type of the function that receives the result of a
+ * POST /management/partners request.
*
* @param cls closure
- * @param apr response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementPartnersCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_PARTNERS_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostManagementPartnersResponse *result);
+
+
+/**
+ * Start POST /management/partners operation.
+ *
+ * @param[in,out] pmph 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_management_partners_start (
+ struct TALER_EXCHANGE_PostManagementPartnersHandle *pmph,
+ TALER_EXCHANGE_PostManagementPartnersCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_PARTNERS_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/partners operation. This function must not be
+ * called by clients after the TALER_EXCHANGE_PostManagementPartnersCallback
+ * has been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] pmph operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_partners_cancel (
+ struct TALER_EXCHANGE_PostManagementPartnersHandle *pmph);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementPartnersResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementAddPartnerResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementPartnersCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ManagementAddPartnerCallback) (
void *cls,
const struct TALER_EXCHANGE_ManagementAddPartnerResponse *apr);
-
/**
- * @brief Handle for a POST /management/partners/$PARTNER_PUB request.
+ * @deprecated Use #TALER_EXCHANGE_PostManagementPartnersHandle instead.
*/
struct TALER_EXCHANGE_ManagementAddPartner;
-
/**
- * Inform the exchange that the status of a partnering
- * exchange was defined.
- *
- * @param ctx the context
- * @param url HTTP base URL for the exchange
- * @param partner_pub the offline signing key of the partner
- * @param start_date validity period start
- * @param end_date validity period end
- * @param wad_frequency how often will we do wad transfers to this partner
- * @param wad_fee what is the wad fee to this partner
- * @param partner_base_url what is the base URL of the @a partner_pub exchange
- * @param master_sig the signature the signature
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_management_partners_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ManagementAddPartner *
TALER_EXCHANGE_management_add_partner (
@@ -84,14 +160,12 @@ TALER_EXCHANGE_management_add_partner (
TALER_EXCHANGE_ManagementAddPartnerCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_management_add_partner() operation.
- *
- * @param rh handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_management_partners_cancel() instead.
*/
void
TALER_EXCHANGE_management_add_partner_cancel (
struct TALER_EXCHANGE_ManagementAddPartner *rh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_PARTNERS_H */
diff --git a/src/include/taler/taler-exchange/post-management-signkeys-EXCHANGE_PUB-revoke.h b/src/include/taler/taler-exchange/post-management-signkeys-EXCHANGE_PUB-revoke.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-signkeys-EXCHANGE_PUB-revoke.h
@@ -24,45 +24,119 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST
+ * /management/signkeys/$EXCHANGE_PUB/revoke.
+ */
+struct TALER_EXCHANGE_PostManagementSignkeysRevokeHandle;
+
+
+/**
+ * Set up POST /management/signkeys/$EXCHANGE_PUB/revoke operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param url HTTP base URL for the exchange
+ * @param exchange_pub the public signing key that was revoked
+ * @param master_sig signature affirming the revocation
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementSignkeysRevokeHandle *
+TALER_EXCHANGE_post_management_signkeys_revoke_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_ExchangePublicKeyP *exchange_pub,
+ const struct TALER_MasterSignatureP *master_sig);
+
+
+/**
* Response from a POST /management/signkeys/$SK/revoke request.
*/
-struct TALER_EXCHANGE_ManagementRevokeSigningKeyResponse
+struct TALER_EXCHANGE_PostManagementSignkeysRevokeResponse
{
/**
* HTTP response data
*/
struct TALER_EXCHANGE_HttpResponse hr;
-
};
+
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_SIGNKEYS_REVOKE_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementSignkeysRevokeCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_SIGNKEYS_REVOKE_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_SIGNKEYS_REVOKE_RESULT_CLOSURE */
+
/**
- * Function called with information about the post revocation operation result.
+ * Type of the function that receives the result of a
+ * POST /management/signkeys/$EXCHANGE_PUB/revoke request.
*
* @param cls closure
- * @param hr HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementSignkeysRevokeCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_SIGNKEYS_REVOKE_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostManagementSignkeysRevokeResponse *result);
+
+
+/**
+ * Start POST /management/signkeys/$EXCHANGE_PUB/revoke operation.
+ *
+ * @param[in,out] pmsrh 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_management_signkeys_revoke_start (
+ struct TALER_EXCHANGE_PostManagementSignkeysRevokeHandle *pmsrh,
+ TALER_EXCHANGE_PostManagementSignkeysRevokeCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_SIGNKEYS_REVOKE_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/signkeys/$EXCHANGE_PUB/revoke operation. This
+ * function must not be called by clients after the
+ * TALER_EXCHANGE_PostManagementSignkeysRevokeCallback has been invoked (as in
+ * those cases it'll be called internally by the implementation already).
+ *
+ * @param[in] pmsrh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_signkeys_revoke_cancel (
+ struct TALER_EXCHANGE_PostManagementSignkeysRevokeHandle *pmsrh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementSignkeysRevokeResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementRevokeSigningKeyResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementSignkeysRevokeCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ManagementRevokeSigningKeyCallback) (
void *cls,
const struct TALER_EXCHANGE_ManagementRevokeSigningKeyResponse *hr);
-
/**
- * @brief Handle for a POST /management/signkeys/$H_DENOM_PUB/revoke request.
+ * @deprecated Use #TALER_EXCHANGE_PostManagementSignkeysRevokeHandle instead.
*/
struct TALER_EXCHANGE_ManagementRevokeSigningKeyHandle;
-
/**
- * Inform the exchange that a signing key was revoked.
- *
- * @param ctx the context
- * @param url HTTP base URL for the exchange
- * @param exchange_pub the public signing key that was revoked
- * @param master_sig signature affirming the revocation
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use
+ * #TALER_EXCHANGE_post_management_signkeys_revoke_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ManagementRevokeSigningKeyHandle *
TALER_EXCHANGE_management_revoke_signing_key (
@@ -73,14 +147,13 @@ TALER_EXCHANGE_management_revoke_signing_key (
TALER_EXCHANGE_ManagementRevokeSigningKeyCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_management_revoke_signing_key() operation.
- *
- * @param rh handle of the operation to cancel
+ * @deprecated Use
+ * #TALER_EXCHANGE_post_management_signkeys_revoke_cancel() instead.
*/
void
TALER_EXCHANGE_management_revoke_signing_key_cancel (
struct TALER_EXCHANGE_ManagementRevokeSigningKeyHandle *rh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_SIGNKEYS_EXCHANGE_PUB_REVOKE_H */
diff --git a/src/include/taler/taler-exchange/post-management-wire-disable.h b/src/include/taler/taler-exchange/post-management-wire-disable.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-wire-disable.h
@@ -24,9 +24,36 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST /management/wire/disable.
+ */
+struct TALER_EXCHANGE_PostManagementWireDisableHandle;
+
+
+/**
+ * Set up POST /management/wire/disable operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param exchange_url HTTP base URL for the exchange
+ * @param payto_uri RFC 8905 URI of the exchange's bank account
+ * @param validity_end when was this decided?
+ * @param master_sig signature affirming the wire disablement
+ * of purpose #TALER_SIGNATURE_MASTER_DEL_WIRE
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementWireDisableHandle *
+TALER_EXCHANGE_post_management_wire_disable_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *exchange_url,
+ const struct TALER_FullPayto payto_uri,
+ struct GNUNET_TIME_Timestamp validity_end,
+ const struct TALER_MasterSignatureP *master_sig);
+
+
+/**
* Response from an exchange account/disable operation.
*/
-struct TALER_EXCHANGE_ManagementWireDisableResponse
+struct TALER_EXCHANGE_PostManagementWireDisableResponse
{
/**
* HTTP response data.
@@ -34,36 +61,83 @@ struct TALER_EXCHANGE_ManagementWireDisableResponse
struct TALER_EXCHANGE_HttpResponse hr;
};
+
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_WIRE_DISABLE_RESULT_CLOSURE
/**
- * Function called with information about the wire disable operation result.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementWireDisableCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_WIRE_DISABLE_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_WIRE_DISABLE_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /management/wire/disable request.
*
* @param cls closure
- * @param wdr response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementWireDisableCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_WIRE_DISABLE_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostManagementWireDisableResponse *result);
+
+
+/**
+ * Start POST /management/wire/disable operation.
+ *
+ * @param[in,out] pmwdh 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_management_wire_disable_start (
+ struct TALER_EXCHANGE_PostManagementWireDisableHandle *pmwdh,
+ TALER_EXCHANGE_PostManagementWireDisableCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_WIRE_DISABLE_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/wire/disable operation. This function must not be
+ * called by clients after the
+ * TALER_EXCHANGE_PostManagementWireDisableCallback has been invoked (as in
+ * those cases it'll be called internally by the implementation already).
+ *
+ * @param[in] pmwdh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_wire_disable_cancel (
+ struct TALER_EXCHANGE_PostManagementWireDisableHandle *pmwdh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementWireDisableResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementWireDisableResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementWireDisableCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ManagementWireDisableCallback) (
void *cls,
const struct TALER_EXCHANGE_ManagementWireDisableResponse *wdr);
-
/**
- * @brief Handle for a POST /management/wire/disable request.
+ * @deprecated Use #TALER_EXCHANGE_PostManagementWireDisableHandle instead.
*/
struct TALER_EXCHANGE_ManagementWireDisableHandle;
-
/**
- * Inform the exchange that a wire account should be disabled.
- *
- * @param ctx the context
- * @param exchange_url HTTP base URL for the exchange
- * @param payto_uri RFC 8905 URI of the exchange's bank account
- * @param validity_end when was this decided?
- * @param master_sig signature affirming the wire addition
- * of purpose #TALER_SIGNATURE_MASTER_DEL_WIRE
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_management_wire_disable_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ManagementWireDisableHandle *
TALER_EXCHANGE_management_disable_wire (
@@ -75,14 +149,12 @@ TALER_EXCHANGE_management_disable_wire (
TALER_EXCHANGE_ManagementWireDisableCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_management_disable_wire() operation.
- *
- * @param wh handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_management_wire_disable_cancel() instead.
*/
void
TALER_EXCHANGE_management_disable_wire_cancel (
struct TALER_EXCHANGE_ManagementWireDisableHandle *wh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_WIRE_DISABLE_H */
diff --git a/src/include/taler/taler-exchange/post-management-wire-fee.h b/src/include/taler/taler-exchange/post-management-wire-fee.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-wire-fee.h
@@ -24,9 +24,40 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST /management/wire-fees.
+ */
+struct TALER_EXCHANGE_PostManagementWireFeesHandle;
+
+
+/**
+ * Set up POST /management/wire-fees operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx the context
+ * @param exchange_base_url HTTP base URL for the exchange
+ * @param wire_method for which wire method are fees provided
+ * @param validity_start start date for the provided wire fees
+ * @param validity_end end date for the provided wire fees
+ * @param fees the wire fees for this time period
+ * @param master_sig signature affirming the wire fees;
+ * of purpose #TALER_SIGNATURE_MASTER_WIRE_FEES
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementWireFeesHandle *
+TALER_EXCHANGE_post_management_wire_fees_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *exchange_base_url,
+ const char *wire_method,
+ struct GNUNET_TIME_Timestamp validity_start,
+ struct GNUNET_TIME_Timestamp validity_end,
+ const struct TALER_WireFeeSet *fees,
+ const struct TALER_MasterSignatureP *master_sig);
+
+
+/**
* Response when setting wire fees.
*/
-struct TALER_EXCHANGE_ManagementSetWireFeeResponse
+struct TALER_EXCHANGE_PostManagementWireFeesResponse
{
/**
* HTTP response data.
@@ -34,38 +65,83 @@ struct TALER_EXCHANGE_ManagementSetWireFeeResponse
struct TALER_EXCHANGE_HttpResponse hr;
};
+
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_WIRE_FEES_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementWireFeesCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_WIRE_FEES_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_WIRE_FEES_RESULT_CLOSURE */
+
/**
- * Function called with information about the wire enable operation result.
+ * Type of the function that receives the result of a
+ * POST /management/wire-fees request.
*
* @param cls closure
- * @param wfr response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementWireFeesCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_WIRE_FEES_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostManagementWireFeesResponse *result);
+
+
+/**
+ * Start POST /management/wire-fees operation.
+ *
+ * @param[in,out] pmwfh 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_management_wire_fees_start (
+ struct TALER_EXCHANGE_PostManagementWireFeesHandle *pmwfh,
+ TALER_EXCHANGE_PostManagementWireFeesCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_WIRE_FEES_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/wire-fees operation. This function must not be
+ * called by clients after the TALER_EXCHANGE_PostManagementWireFeesCallback
+ * has been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] pmwfh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_wire_fees_cancel (
+ struct TALER_EXCHANGE_PostManagementWireFeesHandle *pmwfh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementWireFeesResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementSetWireFeeResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementWireFeesCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ManagementSetWireFeeCallback) (
void *cls,
const struct TALER_EXCHANGE_ManagementSetWireFeeResponse *wfr);
-
/**
- * @brief Handle for a POST /management/wire-fees request.
+ * @deprecated Use #TALER_EXCHANGE_PostManagementWireFeesHandle instead.
*/
struct TALER_EXCHANGE_ManagementSetWireFeeHandle;
-
/**
- * Inform the exchange about future wire fees.
- *
- * @param ctx the context
- * @param exchange_base_url HTTP base URL for the exchange
- * @param wire_method for which wire method are fees provided
- * @param validity_start start date for the provided wire fees
- * @param validity_end end date for the provided wire fees
- * @param fees the wire fees for this time period
- * @param master_sig signature affirming the wire fees;
- * of purpose #TALER_SIGNATURE_MASTER_WIRE_FEES
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_management_wire_fees_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ManagementSetWireFeeHandle *
TALER_EXCHANGE_management_set_wire_fees (
@@ -79,14 +155,12 @@ TALER_EXCHANGE_management_set_wire_fees (
TALER_EXCHANGE_ManagementSetWireFeeCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_management_enable_wire() operation.
- *
- * @param swfh handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_management_wire_fees_cancel() instead.
*/
void
TALER_EXCHANGE_management_set_wire_fees_cancel (
struct TALER_EXCHANGE_ManagementSetWireFeeHandle *swfh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_WIRE_FEE_H */
diff --git a/src/include/taler/taler-exchange/post-management-wire.h b/src/include/taler/taler-exchange/post-management-wire.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-management-wire.h
@@ -23,38 +23,74 @@
#include <taler/taler-exchange/common.h>
+
/**
- * Response from an exchange account/enable operation.
+ * Possible options we can set for the POST /management/wire request.
*/
-struct TALER_EXCHANGE_ManagementWireEnableResponse
+enum TALER_EXCHANGE_PostManagementWireOption
{
/**
- * HTTP response data.
+ * End of list of options.
*/
- struct TALER_EXCHANGE_HttpResponse hr;
+ TALER_EXCHANGE_POST_MANAGEMENT_WIRE_OPTION_END = 0,
+
+ /**
+ * Label to use when showing the account to users.
+ * If not set, no label is used.
+ */
+ TALER_EXCHANGE_POST_MANAGEMENT_WIRE_OPTION_BANK_LABEL,
+
+ /**
+ * Priority for ordering the bank accounts when displaying to users.
+ * If not set, defaults to 0.
+ */
+ TALER_EXCHANGE_POST_MANAGEMENT_WIRE_OPTION_PRIORITY
+
};
/**
- * Function called with information about the wire enable operation result.
- *
- * @param cls closure
- * @param wer HTTP response data
+ * Value for an option we can set for the POST /management/wire request.
*/
-typedef void
-(*TALER_EXCHANGE_ManagementWireEnableCallback) (
- void *cls,
- const struct TALER_EXCHANGE_ManagementWireEnableResponse *wer);
+struct TALER_EXCHANGE_PostManagementWireOptionValue
+{
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_PostManagementWireOption option;
+
+ /**
+ * Specific option value.
+ */
+ union
+ {
+ /**
+ * Value if @e option is
+ * #TALER_EXCHANGE_POST_MANAGEMENT_WIRE_OPTION_BANK_LABEL.
+ * May be NULL.
+ */
+ const char *bank_label;
+
+ /**
+ * Value if @e option is
+ * #TALER_EXCHANGE_POST_MANAGEMENT_WIRE_OPTION_PRIORITY.
+ */
+ int64_t priority;
+
+ } details;
+
+};
/**
- * @brief Handle for a POST /management/wire request.
+ * Handle for an operation to POST /management/wire.
*/
-struct TALER_EXCHANGE_ManagementWireEnableHandle;
+struct TALER_EXCHANGE_PostManagementWireHandle;
/**
- * Inform the exchange that a wire account should be enabled.
+ * Set up POST /management/wire operation.
+ * Note that you must explicitly start the operation after setup.
*
* @param ctx the context
* @param url HTTP base URL for the exchange
@@ -66,12 +102,190 @@ struct TALER_EXCHANGE_ManagementWireEnableHandle;
* @param master_sig1 signature affirming the wire addition
* of purpose #TALER_SIGNATURE_MASTER_ADD_WIRE
* @param master_sig2 signature affirming the validity of the account for clients;
- * of purpose #TALER_SIGNATURE_MASTER_WIRE_DETAILS.
- * @param bank_label label to use when showing the account, can be NULL
- * @param priority priority for ordering the bank accounts
+ * of purpose #TALER_SIGNATURE_MASTER_WIRE_DETAILS
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostManagementWireHandle *
+TALER_EXCHANGE_post_management_wire_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_FullPayto payto_uri,
+ const char *conversion_url,
+ const json_t *debit_restrictions,
+ const json_t *credit_restrictions,
+ struct GNUNET_TIME_Timestamp validity_start,
+ const struct TALER_MasterSignatureP *master_sig1,
+ const struct TALER_MasterSignatureP *master_sig2);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_PostManagementWireOptionValue
+ */
+#define TALER_EXCHANGE_post_management_wire_option_end_() \
+ (const struct TALER_EXCHANGE_PostManagementWireOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_MANAGEMENT_WIRE_OPTION_END \
+ }
+
+/**
+ * Set the bank label for the wire account.
+ *
+ * @param l the label string, or NULL for no label
+ * @return representation of the option as a struct TALER_EXCHANGE_PostManagementWireOptionValue
+ */
+#define TALER_EXCHANGE_post_management_wire_option_bank_label(l) \
+ (const struct TALER_EXCHANGE_PostManagementWireOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_MANAGEMENT_WIRE_OPTION_BANK_LABEL, \
+ .details.bank_label = (l) \
+ }
+
+/**
+ * Set the priority for ordering the bank accounts.
+ *
+ * @param p priority value (higher is shown first)
+ * @return representation of the option as a struct TALER_EXCHANGE_PostManagementWireOptionValue
+ */
+#define TALER_EXCHANGE_post_management_wire_option_priority(p) \
+ (const struct TALER_EXCHANGE_PostManagementWireOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_MANAGEMENT_WIRE_OPTION_PRIORITY, \
+ .details.priority = (p) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param pmwh the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_post_management_wire_set_options_ (
+ struct TALER_EXCHANGE_PostManagementWireHandle *pmwh,
+ unsigned int num_options,
+ struct TALER_EXCHANGE_PostManagementWireOptionValue options[
+ static num_options]);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param pmwh the request to set the options for
+ * @param ... the list of the options, each option must be created
+ * by helpers TALER_EXCHANGE_post_management_wire_option_NAME(VALUE)
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_post_management_wire_set_options(pmwh,...) \
+ TALER_EXCHANGE_post_management_wire_set_options_ ( \
+ pmwh, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_PostManagementWireOptionValue[]) \
+ {__VA_ARGS__, \
+ TALER_EXCHANGE_post_management_wire_option_end_ ()} \
+ ))
+
+
+/**
+ * Response from a POST /management/wire request.
+ */
+struct TALER_EXCHANGE_PostManagementWireResponse
+{
+ /**
+ * HTTP response data.
+ */
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+
+#ifndef TALER_EXCHANGE_POST_MANAGEMENT_WIRE_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostManagementWireCallback.
+ */
+#define TALER_EXCHANGE_POST_MANAGEMENT_WIRE_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_MANAGEMENT_WIRE_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /management/wire request.
+ *
+ * @param cls closure
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostManagementWireCallback)(
+ TALER_EXCHANGE_POST_MANAGEMENT_WIRE_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostManagementWireResponse *result);
+
+
+/**
+ * Start POST /management/wire operation.
+ *
+ * @param[in,out] pmwh operation to start
* @param cb function to call with the exchange's result
* @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @return status code, #TALER_EC_NONE on success
+ */
+enum TALER_ErrorCode
+TALER_EXCHANGE_post_management_wire_start (
+ struct TALER_EXCHANGE_PostManagementWireHandle *pmwh,
+ TALER_EXCHANGE_PostManagementWireCallback cb,
+ TALER_EXCHANGE_POST_MANAGEMENT_WIRE_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /management/wire operation. This function must not be called
+ * by clients after the TALER_EXCHANGE_PostManagementWireCallback has been
+ * invoked (as in those cases it'll be called internally by the implementation
+ * already).
+ *
+ * @param[in] pmwh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_management_wire_cancel (
+ struct TALER_EXCHANGE_PostManagementWireHandle *pmwh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementWireResponse instead.
+ */
+struct TALER_EXCHANGE_ManagementWireEnableResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementWireCallback instead.
+ */
+typedef void
+(*TALER_EXCHANGE_ManagementWireEnableCallback) (
+ void *cls,
+ const struct TALER_EXCHANGE_ManagementWireEnableResponse *wer);
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostManagementWireHandle instead.
+ */
+struct TALER_EXCHANGE_ManagementWireEnableHandle;
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_post_management_wire_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ManagementWireEnableHandle *
TALER_EXCHANGE_management_enable_wire (
@@ -89,14 +303,12 @@ TALER_EXCHANGE_management_enable_wire (
TALER_EXCHANGE_ManagementWireEnableCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_management_enable_wire() operation.
- *
- * @param wh handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_management_wire_cancel() instead.
*/
void
TALER_EXCHANGE_management_enable_wire_cancel (
struct TALER_EXCHANGE_ManagementWireEnableHandle *wh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MANAGEMENT_WIRE_H */
diff --git a/src/include/taler/taler-exchange/post-melt.h b/src/include/taler/taler-exchange/post-melt.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-melt.h
@@ -23,18 +23,41 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /melt (starting with v27) **************************** */
+/**
+ * Handle for an operation to POST /melt.
+ */
+struct TALER_EXCHANGE_PostMeltHandle;
+
/**
- * @brief A /melt Handle
+ * 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_MeltHandle;
+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 /melt request.
+ * Response returned to a POST /melt request.
*/
-struct TALER_EXCHANGE_MeltResponse
+struct TALER_EXCHANGE_PostMeltResponse
{
/**
* Full HTTP response details.
@@ -84,13 +107,81 @@ struct TALER_EXCHANGE_MeltResponse
};
+#ifndef TALER_EXCHANGE_POST_MELT_RESULT_CLOSURE
/**
- * Callbacks of this type are used to notify the application about the result
- * of the /melt stage. If successful, the @a noreveal_index should be committed
+ * 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 mr response details
+ * @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);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostMeltResponse instead.
+ */
+struct TALER_EXCHANGE_MeltResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ unsigned int num_melt_blinding_values;
+ const struct TALER_ExchangeBlindingValues *melt_blinding_values;
+ const struct TALER_BlindingMasterSeedP *blinding_seed;
+ struct TALER_ExchangePublicKeyP sign_key;
+ uint32_t noreveal_index;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostMeltCallback instead.
*/
typedef void
(*TALER_EXCHANGE_MeltCallback) (
@@ -98,23 +189,13 @@ typedef void
const struct TALER_EXCHANGE_MeltResponse *mr);
/**
- * Submit a melt request to the exchange and get the exchange's
- * response.
- *
- * 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 rd 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
- * @param melt_cb the callback to call with the result
- * @param melt_cb_cls closure for @a melt_cb
- * @return a handle for this request; NULL if the argument was invalid.
- * In this case, neither callback will be called.
+ * @deprecated Use #TALER_EXCHANGE_PostMeltHandle instead.
+ */
+struct TALER_EXCHANGE_MeltHandle;
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_post_melt_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_MeltHandle *
TALER_EXCHANGE_melt (
@@ -126,14 +207,11 @@ TALER_EXCHANGE_melt (
TALER_EXCHANGE_MeltCallback melt_cb,
void *melt_cb_cls);
-
/**
- * Cancel a melt request. This function cannot be used
- * on a request handle if the callback was already invoked.
- *
- * @param mh the melt handle
+ * @deprecated Use #TALER_EXCHANGE_post_melt_cancel() instead.
*/
void
TALER_EXCHANGE_melt_cancel (struct TALER_EXCHANGE_MeltHandle *mh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_MELT_H */
diff --git a/src/include/taler/taler-exchange/post-purses-PURSE_PUB-create.h b/src/include/taler/taler-exchange/post-purses-PURSE_PUB-create.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-purses-PURSE_PUB-create.h
@@ -23,10 +23,159 @@
#include <taler/taler-exchange/common.h>
+
+/**
+ * Possible options we can set for the POST /purses/$PURSE_PUB/create request.
+ */
+enum TALER_EXCHANGE_PostPursesCreateOption
+{
+ /**
+ * End of list of options.
+ */
+ TALER_EXCHANGE_POST_PURSES_CREATE_OPTION_END = 0,
+
+ /**
+ * Upload the contract to the exchange.
+ * If not set, defaults to not uploading the contract.
+ * Must be FALSE for repeated calls to this API for the
+ * same purse (i.e. when adding more deposits).
+ */
+ TALER_EXCHANGE_POST_PURSES_CREATE_OPTION_UPLOAD_CONTRACT
+
+};
+
+
+/**
+ * Value for an option we can set for the POST /purses/$PURSE_PUB/create request.
+ */
+struct TALER_EXCHANGE_PostPursesCreateOptionValue
+{
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_PostPursesCreateOption option;
+
+ /**
+ * Specific option value.
+ */
+ union
+ {
+ /**
+ * Value if @e option is
+ * #TALER_EXCHANGE_POST_PURSES_CREATE_OPTION_UPLOAD_CONTRACT.
+ */
+ bool upload_contract;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to POST /purses/$PURSE_PUB/create.
+ */
+struct TALER_EXCHANGE_PostPursesCreateHandle;
+
+
+/**
+ * Set up POST /purses/$PURSE_PUB/create operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx curl context
+ * @param url exchange base URL
+ * @param keys exchange keys
+ * @param purse_priv private key of the purse
+ * @param merge_priv the merge credential
+ * @param contract_priv key needed to obtain and decrypt the contract
+ * @param contract_terms contract the purse is about
+ * @param num_deposits length of the @a deposits array
+ * @param deposits array of deposits to make into the purse
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostPursesCreateHandle *
+TALER_EXCHANGE_post_purses_create_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_PurseContractPrivateKeyP *purse_priv,
+ const struct TALER_PurseMergePrivateKeyP *merge_priv,
+ const struct TALER_ContractDiffiePrivateP *contract_priv,
+ const json_t *contract_terms,
+ unsigned int num_deposits,
+ const struct TALER_EXCHANGE_PurseDeposit deposits[static num_deposits]);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_PostPursesCreateOptionValue
+ */
+#define TALER_EXCHANGE_post_purses_create_option_end_() \
+ (const struct TALER_EXCHANGE_PostPursesCreateOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_PURSES_CREATE_OPTION_END \
+ }
+
+/**
+ * Set whether to upload the contract to the exchange.
+ *
+ * @param u true to upload the contract
+ * @return representation of the option as a struct TALER_EXCHANGE_PostPursesCreateOptionValue
+ */
+#define TALER_EXCHANGE_post_purses_create_option_upload_contract(u) \
+ (const struct TALER_EXCHANGE_PostPursesCreateOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_PURSES_CREATE_OPTION_UPLOAD_CONTRACT, \
+ .details.upload_contract = (u) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param ppch the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_post_purses_create_set_options_ (
+ struct TALER_EXCHANGE_PostPursesCreateHandle *ppch,
+ unsigned int num_options,
+ struct TALER_EXCHANGE_PostPursesCreateOptionValue options[
+ static num_options]);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param ppch the request to set the options for
+ * @param ... the list of the options, each option must be created
+ * by helpers TALER_EXCHANGE_post_purses_create_option_NAME(VALUE)
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_post_purses_create_set_options(ppch,...) \
+ TALER_EXCHANGE_post_purses_create_set_options_ ( \
+ ppch, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_PostPursesCreateOptionValue[]) \
+ {__VA_ARGS__, \
+ TALER_EXCHANGE_post_purses_create_option_end_ ()} \
+ ))
+
+
/**
* Response generated for a purse creation request.
*/
-struct TALER_EXCHANGE_PurseCreateDepositResponse
+struct TALER_EXCHANGE_PostPursesCreateResponse
{
/**
* Full HTTP response.
@@ -38,9 +187,8 @@ struct TALER_EXCHANGE_PurseCreateDepositResponse
*/
union
{
-
/**
- * Detailed returned on #MHD_HTTP_OK.
+ * Details returned on #MHD_HTTP_OK.
*/
struct
{
@@ -56,56 +204,97 @@ struct TALER_EXCHANGE_PurseCreateDepositResponse
*/
struct TALER_ExchangeSignatureP exchange_sig;
-
} ok;
} details;
};
+
+#ifndef TALER_EXCHANGE_POST_PURSES_CREATE_RESULT_CLOSURE
/**
- * Function called with information about the creation
- * of a new purse.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostPursesCreateCallback.
+ */
+#define TALER_EXCHANGE_POST_PURSES_CREATE_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_PURSES_CREATE_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /purses/$PURSE_PUB/create request.
*
* @param cls closure
- * @param pcr HTTP response data
+ * @param result result returned by the HTTP server
*/
typedef void
-(*TALER_EXCHANGE_PurseCreateDepositCallback) (
- void *cls,
- const struct TALER_EXCHANGE_PurseCreateDepositResponse *pcr);
+(*TALER_EXCHANGE_PostPursesCreateCallback)(
+ TALER_EXCHANGE_POST_PURSES_CREATE_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostPursesCreateResponse *result);
/**
- * @brief Handle for a POST /purses/$PID/create request.
+ * Start POST /purses/$PURSE_PUB/create operation.
+ *
+ * @param[in,out] ppch 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
*/
-struct TALER_EXCHANGE_PurseCreateDepositHandle;
+enum TALER_ErrorCode
+TALER_EXCHANGE_post_purses_create_start (
+ struct TALER_EXCHANGE_PostPursesCreateHandle *ppch,
+ TALER_EXCHANGE_PostPursesCreateCallback cb,
+ TALER_EXCHANGE_POST_PURSES_CREATE_RESULT_CLOSURE *cb_cls);
/**
- * Information about a coin to be deposited into a purse or reserve.
+ * Cancel POST /purses/$PURSE_PUB/create operation. This function must not be
+ * called by clients after the TALER_EXCHANGE_PostPursesCreateCallback has been
+ * invoked (as in those cases it'll be called internally by the implementation
+ * already).
+ *
+ * @param[in] ppch operation to cancel
*/
+void
+TALER_EXCHANGE_post_purses_create_cancel (
+ struct TALER_EXCHANGE_PostPursesCreateHandle *ppch);
+
+
+/* **************** deprecated legacy API ***************** */
/**
- * Inform the exchange that a purse should be created
- * and coins deposited into it.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param purse_priv private key of the purse
- * @param merge_priv the merge credential
- * @param contract_priv key needed to obtain and decrypt the contract
- * @param contract_terms contract the purse is about
- * @param num_deposits length of the @a deposits array
- * @param deposits array of deposits to make into the purse
- * @param upload_contract true to upload the contract; must
- * be FALSE for repeated calls to this API for the
- * same purse (i.e. when adding more deposits).
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_PostPursesCreateResponse instead.
+ */
+struct TALER_EXCHANGE_PurseCreateDepositResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct TALER_ExchangePublicKeyP exchange_pub;
+ struct TALER_ExchangeSignatureP exchange_sig;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostPursesCreateCallback instead.
+ */
+typedef void
+(*TALER_EXCHANGE_PurseCreateDepositCallback) (
+ void *cls,
+ const struct TALER_EXCHANGE_PurseCreateDepositResponse *pcr);
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostPursesCreateHandle instead.
+ */
+struct TALER_EXCHANGE_PurseCreateDepositHandle;
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_post_purses_create_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_PurseCreateDepositHandle *
TALER_EXCHANGE_purse_create_with_deposit (
@@ -122,14 +311,12 @@ TALER_EXCHANGE_purse_create_with_deposit (
TALER_EXCHANGE_PurseCreateDepositCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_purse_create_with_deposit() operation.
- *
- * @param pch handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_purses_create_cancel() instead.
*/
void
TALER_EXCHANGE_purse_create_with_deposit_cancel (
struct TALER_EXCHANGE_PurseCreateDepositHandle *pch);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_PURSES_PURSE_PUB_CREATE_H */
diff --git a/src/include/taler/taler-exchange/post-purses-PURSE_PUB-deposit.h b/src/include/taler/taler-exchange/post-purses-PURSE_PUB-deposit.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-purses-PURSE_PUB-deposit.h
@@ -24,9 +24,41 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST /purses/$PURSE_PUB/deposit.
+ */
+struct TALER_EXCHANGE_PostPursesDepositHandle;
+
+
+/**
+ * Set up POST /purses/$PURSE_PUB/deposit operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx curl context
+ * @param url exchange base URL
+ * @param keys exchange keys
+ * @param purse_exchange_url base URL of the exchange hosting the purse
+ * @param purse_pub public key of the purse to deposit into
+ * @param min_age minimum age we need to prove for the purse
+ * @param num_deposits length of the @a deposits array
+ * @param deposits array of deposits to make into the purse
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostPursesDepositHandle *
+TALER_EXCHANGE_post_purses_deposit_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const char *purse_exchange_url,
+ const struct TALER_PurseContractPublicKeyP *purse_pub,
+ uint8_t min_age,
+ unsigned int num_deposits,
+ const struct TALER_EXCHANGE_PurseDeposit deposits[static num_deposits]);
+
+
+/**
* Response generated for purse deposit request.
*/
-struct TALER_EXCHANGE_PurseDepositResponse
+struct TALER_EXCHANGE_PostPursesDepositResponse
{
/**
* Full HTTP response.
@@ -39,11 +71,10 @@ struct TALER_EXCHANGE_PurseDepositResponse
union
{
/**
- * Detailed returned on #MHD_HTTP_OK.
+ * Details returned on #MHD_HTTP_OK.
*/
struct
{
-
/**
* When does the purse expire.
*/
@@ -69,40 +100,93 @@ struct TALER_EXCHANGE_PurseDepositResponse
};
+
+#ifndef TALER_EXCHANGE_POST_PURSES_DEPOSIT_RESULT_CLOSURE
/**
- * Function called with information about a purse-deposit
- * operation.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostPursesDepositCallback.
+ */
+#define TALER_EXCHANGE_POST_PURSES_DEPOSIT_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_PURSES_DEPOSIT_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /purses/$PURSE_PUB/deposit request.
*
* @param cls closure
- * @param pdr HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostPursesDepositCallback)(
+ TALER_EXCHANGE_POST_PURSES_DEPOSIT_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostPursesDepositResponse *result);
+
+
+/**
+ * Start POST /purses/$PURSE_PUB/deposit operation.
+ *
+ * @param[in,out] ppdh 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_purses_deposit_start (
+ struct TALER_EXCHANGE_PostPursesDepositHandle *ppdh,
+ TALER_EXCHANGE_PostPursesDepositCallback cb,
+ TALER_EXCHANGE_POST_PURSES_DEPOSIT_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /purses/$PURSE_PUB/deposit operation. This function must not
+ * be called by clients after the TALER_EXCHANGE_PostPursesDepositCallback has
+ * been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] ppdh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_purses_deposit_cancel (
+ struct TALER_EXCHANGE_PostPursesDepositHandle *ppdh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostPursesDepositResponse instead.
+ */
+struct TALER_EXCHANGE_PurseDepositResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct GNUNET_TIME_Timestamp purse_expiration;
+ struct TALER_Amount total_deposited;
+ struct TALER_Amount purse_value_after_fees;
+ struct TALER_PrivateContractHashP h_contract_terms;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostPursesDepositCallback instead.
*/
typedef void
(*TALER_EXCHANGE_PurseDepositCallback) (
void *cls,
const struct TALER_EXCHANGE_PurseDepositResponse *pdr);
-
/**
- * @brief Handle for a POST /purses/$PID/deposit request.
+ * @deprecated Use #TALER_EXCHANGE_PostPursesDepositHandle instead.
*/
struct TALER_EXCHANGE_PurseDepositHandle;
-
/**
- * Inform the exchange that a deposit should be made into
- * a purse.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param purse_exchange_url base URL of the exchange hosting the purse
- * @param purse_pub public key of the purse to merge
- * @param min_age minimum age we need to prove for the purse
- * @param num_deposits length of the @a deposits array
- * @param deposits array of deposits to make into the purse
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_purses_deposit_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_PurseDepositHandle *
TALER_EXCHANGE_purse_deposit (
@@ -117,14 +201,12 @@ TALER_EXCHANGE_purse_deposit (
TALER_EXCHANGE_PurseDepositCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_purse_deposit() operation.
- *
- * @param amh handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_purses_deposit_cancel() instead.
*/
void
TALER_EXCHANGE_purse_deposit_cancel (
struct TALER_EXCHANGE_PurseDepositHandle *amh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_PURSES_PURSE_PUB_DEPOSIT_H */
diff --git a/src/include/taler/taler-exchange/post-purses-PURSE_PUB-merge.h b/src/include/taler/taler-exchange/post-purses-PURSE_PUB-merge.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-purses-PURSE_PUB-merge.h
@@ -24,9 +24,49 @@
#include <taler/taler-exchange/common.h>
/**
+ * Handle for an operation to POST /purses/$PURSE_PUB/merge.
+ */
+struct TALER_EXCHANGE_PostPursesMergeHandle;
+
+
+/**
+ * Set up POST /purses/$PURSE_PUB/merge operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx curl context
+ * @param url exchange base URL
+ * @param keys exchange keys
+ * @param reserve_exchange_url base URL of the exchange with the reserve
+ * @param reserve_priv private key of the reserve to merge into
+ * @param purse_pub public key of the purse to merge
+ * @param merge_priv private key granting us the right to merge
+ * @param h_contract_terms hash of the purse's contract
+ * @param min_age minimum age of deposits into the purse
+ * @param purse_value_after_fees amount that should be in the purse
+ * @param purse_expiration when will the purse expire
+ * @param merge_timestamp when is the merge happening (current time)
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostPursesMergeHandle *
+TALER_EXCHANGE_post_purses_merge_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const char *reserve_exchange_url,
+ const struct TALER_ReservePrivateKeyP *reserve_priv,
+ const struct TALER_PurseContractPublicKeyP *purse_pub,
+ const struct TALER_PurseMergePrivateKeyP *merge_priv,
+ const struct TALER_PrivateContractHashP *h_contract_terms,
+ uint8_t min_age,
+ const struct TALER_Amount *purse_value_after_fees,
+ struct GNUNET_TIME_Timestamp purse_expiration,
+ struct GNUNET_TIME_Timestamp merge_timestamp);
+
+
+/**
* Response generated for an account merge request.
*/
-struct TALER_EXCHANGE_AccountMergeResponse
+struct TALER_EXCHANGE_PostPursesMergeResponse
{
/**
* Full HTTP response.
@@ -44,7 +84,7 @@ struct TALER_EXCHANGE_AccountMergeResponse
union
{
/**
- * Detailed returned on #MHD_HTTP_OK.
+ * Details returned on #MHD_HTTP_OK.
*/
struct
{
@@ -74,44 +114,94 @@ struct TALER_EXCHANGE_AccountMergeResponse
};
+
+#ifndef TALER_EXCHANGE_POST_PURSES_MERGE_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostPursesMergeCallback.
+ */
+#define TALER_EXCHANGE_POST_PURSES_MERGE_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_PURSES_MERGE_RESULT_CLOSURE */
+
/**
- * Function called with information about an account merge
- * operation.
+ * Type of the function that receives the result of a
+ * POST /purses/$PURSE_PUB/merge request.
*
* @param cls closure
- * @param amr HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostPursesMergeCallback)(
+ TALER_EXCHANGE_POST_PURSES_MERGE_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostPursesMergeResponse *result);
+
+
+/**
+ * Start POST /purses/$PURSE_PUB/merge operation.
+ *
+ * @param[in,out] ppmh 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_purses_merge_start (
+ struct TALER_EXCHANGE_PostPursesMergeHandle *ppmh,
+ TALER_EXCHANGE_PostPursesMergeCallback cb,
+ TALER_EXCHANGE_POST_PURSES_MERGE_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /purses/$PURSE_PUB/merge operation. This function must not be
+ * called by clients after the TALER_EXCHANGE_PostPursesMergeCallback has been
+ * invoked (as in those cases it'll be called internally by the implementation
+ * already).
+ *
+ * @param[in] ppmh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_purses_merge_cancel (
+ struct TALER_EXCHANGE_PostPursesMergeHandle *ppmh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostPursesMergeResponse instead.
+ */
+struct TALER_EXCHANGE_AccountMergeResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ const struct TALER_ReserveSignatureP *reserve_sig;
+ union
+ {
+ struct
+ {
+ struct TALER_ExchangeSignatureP exchange_sig;
+ struct TALER_ExchangePublicKeyP exchange_pub;
+ struct GNUNET_TIME_Timestamp etime;
+ } ok;
+ struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostPursesMergeCallback instead.
*/
typedef void
(*TALER_EXCHANGE_AccountMergeCallback) (
void *cls,
const struct TALER_EXCHANGE_AccountMergeResponse *amr);
-
/**
- * @brief Handle for a POST /purses/$PID/merge request.
+ * @deprecated Use #TALER_EXCHANGE_PostPursesMergeHandle instead.
*/
struct TALER_EXCHANGE_AccountMergeHandle;
-
/**
- * Inform the exchange that a purse should be merged
- * with a reserve.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param reserve_exchange_url base URL of the exchange with the reserve
- * @param reserve_priv private key of the reserve to merge into
- * @param purse_pub public key of the purse to merge
- * @param merge_priv private key granting us the right to merge
- * @param h_contract_terms hash of the purses' contract
- * @param min_age minimum age of deposits into the purse
- * @param purse_value_after_fees amount that should be in the purse
- * @param purse_expiration when will the purse expire
- * @param merge_timestamp when is the merge happening (current time)
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_purses_merge_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_AccountMergeHandle *
TALER_EXCHANGE_account_merge (
@@ -130,14 +220,12 @@ TALER_EXCHANGE_account_merge (
TALER_EXCHANGE_AccountMergeCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_account_merge() operation.
- *
- * @param amh handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_purses_merge_cancel() instead.
*/
void
TALER_EXCHANGE_account_merge_cancel (
struct TALER_EXCHANGE_AccountMergeHandle *amh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_PURSES_PURSE_PUB_MERGE_H */
diff --git a/src/include/taler/taler-exchange/post-recoup-refresh.h b/src/include/taler/taler-exchange/post-recoup-refresh.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-recoup-refresh.h
@@ -23,19 +23,50 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /recoup-refresh *********************** */
+/**
+ * Handle for an operation to POST /coins/$COIN_PUB/recoup-refresh.
+ */
+struct TALER_EXCHANGE_PostRecoupRefreshHandle;
/**
- * @brief A /recoup-refresh Handle
+ * Set up POST /coins/$COIN_PUB/recoup-refresh operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * Ask the exchange to pay back a coin due to the exchange triggering
+ * the emergency recoup protocol for a given denomination. The value
+ * of the coin will be refunded to the original coin that the
+ * revoked coin was refreshed from. The original coin is then
+ * considered a zombie.
+ *
+ * @param ctx curl context
+ * @param url exchange base URL
+ * @param keys exchange keys
+ * @param pk kind of coin to pay back
+ * @param denom_sig signature over the coin by the exchange using @a pk
+ * @param exchange_vals contribution from the exchange on the withdraw
+ * @param rms the public seed of the refreshing operation
+ * @param ps coin-specific secrets derived for this coin during the refreshing operation
+ * @param idx index of the fresh coin in the refresh operation that is now being recouped
+ * @return handle to operation, NULL if the inputs are invalid
*/
-struct TALER_EXCHANGE_RecoupRefreshHandle;
+struct TALER_EXCHANGE_PostRecoupRefreshHandle *
+TALER_EXCHANGE_post_recoup_refresh_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_EXCHANGE_DenomPublicKey *pk,
+ const struct TALER_DenominationSignature *denom_sig,
+ const struct TALER_ExchangeBlindingValues *exchange_vals,
+ const struct TALER_PublicRefreshMasterSeedP *rms,
+ const struct TALER_PlanchetMasterSecretP *ps,
+ unsigned int idx);
/**
- * Response from a /recoup-refresh request.
+ * Response from a POST /coins/$COIN_PUB/recoup-refresh request.
*/
-struct TALER_EXCHANGE_RecoupRefreshResponse
+struct TALER_EXCHANGE_PostRecoupRefreshResponse
{
/**
* HTTP response data
@@ -63,40 +94,89 @@ struct TALER_EXCHANGE_RecoupRefreshResponse
};
+#ifndef TALER_EXCHANGE_POST_RECOUP_REFRESH_RESULT_CLOSURE
/**
- * Callbacks of this type are used to return the final result of
- * submitting a recoup-refresh request to a exchange.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostRecoupRefreshCallback.
+ */
+#define TALER_EXCHANGE_POST_RECOUP_REFRESH_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_RECOUP_REFRESH_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /coins/$COIN_PUB/recoup-refresh request.
*
* @param cls closure
- * @param rrr response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostRecoupRefreshCallback)(
+ TALER_EXCHANGE_POST_RECOUP_REFRESH_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostRecoupRefreshResponse *result);
+
+
+/**
+ * Start POST /coins/$COIN_PUB/recoup-refresh operation.
+ *
+ * @param[in,out] prrh 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_recoup_refresh_start (
+ struct TALER_EXCHANGE_PostRecoupRefreshHandle *prrh,
+ TALER_EXCHANGE_PostRecoupRefreshCallback cb,
+ TALER_EXCHANGE_POST_RECOUP_REFRESH_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /coins/$COIN_PUB/recoup-refresh operation. This function must
+ * not be called by clients after the
+ * TALER_EXCHANGE_PostRecoupRefreshCallback has been invoked (as in those
+ * cases it'll be called internally by the implementation already).
+ *
+ * @param[in] prrh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_recoup_refresh_cancel (
+ struct TALER_EXCHANGE_PostRecoupRefreshHandle *prrh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostRecoupRefreshResponse instead.
+ */
+struct TALER_EXCHANGE_RecoupRefreshResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct TALER_CoinSpendPublicKeyP old_coin_pub;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostRecoupRefreshCallback instead.
*/
typedef void
(*TALER_EXCHANGE_RecoupRefreshResultCallback) (
void *cls,
const struct TALER_EXCHANGE_RecoupRefreshResponse *rrr);
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostRecoupRefreshHandle instead.
+ */
+struct TALER_EXCHANGE_RecoupRefreshHandle;
/**
- * Ask the exchange to pay back a coin due to the exchange triggering
- * the emergency recoup protocol for a given denomination. The value
- * of the coin will be refunded to the original coin that the
- * revoked coin was refreshed from. The original coin is then
- * considered a zombie.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param pk kind of coin to pay back
- * @param denom_sig signature over the coin by the exchange using @a pk
- * @param exchange_vals contribution from the exchange on the withdraw
- * @param rms the public seed of the refreshing operation
- * @param ps coin-specific secrets derived for this coin during the refreshing operation
- * @param idx index of the fresh coin in the refresh operation that is now being recouped
- * @param recoup_cb the callback to call when the final result for this request is available
- * @param recoup_cb_cls closure for @a recoup_cb
- * @return NULL
- * if the inputs are invalid (i.e. denomination key not with this exchange).
- * In this case, the callback is not called.
+ * @deprecated Use #TALER_EXCHANGE_post_recoup_refresh_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_RecoupRefreshHandle *
TALER_EXCHANGE_recoup_refresh (
@@ -112,15 +192,12 @@ TALER_EXCHANGE_recoup_refresh (
TALER_EXCHANGE_RecoupRefreshResultCallback recoup_cb,
void *recoup_cb_cls);
-
/**
- * Cancel a recoup-refresh request. This function cannot be used on a request
- * handle if the callback was already invoked.
- *
- * @param ph the recoup handle
+ * @deprecated Use #TALER_EXCHANGE_post_recoup_refresh_cancel() instead.
*/
void
TALER_EXCHANGE_recoup_refresh_cancel (
struct TALER_EXCHANGE_RecoupRefreshHandle *ph);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_RECOUP_REFRESH_H */
diff --git a/src/include/taler/taler-exchange/post-recoup-withdraw.h b/src/include/taler/taler-exchange/post-recoup-withdraw.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-recoup-withdraw.h
@@ -23,19 +23,46 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /recoup *********************** */
+/**
+ * Handle for an operation to POST /coins/$COIN_PUB/recoup.
+ */
+struct TALER_EXCHANGE_PostRecoupWithdrawHandle;
/**
- * @brief A /recoup Handle
+ * Set up POST /coins/$COIN_PUB/recoup operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * Ask the exchange to pay back a coin due to the exchange triggering
+ * the emergency recoup protocol for a given denomination. The value
+ * of the coin will be refunded to the original customer (without fees).
+ *
+ * @param ctx curl context
+ * @param url exchange base URL
+ * @param keys exchange keys
+ * @param pk kind of coin to pay back
+ * @param denom_sig signature over the coin by the exchange using @a pk
+ * @param exchange_vals contribution from the exchange on the withdraw
+ * @param ps secret internals of the original planchet
+ * @param h_planchets hash of the commitment of the corresponding original withdraw request
+ * @return handle to operation, NULL if the inputs are invalid
*/
-struct TALER_EXCHANGE_RecoupHandle;
+struct TALER_EXCHANGE_PostRecoupWithdrawHandle *
+TALER_EXCHANGE_post_recoup_withdraw_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_EXCHANGE_DenomPublicKey *pk,
+ const struct TALER_DenominationSignature *denom_sig,
+ const struct TALER_ExchangeBlindingValues *exchange_vals,
+ const struct TALER_PlanchetMasterSecretP *ps,
+ const struct TALER_HashBlindedPlanchetsP *h_planchets);
/**
- * Response from a recoup request.
+ * Response from a POST /coins/$COIN_PUB/recoup request.
*/
-struct TALER_EXCHANGE_RecoupResponse
+struct TALER_EXCHANGE_PostRecoupWithdrawResponse
{
/**
* HTTP response data
@@ -63,39 +90,89 @@ struct TALER_EXCHANGE_RecoupResponse
};
+#ifndef TALER_EXCHANGE_POST_RECOUP_WITHDRAW_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostRecoupWithdrawCallback.
+ */
+#define TALER_EXCHANGE_POST_RECOUP_WITHDRAW_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_RECOUP_WITHDRAW_RESULT_CLOSURE */
+
/**
- * Callbacks of this type are used to return the final result of
- * submitting a recoup request to a exchange. If the operation was
- * successful, this function returns the @a reserve_pub of the
- * reserve that was credited.
+ * Type of the function that receives the result of a
+ * POST /coins/$COIN_PUB/recoup request.
*
* @param cls closure
- * @param rr response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostRecoupWithdrawCallback)(
+ TALER_EXCHANGE_POST_RECOUP_WITHDRAW_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostRecoupWithdrawResponse *result);
+
+
+/**
+ * Start POST /coins/$COIN_PUB/recoup operation.
+ *
+ * @param[in,out] prwh 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_recoup_withdraw_start (
+ struct TALER_EXCHANGE_PostRecoupWithdrawHandle *prwh,
+ TALER_EXCHANGE_PostRecoupWithdrawCallback cb,
+ TALER_EXCHANGE_POST_RECOUP_WITHDRAW_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /coins/$COIN_PUB/recoup operation. This function must not be
+ * called by clients after the TALER_EXCHANGE_PostRecoupWithdrawCallback has
+ * been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] prwh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_recoup_withdraw_cancel (
+ struct TALER_EXCHANGE_PostRecoupWithdrawHandle *prwh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostRecoupWithdrawResponse instead.
+ */
+struct TALER_EXCHANGE_RecoupResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct TALER_ReservePublicKeyP reserve_pub;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostRecoupWithdrawCallback instead.
*/
typedef void
(*TALER_EXCHANGE_RecoupResultCallback) (
void *cls,
const struct TALER_EXCHANGE_RecoupResponse *rr);
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostRecoupWithdrawHandle instead.
+ */
+struct TALER_EXCHANGE_RecoupHandle;
/**
- * Ask the exchange to pay back a coin due to the exchange triggering
- * the emergency recoup protocol for a given denomination. The value
- * of the coin will be refunded to the original customer (without fees).
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param pk kind of coin to pay back
- * @param denom_sig signature over the coin by the exchange using @a pk
- * @param exchange_vals contribution from the exchange on the withdraw
- * @param ps secret internals of the original planchet
- * @param h_planchets hash of the commitment of the corresponding original withdraw request
- * @param recoup_cb the callback to call when the final result for this request is available
- * @param recoup_cb_cls closure for @a recoup_cb
- * @return NULL
- * if the inputs are invalid (i.e. denomination key not with this exchange).
- * In this case, the callback is not called.
+ * @deprecated Use #TALER_EXCHANGE_post_recoup_withdraw_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_RecoupHandle *
TALER_EXCHANGE_recoup (
@@ -110,14 +187,11 @@ TALER_EXCHANGE_recoup (
TALER_EXCHANGE_RecoupResultCallback recoup_cb,
void *recoup_cb_cls);
-
/**
- * Cancel a recoup request. This function cannot be used on a
- * request handle if the callback was already invoked.
- *
- * @param ph the recoup handle
+ * @deprecated Use #TALER_EXCHANGE_post_recoup_withdraw_cancel() instead.
*/
void
TALER_EXCHANGE_recoup_cancel (struct TALER_EXCHANGE_RecoupHandle *ph);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_RECOUP_WITHDRAW_H */
diff --git a/src/include/taler/taler-exchange/post-reserves-RESERVE_PUB-close.h b/src/include/taler/taler-exchange/post-reserves-RESERVE_PUB-close.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-reserves-RESERVE_PUB-close.h
@@ -23,21 +23,146 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /reserves/$RID/close *********************** */
-
/**
- * @brief A /reserves/$RID/close Handle
+ * Possible options we can set for the POST /reserves/$RESERVE_PUB/close request.
*/
-struct TALER_EXCHANGE_ReservesCloseHandle;
+enum TALER_EXCHANGE_PostReservesCloseOption
+{
+ /**
+ * End of list of options.
+ */
+ TALER_EXCHANGE_POST_RESERVES_CLOSE_OPTION_END = 0,
+
+ /**
+ * Target payto URI to send the reserve balance to.
+ * If not set, the exchange will use the reserve's origin account.
+ */
+ TALER_EXCHANGE_POST_RESERVES_CLOSE_OPTION_PAYTO_URI
+
+};
/**
- * @brief Reserve close result details.
+ * Value for an option we can set for the POST /reserves/$RESERVE_PUB/close request.
*/
-struct TALER_EXCHANGE_ReserveCloseResult
+struct TALER_EXCHANGE_PostReservesCloseOptionValue
{
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_PostReservesCloseOption option;
+
+ /**
+ * Specific option value.
+ */
+ union
+ {
+ /**
+ * Value if @e option is
+ * #TALER_EXCHANGE_POST_RESERVES_CLOSE_OPTION_PAYTO_URI.
+ */
+ struct TALER_FullPayto payto_uri;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to POST /reserves/$RESERVE_PUB/close.
+ */
+struct TALER_EXCHANGE_PostReservesCloseHandle;
+
+
+/**
+ * Set up POST /reserves/$RESERVE_PUB/close operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx curl context
+ * @param url exchange base URL
+ * @param reserve_priv private key of the reserve to close
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostReservesCloseHandle *
+TALER_EXCHANGE_post_reserves_close_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const struct TALER_ReservePrivateKeyP *reserve_priv);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_PostReservesCloseOptionValue
+ */
+#define TALER_EXCHANGE_post_reserves_close_option_end_() \
+ (const struct TALER_EXCHANGE_PostReservesCloseOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_RESERVES_CLOSE_OPTION_END \
+ }
+
+/**
+ * Set the target payto URI to send the reserve balance to.
+ *
+ * @param p the target payto URI
+ * @return representation of the option as a struct TALER_EXCHANGE_PostReservesCloseOptionValue
+ */
+#define TALER_EXCHANGE_post_reserves_close_option_payto_uri(p) \
+ (const struct TALER_EXCHANGE_PostReservesCloseOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_RESERVES_CLOSE_OPTION_PAYTO_URI, \
+ .details.payto_uri = (p) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param prch the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_post_reserves_close_set_options_ (
+ struct TALER_EXCHANGE_PostReservesCloseHandle *prch,
+ unsigned int num_options,
+ struct TALER_EXCHANGE_PostReservesCloseOptionValue options[
+ static num_options]);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param prch the request to set the options for
+ * @param ... the list of the options, each option must be created
+ * by helpers TALER_EXCHANGE_post_reserves_close_option_NAME(VALUE)
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_post_reserves_close_set_options(prch,...) \
+ TALER_EXCHANGE_post_reserves_close_set_options_ ( \
+ prch, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_PostReservesCloseOptionValue[]) \
+ {__VA_ARGS__, \
+ TALER_EXCHANGE_post_reserves_close_option_end_ ()} \
+ ))
+
+/**
+ * Response from a POST /reserves/$RESERVE_PUB/close request.
+ */
+struct TALER_EXCHANGE_PostReservesCloseResponse
+{
/**
* High-level HTTP response details.
*/
@@ -48,14 +173,12 @@ struct TALER_EXCHANGE_ReserveCloseResult
*/
union
{
-
/**
* Information returned on success, if
* @e hr.http_status is #MHD_HTTP_OK
*/
struct
{
-
/**
* Amount wired to the target account.
*/
@@ -72,30 +195,90 @@ struct TALER_EXCHANGE_ReserveCloseResult
};
+#ifndef TALER_EXCHANGE_POST_RESERVES_CLOSE_RESULT_CLOSURE
/**
- * Callbacks of this type are used to serve the result of submitting a
- * reserve close request to a exchange.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostReservesCloseCallback.
+ */
+#define TALER_EXCHANGE_POST_RESERVES_CLOSE_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_RESERVES_CLOSE_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /reserves/$RESERVE_PUB/close request.
*
* @param cls closure
- * @param ror HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostReservesCloseCallback)(
+ TALER_EXCHANGE_POST_RESERVES_CLOSE_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostReservesCloseResponse *result);
+
+
+/**
+ * Start POST /reserves/$RESERVE_PUB/close operation.
+ *
+ * @param[in,out] prch 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_reserves_close_start (
+ struct TALER_EXCHANGE_PostReservesCloseHandle *prch,
+ TALER_EXCHANGE_PostReservesCloseCallback cb,
+ TALER_EXCHANGE_POST_RESERVES_CLOSE_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /reserves/$RESERVE_PUB/close operation. This function must not
+ * be called by clients after the TALER_EXCHANGE_PostReservesCloseCallback has
+ * been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] prch operation to cancel
+ */
+void
+TALER_EXCHANGE_post_reserves_close_cancel (
+ struct TALER_EXCHANGE_PostReservesCloseHandle *prch);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostReservesCloseResponse instead.
+ */
+struct TALER_EXCHANGE_ReserveCloseResult
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct TALER_Amount wire_amount;
+ } ok;
+ struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostReservesCloseCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ReservesCloseCallback) (
void *cls,
const struct TALER_EXCHANGE_ReserveCloseResult *ror);
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostReservesCloseHandle instead.
+ */
+struct TALER_EXCHANGE_ReservesCloseHandle;
/**
- * Submit a request to close a reserve.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param reserve_priv private key of the reserve to close
- * @param target_payto_uri where to send the payment, NULL to send to reserve origin
- * @param cb the callback to call when a reply for this request is available
- * @param cb_cls closure for the above callback
- * @return a handle for this request; NULL if the inputs are invalid (i.e.
- * signatures fail to verify). In this case, the callback is not called.
+ * @deprecated Use #TALER_EXCHANGE_post_reserves_close_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ReservesCloseHandle *
TALER_EXCHANGE_reserves_close (
@@ -106,16 +289,12 @@ TALER_EXCHANGE_reserves_close (
TALER_EXCHANGE_ReservesCloseCallback cb,
void *cb_cls);
-
/**
- * Cancel a reserve status request. This function cannot be used
- * on a request handle if a response is already served for it.
- *
- * @param rch the reserve request handle
+ * @deprecated Use #TALER_EXCHANGE_post_reserves_close_cancel() instead.
*/
void
TALER_EXCHANGE_reserves_close_cancel (
struct TALER_EXCHANGE_ReservesCloseHandle *rch);
-#endif
+#endif /* _TALER_EXCHANGE__POST_RESERVES_RESERVE_PUB_CLOSE_H */
diff --git a/src/include/taler/taler-exchange/post-reserves-RESERVE_PUB-open.h b/src/include/taler/taler-exchange/post-reserves-RESERVE_PUB-open.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-reserves-RESERVE_PUB-open.h
@@ -23,21 +23,46 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /reserves/$RID/open *********************** */
+/**
+ * Handle for an operation to POST /reserves/$RESERVE_PUB/open.
+ */
+struct TALER_EXCHANGE_PostReservesOpenHandle;
/**
- * @brief A /reserves/$RID/open Handle
+ * Set up POST /reserves/$RESERVE_PUB/open operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx curl context
+ * @param url exchange base URL
+ * @param keys exchange keys
+ * @param reserve_priv private key of the reserve to open
+ * @param reserve_contribution amount to pay from the reserve's balance for the operation
+ * @param coin_payments_length length of the @a coin_payments array
+ * @param coin_payments array of coin payments to use for opening the reserve
+ * @param expiration_time desired new expiration time for the reserve
+ * @param min_purses minimum number of purses to allow being concurrently opened per reserve
+ * @return handle to operation, NULL on error
*/
-struct TALER_EXCHANGE_ReservesOpenHandle;
+struct TALER_EXCHANGE_PostReservesOpenHandle *
+TALER_EXCHANGE_post_reserves_open_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_ReservePrivateKeyP *reserve_priv,
+ const struct TALER_Amount *reserve_contribution,
+ unsigned int coin_payments_length,
+ const struct TALER_EXCHANGE_PurseDeposit coin_payments[
+ static coin_payments_length],
+ struct GNUNET_TIME_Timestamp expiration_time,
+ uint32_t min_purses);
/**
- * @brief Reserve open result details.
+ * Response from a POST /reserves/$RESERVE_PUB/open request.
*/
-struct TALER_EXCHANGE_ReserveOpenResult
+struct TALER_EXCHANGE_PostReservesOpenResponse
{
-
/**
* High-level HTTP response details.
*/
@@ -48,7 +73,6 @@ struct TALER_EXCHANGE_ReserveOpenResult
*/
union
{
-
/**
* Information returned on success, if
* @e hr.http_status is #MHD_HTTP_OK
@@ -67,7 +91,6 @@ struct TALER_EXCHANGE_ReserveOpenResult
} ok;
-
/**
* Information returned if the payment provided is insufficient, if
* @e hr.http_status is #MHD_HTTP_PAYMENT_REQUIRED
@@ -87,8 +110,7 @@ struct TALER_EXCHANGE_ReserveOpenResult
} payment_required;
/**
- * Information returned if status is
- * #MHD_HTTP_CONFLICT.
+ * Information returned if status is #MHD_HTTP_CONFLICT.
*/
struct
{
@@ -109,35 +131,100 @@ struct TALER_EXCHANGE_ReserveOpenResult
};
+#ifndef TALER_EXCHANGE_POST_RESERVES_OPEN_RESULT_CLOSURE
/**
- * Callbacks of this type are used to serve the result of submitting a
- * reserve open request to a exchange.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostReservesOpenCallback.
+ */
+#define TALER_EXCHANGE_POST_RESERVES_OPEN_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_RESERVES_OPEN_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /reserves/$RESERVE_PUB/open request.
*
* @param cls closure
- * @param ror HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostReservesOpenCallback)(
+ TALER_EXCHANGE_POST_RESERVES_OPEN_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostReservesOpenResponse *result);
+
+
+/**
+ * Start POST /reserves/$RESERVE_PUB/open operation.
+ *
+ * @param[in,out] proh 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_reserves_open_start (
+ struct TALER_EXCHANGE_PostReservesOpenHandle *proh,
+ TALER_EXCHANGE_PostReservesOpenCallback cb,
+ TALER_EXCHANGE_POST_RESERVES_OPEN_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /reserves/$RESERVE_PUB/open operation. This function must not
+ * be called by clients after the TALER_EXCHANGE_PostReservesOpenCallback has
+ * been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] proh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_reserves_open_cancel (
+ struct TALER_EXCHANGE_PostReservesOpenHandle *proh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostReservesOpenResponse instead.
+ */
+struct TALER_EXCHANGE_ReserveOpenResult
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct GNUNET_TIME_Timestamp expiration_time;
+ struct TALER_Amount open_cost;
+ } ok;
+ struct
+ {
+ struct GNUNET_TIME_Timestamp expiration_time;
+ struct TALER_Amount open_cost;
+ } payment_required;
+ struct
+ {
+ struct TALER_CoinSpendPublicKeyP coin_pub;
+ } conflict;
+ struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostReservesOpenCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ReservesOpenCallback) (
void *cls,
const struct TALER_EXCHANGE_ReserveOpenResult *ror);
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostReservesOpenHandle instead.
+ */
+struct TALER_EXCHANGE_ReservesOpenHandle;
/**
- * Submit a request to open a reserve.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param reserve_priv private key of the reserve to open
- * @param reserve_contribution amount to pay from the reserve's balance for the operation
- * @param coin_payments_length length of the @a coin_payments array
- * @param coin_payments array of coin payments to use for opening the reserve
- * @param expiration_time desired new expiration time for the reserve
- * @param min_purses minimum number of purses to allow being concurrently opened per reserve
- * @param cb the callback to call when a reply for this request is available
- * @param cb_cls closure for the above callback
- * @return a handle for this request; NULL if the inputs are invalid (i.e.
- * signatures fail to verify). In this case, the callback is not called.
+ * @deprecated Use #TALER_EXCHANGE_post_reserves_open_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ReservesOpenHandle *
TALER_EXCHANGE_reserves_open (
@@ -154,15 +241,12 @@ TALER_EXCHANGE_reserves_open (
TALER_EXCHANGE_ReservesOpenCallback cb,
void *cb_cls);
-
/**
- * Cancel a reserve status request. This function cannot be used
- * on a request handle if a response is already served for it.
- *
- * @param[in] roh the reserve open request handle
+ * @deprecated Use #TALER_EXCHANGE_post_reserves_open_cancel() instead.
*/
void
TALER_EXCHANGE_reserves_open_cancel (
struct TALER_EXCHANGE_ReservesOpenHandle *roh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_RESERVES_RESERVE_PUB_OPEN_H */
diff --git a/src/include/taler/taler-exchange/post-reserves-RESERVE_PUB-purse.h b/src/include/taler/taler-exchange/post-reserves-RESERVE_PUB-purse.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-reserves-RESERVE_PUB-purse.h
@@ -23,10 +23,159 @@
#include <taler/taler-exchange/common.h>
+
/**
- * Response generated for a purse creation request.
+ * Possible options we can set for the POST /reserves/$RESERVE_PUB/purse request.
*/
-struct TALER_EXCHANGE_PurseCreateMergeResponse
+enum TALER_EXCHANGE_PostReservesPurseOption
+{
+ /**
+ * End of list of options.
+ */
+ TALER_EXCHANGE_POST_RESERVES_PURSE_OPTION_END = 0,
+
+ /**
+ * Upload the contract to the exchange.
+ * If not set, defaults to not uploading the contract.
+ */
+ TALER_EXCHANGE_POST_RESERVES_PURSE_OPTION_UPLOAD_CONTRACT
+
+};
+
+
+/**
+ * Value for an option we can set for the POST /reserves/$RESERVE_PUB/purse request.
+ */
+struct TALER_EXCHANGE_PostReservesPurseOptionValue
+{
+ /**
+ * Type of the option being set.
+ */
+ enum TALER_EXCHANGE_PostReservesPurseOption option;
+
+ /**
+ * Specific option value.
+ */
+ union
+ {
+ /**
+ * Value if @e option is
+ * #TALER_EXCHANGE_POST_RESERVES_PURSE_OPTION_UPLOAD_CONTRACT.
+ */
+ bool upload_contract;
+
+ } details;
+
+};
+
+
+/**
+ * Handle for an operation to POST /reserves/$RESERVE_PUB/purse.
+ */
+struct TALER_EXCHANGE_PostReservesPurseHandle;
+
+
+/**
+ * Set up POST /reserves/$RESERVE_PUB/purse operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx curl context
+ * @param url exchange base URL
+ * @param keys exchange keys
+ * @param reserve_priv private key of the reserve
+ * @param purse_priv private key of the purse
+ * @param merge_priv private key of the merge capability
+ * @param contract_priv private key to get the contract
+ * @param contract_terms contract the purse is about
+ * @param pay_for_purse true to pay for purse creation
+ * @param merge_timestamp when should the merge happen (use current time)
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostReservesPurseHandle *
+TALER_EXCHANGE_post_reserves_purse_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_ReservePrivateKeyP *reserve_priv,
+ const struct TALER_PurseContractPrivateKeyP *purse_priv,
+ const struct TALER_PurseMergePrivateKeyP *merge_priv,
+ const struct TALER_ContractDiffiePrivateP *contract_priv,
+ const json_t *contract_terms,
+ bool pay_for_purse,
+ struct GNUNET_TIME_Timestamp merge_timestamp);
+
+
+/**
+ * Terminate the list of options.
+ *
+ * @return the terminating object of struct TALER_EXCHANGE_PostReservesPurseOptionValue
+ */
+#define TALER_EXCHANGE_post_reserves_purse_option_end_() \
+ (const struct TALER_EXCHANGE_PostReservesPurseOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_RESERVES_PURSE_OPTION_END \
+ }
+
+/**
+ * Set whether to upload the contract to the exchange.
+ *
+ * @param u true to upload the contract
+ * @return representation of the option as a struct TALER_EXCHANGE_PostReservesPurseOptionValue
+ */
+#define TALER_EXCHANGE_post_reserves_purse_option_upload_contract(u) \
+ (const struct TALER_EXCHANGE_PostReservesPurseOptionValue) \
+ { \
+ .option = TALER_EXCHANGE_POST_RESERVES_PURSE_OPTION_UPLOAD_CONTRACT, \
+ .details.upload_contract = (u) \
+ }
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param prph the request to set the options for
+ * @param num_options length of the @a options array
+ * @param options an array of options
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+enum GNUNET_GenericReturnValue
+TALER_EXCHANGE_post_reserves_purse_set_options_ (
+ struct TALER_EXCHANGE_PostReservesPurseHandle *prph,
+ unsigned int num_options,
+ struct TALER_EXCHANGE_PostReservesPurseOptionValue options[
+ static num_options]);
+
+
+/**
+ * Set the requested options for the operation.
+ *
+ * If any option fails, other options may or may not be applied.
+ *
+ * @param prph the request to set the options for
+ * @param ... the list of the options, each option must be created
+ * by helpers TALER_EXCHANGE_post_reserves_purse_option_NAME(VALUE)
+ * @return #GNUNET_OK on success,
+ * #GNUNET_NO on failure,
+ * #GNUNET_SYSERR on internal error
+ */
+#define TALER_EXCHANGE_post_reserves_purse_set_options(prph,...) \
+ TALER_EXCHANGE_post_reserves_purse_set_options_ ( \
+ prph, \
+ TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \
+ ((const struct TALER_EXCHANGE_PostReservesPurseOptionValue[]) \
+ {__VA_ARGS__, \
+ TALER_EXCHANGE_post_reserves_purse_option_end_ ()} \
+ ))
+
+
+/**
+ * Response generated for a purse creation request via reserve.
+ */
+struct TALER_EXCHANGE_PostReservesPurseResponse
{
/**
* Full HTTP response.
@@ -61,43 +210,89 @@ struct TALER_EXCHANGE_PurseCreateMergeResponse
};
+
+#ifndef TALER_EXCHANGE_POST_RESERVES_PURSE_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostReservesPurseCallback.
+ */
+#define TALER_EXCHANGE_POST_RESERVES_PURSE_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_RESERVES_PURSE_RESULT_CLOSURE */
+
/**
- * Function called with information about the creation
- * of a new purse.
+ * Type of the function that receives the result of a
+ * POST /reserves/$RESERVE_PUB/purse request.
*
* @param cls closure
- * @param pcr HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostReservesPurseCallback)(
+ TALER_EXCHANGE_POST_RESERVES_PURSE_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostReservesPurseResponse *result);
+
+
+/**
+ * Start POST /reserves/$RESERVE_PUB/purse operation.
+ *
+ * @param[in,out] prph 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_reserves_purse_start (
+ struct TALER_EXCHANGE_PostReservesPurseHandle *prph,
+ TALER_EXCHANGE_PostReservesPurseCallback cb,
+ TALER_EXCHANGE_POST_RESERVES_PURSE_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /reserves/$RESERVE_PUB/purse operation. This function must not
+ * be called by clients after the TALER_EXCHANGE_PostReservesPurseCallback has
+ * been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] prph operation to cancel
+ */
+void
+TALER_EXCHANGE_post_reserves_purse_cancel (
+ struct TALER_EXCHANGE_PostReservesPurseHandle *prph);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostReservesPurseResponse instead.
+ */
+struct TALER_EXCHANGE_PurseCreateMergeResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ const struct TALER_ReserveSignatureP *reserve_sig;
+ union
+ {
+ struct { } ok;
+ struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostReservesPurseCallback instead.
*/
typedef void
(*TALER_EXCHANGE_PurseCreateMergeCallback) (
void *cls,
const struct TALER_EXCHANGE_PurseCreateMergeResponse *pcr);
-
/**
- * @brief Handle for a POST /reserves/$RID/purse request.
+ * @deprecated Use #TALER_EXCHANGE_PostReservesPurseHandle instead.
*/
struct TALER_EXCHANGE_PurseCreateMergeHandle;
-
/**
- * Inform the exchange that a purse should be created
- * and merged with a reserve.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param keys exchange keys
- * @param reserve_priv private key of the reserve
- * @param purse_priv private key of the purse
- * @param merge_priv private key of the merge capability
- * @param contract_priv private key to get the contract
- * @param contract_terms contract the purse is about
- * @param upload_contract true to upload the contract
- * @param pay_for_purse true to pay for purse creation
- * @param merge_timestamp when should the merge happen (use current time)
- * @param cb function to call with the exchange's result
- * @param cb_cls closure for @a cb
- * @return the request handle; NULL upon error
+ * @deprecated Use #TALER_EXCHANGE_post_reserves_purse_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_PurseCreateMergeHandle *
TALER_EXCHANGE_purse_create_with_merge (
@@ -115,14 +310,12 @@ TALER_EXCHANGE_purse_create_with_merge (
TALER_EXCHANGE_PurseCreateMergeCallback cb,
void *cb_cls);
-
/**
- * Cancel #TALER_EXCHANGE_purse_create_with_merge() operation.
- *
- * @param pcm handle of the operation to cancel
+ * @deprecated Use #TALER_EXCHANGE_post_reserves_purse_cancel() instead.
*/
void
TALER_EXCHANGE_purse_create_with_merge_cancel (
struct TALER_EXCHANGE_PurseCreateMergeHandle *pcm);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_RESERVES_RESERVE_PUB_PURSE_H */
diff --git a/src/include/taler/taler-exchange/post-reserves-attest-RESERVE_PUB.h b/src/include/taler/taler-exchange/post-reserves-attest-RESERVE_PUB.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-reserves-attest-RESERVE_PUB.h
@@ -24,17 +24,38 @@
#include <taler/taler-exchange/common.h>
/**
- * @brief A POST /reserves/$RID/attest Handle
+ * Handle for an operation to POST /reserves/$RESERVE_PUB/attest.
*/
-struct TALER_EXCHANGE_ReservesPostAttestHandle;
+struct TALER_EXCHANGE_PostReservesAttestHandle;
/**
- * @brief Reserve attest result details.
+ * Set up POST /reserves/$RESERVE_PUB/attest operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx CURL context
+ * @param url exchange base URL
+ * @param keys exchange key data
+ * @param reserve_priv private key of the reserve to attest
+ * @param attributes_length length of the @a attributes array
+ * @param attributes array of names of attributes to get attestations for
+ * @return handle to operation, NULL on error
*/
-struct TALER_EXCHANGE_ReservePostAttestResult
-{
+struct TALER_EXCHANGE_PostReservesAttestHandle *
+TALER_EXCHANGE_post_reserves_attest_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_ReservePrivateKeyP *reserve_priv,
+ unsigned int attributes_length,
+ const char *attributes[const static attributes_length]);
+
+/**
+ * Response from a POST /reserves/$RESERVE_PUB/attest request.
+ */
+struct TALER_EXCHANGE_PostReservesAttestResponse
+{
/**
* High-level HTTP response details.
*/
@@ -45,7 +66,6 @@ struct TALER_EXCHANGE_ReservePostAttestResult
*/
union
{
-
/**
* Information returned on success, if
* @e hr.http_status is #MHD_HTTP_OK
@@ -84,32 +104,93 @@ struct TALER_EXCHANGE_ReservePostAttestResult
};
+#ifndef TALER_EXCHANGE_POST_RESERVES_ATTEST_RESULT_CLOSURE
/**
- * Callbacks of this type are used to serve the result of submitting a
- * reserve attest request to a exchange.
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostReservesAttestCallback.
+ */
+#define TALER_EXCHANGE_POST_RESERVES_ATTEST_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_RESERVES_ATTEST_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /reserves/$RESERVE_PUB/attest request.
*
* @param cls closure
- * @param ror HTTP response data
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostReservesAttestCallback)(
+ TALER_EXCHANGE_POST_RESERVES_ATTEST_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostReservesAttestResponse *result);
+
+
+/**
+ * Start POST /reserves/$RESERVE_PUB/attest operation.
+ *
+ * @param[in,out] prah 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_reserves_attest_start (
+ struct TALER_EXCHANGE_PostReservesAttestHandle *prah,
+ TALER_EXCHANGE_PostReservesAttestCallback cb,
+ TALER_EXCHANGE_POST_RESERVES_ATTEST_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /reserves/$RESERVE_PUB/attest operation. This function must
+ * not be called by clients after the
+ * TALER_EXCHANGE_PostReservesAttestCallback has been invoked (as in those
+ * cases it'll be called internally by the implementation already).
+ *
+ * @param[in] prah operation to cancel
+ */
+void
+TALER_EXCHANGE_post_reserves_attest_cancel (
+ struct TALER_EXCHANGE_PostReservesAttestHandle *prah);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostReservesAttestResponse instead.
+ */
+struct TALER_EXCHANGE_ReservePostAttestResult
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ struct GNUNET_TIME_Timestamp exchange_time;
+ struct GNUNET_TIME_Timestamp expiration_time;
+ struct TALER_ExchangeSignatureP exchange_sig;
+ struct TALER_ExchangePublicKeyP exchange_pub;
+ const json_t *attributes;
+ } ok;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostReservesAttestCallback instead.
*/
typedef void
(*TALER_EXCHANGE_ReservesPostAttestCallback) (
void *cls,
const struct TALER_EXCHANGE_ReservePostAttestResult *ror);
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostReservesAttestHandle instead.
+ */
+struct TALER_EXCHANGE_ReservesAttestHandle;
/**
- * Submit a request to attest attributes about the owner of a reserve.
- *
- * @param ctx CURL context
- * @param url exchange base URL
- * @param keys exchange key data
- * @param reserve_priv private key of the reserve to attest
- * @param attributes_length length of the @a attributes array
- * @param attributes array of names of attributes to get attestations for
- * @param cb the callback to call when a reply for this request is available
- * @param cb_cls closure for the above callback
- * @return a handle for this request; NULL if the inputs are invalid (i.e.
- * signatures fail to verify). In this case, the callback is not called.
+ * @deprecated Use #TALER_EXCHANGE_post_reserves_attest_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_ReservesAttestHandle *
TALER_EXCHANGE_reserves_attest (
@@ -122,15 +203,12 @@ TALER_EXCHANGE_reserves_attest (
TALER_EXCHANGE_ReservesPostAttestCallback cb,
void *cb_cls);
-
/**
- * Cancel a reserve attestation request. This function cannot be used
- * on a request handle if a response is already served for it.
- *
- * @param rah the reserve attest request handle
+ * @deprecated Use #TALER_EXCHANGE_post_reserves_attest_cancel() instead.
*/
void
TALER_EXCHANGE_reserves_attest_cancel (
struct TALER_EXCHANGE_ReservesAttestHandle *rah);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_RESERVES_ATTEST_RESERVE_PUB_H */
diff --git a/src/include/taler/taler-exchange/post-reveal-melt.h b/src/include/taler/taler-exchange/post-reveal-melt.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-reveal-melt.h
@@ -23,8 +23,6 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /reveal-melt ************************ */
-
/**
* Information about a coin obtained via /reveal-melt.
@@ -61,66 +59,6 @@ struct TALER_EXCHANGE_RevealedCoinInfo
/**
- * @brief A handle to a /reveal-melt request
- */
-struct TALER_EXCHANGE_RevealMeltHandle;
-
-/**
- * The response from a /reveal-melt request
- */
-struct TALER_EXCHANGE_RevealMeltResponse
-{
- /**
- * HTTP response data.
- */
- struct TALER_EXCHANGE_HttpResponse hr;
-
- /**
- * Details about the response
- */
- union
- {
- /**
- * Details if the status is #MHD_HTTP_OK.
- */
- struct
- {
- /**
- * Array of @e num_coins values about the coins obtained via the refresh
- * operation. The array give the coins in the same order (and should
- * have the same length) in which the original melt request specified the
- * respective denomination keys.
- */
- const struct TALER_EXCHANGE_RevealedCoinInfo *coins;
-
- /**
- * Number of coins returned.
- */
- unsigned int num_coins;
- } ok;
-
- /**
- * Details if the status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS.
- */
- struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
-
- } details;
-
-};
-
-/**
- * Function called with the result of a reveal-melt operation.
- *
- * @param cls closure
- * @param awr exchange response details
- */
-typedef void
-(*TALER_EXCHANGE_RevealMeltCallback)(
- void *cls,
- const struct TALER_EXCHANGE_RevealMeltResponse *awr);
-
-
-/**
* The tuple of #TALER_CNC_KAPPA - 1 signatures, that are disclosed
* during the /reveal-melt step. From these signatures, signed with
* the melted coin over refresh nonces, all input data is derived from
@@ -209,8 +147,8 @@ struct TALER_EXCHANGE_RevealMeltInput
const struct TALER_EXCHANGE_MeltInput *melt_input;
/**
- * The blinding seed that was used during the call to /melt
- * Maybe NULL
+ * The blinding seed that was used during the call to /melt.
+ * Maybe NULL.
*/
const struct TALER_BlindingMasterSeedP *blinding_seed;
@@ -233,23 +171,163 @@ struct TALER_EXCHANGE_RevealMeltInput
};
+
+/**
+ * Handle for an operation to POST /reveal-melt.
+ */
+struct TALER_EXCHANGE_PostRevealMeltHandle;
+
+
/**
- * Submit an reveal-melt request to the exchange and get the exchange's
- * response. This is the second step in the refresh protocol, after the first
- * step /melt.
+ * Set up POST /reveal-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 rd should be committed to persistent storage
+ * argument @a reveal_melt_input should be committed to persistent storage
* prior to calling this function.
*
* @param curl_ctx The curl context
* @param exchange_url The base url of the exchange
* @param reveal_melt_input The input data for the reveal
- * @param reveal_cb A callback for the result, maybe NULL
- * @param reveal_cb_cls A closure for @e reveal_cb, maybe NULL
- * @return a handle for this request; NULL if the argument was invalid.
- * In this case, the callback will not be called.
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostRevealMeltHandle *
+TALER_EXCHANGE_post_reveal_melt_create (
+ struct GNUNET_CURL_Context *curl_ctx,
+ const char *exchange_url,
+ const struct TALER_EXCHANGE_RevealMeltInput *reveal_melt_input);
+
+
+/**
+ * The response from a POST /reveal-melt request.
+ */
+struct TALER_EXCHANGE_PostRevealMeltResponse
+{
+ /**
+ * HTTP response data.
+ */
+ struct TALER_EXCHANGE_HttpResponse hr;
+
+ /**
+ * Details about the response
+ */
+ union
+ {
+ /**
+ * Details if the status is #MHD_HTTP_OK.
+ */
+ struct
+ {
+ /**
+ * Array of @e num_coins values about the coins obtained via the refresh
+ * operation. The array give the coins in the same order (and should
+ * have the same length) in which the original melt request specified the
+ * respective denomination keys.
+ */
+ const struct TALER_EXCHANGE_RevealedCoinInfo *coins;
+
+ /**
+ * Number of coins returned.
+ */
+ unsigned int num_coins;
+ } ok;
+
+ /**
+ * Details if the status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS.
+ */
+ struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
+
+ } details;
+
+};
+
+
+#ifndef TALER_EXCHANGE_POST_REVEAL_MELT_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostRevealMeltCallback.
+ */
+#define TALER_EXCHANGE_POST_REVEAL_MELT_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_REVEAL_MELT_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /reveal-melt request.
+ *
+ * @param cls closure
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostRevealMeltCallback)(
+ TALER_EXCHANGE_POST_REVEAL_MELT_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostRevealMeltResponse *result);
+
+
+/**
+ * Start POST /reveal-melt operation.
+ *
+ * @param[in,out] prmh 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_reveal_melt_start (
+ struct TALER_EXCHANGE_PostRevealMeltHandle *prmh,
+ TALER_EXCHANGE_PostRevealMeltCallback cb,
+ TALER_EXCHANGE_POST_REVEAL_MELT_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /reveal-melt operation. This function must not be called by
+ * clients after the TALER_EXCHANGE_PostRevealMeltCallback has been invoked
+ * (as in those cases it'll be called internally by the implementation
+ * already).
+ *
+ * @param[in] prmh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_reveal_melt_cancel (
+ struct TALER_EXCHANGE_PostRevealMeltHandle *prmh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostRevealMeltResponse instead.
+ */
+struct TALER_EXCHANGE_RevealMeltResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ const struct TALER_EXCHANGE_RevealedCoinInfo *coins;
+ unsigned int num_coins;
+ } ok;
+ struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostRevealMeltCallback instead.
+ */
+typedef void
+(*TALER_EXCHANGE_RevealMeltCallback)(
+ void *cls,
+ const struct TALER_EXCHANGE_RevealMeltResponse *awr);
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostRevealMeltHandle instead.
+ */
+struct TALER_EXCHANGE_RevealMeltHandle;
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_post_reveal_melt_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_RevealMeltHandle *
TALER_EXCHANGE_reveal_melt (
@@ -259,14 +337,12 @@ TALER_EXCHANGE_reveal_melt (
TALER_EXCHANGE_RevealMeltCallback reveal_cb,
void *reveal_cb_cls);
-
/**
- * @brief Cancel an reveal-melt request
- *
- * @param awrh Handle to an melt-reqveal request
+ * @deprecated Use #TALER_EXCHANGE_post_reveal_melt_cancel() instead.
*/
void
TALER_EXCHANGE_reveal_melt_cancel (
struct TALER_EXCHANGE_RevealMeltHandle *awrh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_REVEAL_MELT_H */
diff --git a/src/include/taler/taler-exchange/post-reveal-withdraw.h b/src/include/taler/taler-exchange/post-reveal-withdraw.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-reveal-withdraw.h
@@ -23,17 +23,44 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /reveal-withdraw ************************ */
+/**
+ * Handle for an operation to POST /reveal-withdraw.
+ */
+struct TALER_EXCHANGE_PostRevealWithdrawHandle;
+
/**
- * @brief A handle to a /reveal-withdraw request
+ * Set up POST /reveal-withdraw operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * This is required as the second step to a withdraw of age-restricted
+ * coins with proof that the correct age-restriction has been applied.
+ *
+ * This API is typically used by a wallet. Note that to ensure that
+ * no money is lost in case of hardware failures, the provided
+ * arguments should be committed to persistent storage
+ * prior to calling this function.
+ *
+ * @param curl_ctx The curl context
+ * @param exchange_url The base url of the exchange
+ * @param num_coins Number of coin signatures to expect from the reveal
+ * @param h_planchets The commitment from the previous call to withdraw
+ * @param seeds TALER_CNC_KAPPA-1 tuple of seeds to reveal
+ * @return handle to operation, NULL on error
*/
-struct TALER_EXCHANGE_RevealWithdrawHandle;
+struct TALER_EXCHANGE_PostRevealWithdrawHandle *
+TALER_EXCHANGE_post_reveal_withdraw_create (
+ struct GNUNET_CURL_Context *curl_ctx,
+ const char *exchange_url,
+ size_t num_coins,
+ const struct TALER_HashBlindedPlanchetsP *h_planchets,
+ const struct TALER_RevealWithdrawMasterSeedsP *seeds);
+
/**
- * The response from a /reveal-withdraw request
+ * The response from a POST /reveal-withdraw request.
*/
-struct TALER_EXCHANGE_RevealWithdrawResponse
+struct TALER_EXCHANGE_PostRevealWithdrawResponse
{
/**
* HTTP response data.
@@ -56,8 +83,8 @@ struct TALER_EXCHANGE_RevealWithdrawResponse
unsigned int num_sigs;
/**
- * Array of @e num_coins blinded denomination signatures, giving each
- * coin its value and validity. The array give these coins in the same
+ * Array of @e num_sigs blinded denomination signatures, giving each
+ * coin its value and validity. The array gives these coins in the same
* order (and should have the same length) in which the original
* withdraw request specified the respective denomination keys.
*/
@@ -74,31 +101,92 @@ struct TALER_EXCHANGE_RevealWithdrawResponse
};
+
+#ifndef TALER_EXCHANGE_POST_REVEAL_WITHDRAW_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostRevealWithdrawCallback.
+ */
+#define TALER_EXCHANGE_POST_REVEAL_WITHDRAW_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_REVEAL_WITHDRAW_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /reveal-withdraw request.
+ *
+ * @param cls closure
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostRevealWithdrawCallback)(
+ TALER_EXCHANGE_POST_REVEAL_WITHDRAW_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostRevealWithdrawResponse *result);
+
+
+/**
+ * Start POST /reveal-withdraw operation.
+ *
+ * @param[in,out] prwh 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_reveal_withdraw_start (
+ struct TALER_EXCHANGE_PostRevealWithdrawHandle *prwh,
+ TALER_EXCHANGE_PostRevealWithdrawCallback cb,
+ TALER_EXCHANGE_POST_REVEAL_WITHDRAW_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /reveal-withdraw operation. This function must not be called
+ * by clients after the TALER_EXCHANGE_PostRevealWithdrawCallback has been
+ * invoked (as in those cases it'll be called internally by the implementation
+ * already).
+ *
+ * @param[in] prwh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_reveal_withdraw_cancel (
+ struct TALER_EXCHANGE_PostRevealWithdrawHandle *prwh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostRevealWithdrawResponse instead.
+ */
+struct TALER_EXCHANGE_RevealWithdrawResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ unsigned int num_sigs;
+ const struct TALER_BlindedDenominationSignature *blinded_denom_sigs;
+ } ok;
+ struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostRevealWithdrawCallback instead.
+ */
typedef void
(*TALER_EXCHANGE_RevealWithdrawCallback)(
void *cls,
const struct TALER_EXCHANGE_RevealWithdrawResponse *awr);
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostRevealWithdrawHandle instead.
+ */
+struct TALER_EXCHANGE_RevealWithdrawHandle;
/**
- * Submit an reveal-withdraw request to the exchange and get the exchange's
- * response. This is required as the second step to a withdraw of age-restricted
- * coins with proof that the correct age-restriction has been applied.
- *
- * 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 rd should be committed to persistent storage
- * prior to calling this function.
- *
- * @param curl_ctx The curl context
- * @param exchange_url The base url of the exchange
- * @param num_coins Number of coin signatures to expect from the reveal
- * @param h_planchets The commitment from the previous call to withdraw
- * @param seeds TALER_CNC_KAPPA-1 tuple of seeds to reveal
- * @param res_cb A callback for the result, maybe NULL
- * @param res_cb_cls A closure for @e res_cb, maybe NULL
- * @return a handle for this request; NULL if the argument was invalid.
- * In this case, the callback will not be called.
+ * @deprecated Use #TALER_EXCHANGE_post_reveal_withdraw_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_RevealWithdrawHandle *
TALER_EXCHANGE_reveal_withdraw (
@@ -110,14 +198,12 @@ TALER_EXCHANGE_reveal_withdraw (
TALER_EXCHANGE_RevealWithdrawCallback res_cb,
void *res_cb_cls);
-
/**
- * @brief Cancel an reveal-withdraw request
- *
- * @param awrh Handle to an withdraw-reqveal request
+ * @deprecated Use #TALER_EXCHANGE_post_reveal_withdraw_cancel() instead.
*/
void
TALER_EXCHANGE_reveal_withdraw_cancel (
struct TALER_EXCHANGE_RevealWithdrawHandle *awrh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_REVEAL_WITHDRAW_H */
diff --git a/src/include/taler/taler-exchange/post-withdraw.h b/src/include/taler/taler-exchange/post-withdraw.h
@@ -1,17 +1,17 @@
/*
- This file is part of TALER
- Copyright (C) 2014-2025 Taler Systems SA
+ 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 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.
+ 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/>
+ 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/taler-exchange/post-withdraw.h
@@ -23,7 +23,6 @@
#include <taler/taler-exchange/common.h>
-/* ********************* /withdraw *************** */
/**
* All the details about a coin that are generated during withdrawal and
@@ -88,15 +87,136 @@ struct TALER_EXCHANGE_WithdrawCoinPrivateDetails
};
+
/**
- * @brief A handle to a /withdraw request
+ * Details from an #MHD_HTTP_CREATED response to POST /withdraw,
+ * indicating age-restricted withdrawal requiring a /reveal-withdraw step.
*/
-struct TALER_EXCHANGE_WithdrawHandle;
+struct TALER_EXCHANGE_WithdrawCreated
+{
+ /**
+ * Index that should not be revealed during the reveal-withdraw
+ * phase.
+ */
+ uint8_t noreveal_index;
+
+ /**
+ * The commitment of the withdraw request, needed for the
+ * subsequent call to /reveal-withdraw and later calls to /recoup
+ */
+ struct TALER_HashBlindedPlanchetsP planchets_h;
+
+ /**
+ * The hash of the selected batch of blinded coin envelopes.
+ */
+ struct TALER_HashBlindedPlanchetsP selected_h;
+
+ /**
+ * The number of elements in @e coins, each referring to
+ * TALER_CNC_KAPPA elements
+ */
+ size_t num_coins;
+
+ /**
+ * The computed details of the non-revealed @e num_coins coins to keep.
+ */
+ const struct TALER_EXCHANGE_WithdrawCoinPrivateDetails *coin_details;
+
+ /**
+ * Key used by the exchange to sign the response.
+ */
+ struct TALER_ExchangePublicKeyP exchange_pub;
+
+ /**
+ * The #TALER_CNC_KAPPA seeds that were used per batch of coin candidates
+ */
+ struct TALER_KappaWithdrawMasterSeedP kappa_seed;
+
+};
+
+
+/* *** High-level withdraw (with automatic blinding) *** */
+
/**
- * @brief Details about the response for a withdraw request
+ * Handle for an operation to POST /withdraw (high-level variant).
*/
-struct TALER_EXCHANGE_WithdrawResponse
+struct TALER_EXCHANGE_PostWithdrawHandle;
+
+
+/**
+ * Set up POST /withdraw operation (high-level variant, with automatic
+ * blinding/unblinding).
+ * 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
+ * arguments should be committed to persistent storage
+ * prior to calling this function.
+ *
+ * Note that a client can opaquely set a maximum age on the coins
+ * (if the denominations do support it), that remains opaque to the exchange.
+ * Only when the corresponding reserve has a birthday associated with it, the
+ * exchange might require a _proof_ for the correct age-restriction to be set.
+ * In that case, the exchange will respond with 409 and the client will need
+ * to call TALER_EXCHANGE_post_withdraw_create_with_age_proof() instead.
+ *
+ * @param curl_ctx The curl context
+ * @param exchange_url The base url of the exchange
+ * @param keys The denomination keys from the exchange
+ * @param reserve_priv The private key to the reserve
+ * @param num_coins Number of coins to withdraw in a batch
+ * @param denoms_pub Array of @e num_coins of denominations of the coins to withdraw
+ * @param seed seed from which @e num_coins secrets for each coin are derived from
+ * @param opaque_max_age The age to commit to opaquely; if not zero, the denominations MUST support age restriction
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostWithdrawHandle *
+TALER_EXCHANGE_post_withdraw_create (
+ struct GNUNET_CURL_Context *curl_ctx,
+ const char *exchange_url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_ReservePrivateKeyP *reserve_priv,
+ size_t num_coins,
+ const struct TALER_EXCHANGE_DenomPublicKey denoms_pub[static num_coins],
+ const struct TALER_WithdrawMasterSeedP *seed,
+ uint8_t opaque_max_age);
+
+
+/**
+ * Set up POST /withdraw operation for age-restricted coins with age proof
+ * (high-level variant, with automatic blinding/unblinding).
+ * Note that you must explicitly start the operation after setup.
+ *
+ * This variant requires an additional protocol step /reveal-withdraw to proof
+ * that the age-restriction is correctly set by the client.
+ *
+ * @param curl_ctx The curl context
+ * @param exchange_url The base url of the exchange
+ * @param keys The denomination keys from the exchange
+ * @param reserve_priv The private key to the reserve
+ * @param num_coins Number of coins to withdraw in a batch
+ * @param denoms_pub Array of @e num_coins denominations, MUST support age restriction
+ * @param seed seed from which all @e num_coins coin candidates and other secrets are derived from
+ * @param max_age maximum age to (provably) commit to
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostWithdrawHandle *
+TALER_EXCHANGE_post_withdraw_create_with_age_proof (
+ struct GNUNET_CURL_Context *curl_ctx,
+ const char *exchange_url,
+ struct TALER_EXCHANGE_Keys *keys,
+ const struct TALER_ReservePrivateKeyP *reserve_priv,
+ size_t num_coins,
+ const struct TALER_EXCHANGE_DenomPublicKey denoms_pub[static num_coins],
+ const struct TALER_WithdrawMasterSeedP *seed,
+ uint8_t max_age);
+
+
+/**
+ * Response from a POST /withdraw request (high-level variant).
+ */
+struct TALER_EXCHANGE_PostWithdrawResponse
{
/**
* HTTP response data.
@@ -108,7 +228,6 @@ struct TALER_EXCHANGE_WithdrawResponse
*/
union
{
-
/**
* Details if the status is #MHD_HTTP_OK
*/
@@ -120,7 +239,7 @@ struct TALER_EXCHANGE_WithdrawResponse
unsigned int num_sigs;
/**
- * The computed details of the@e num_coins coins to keep,
+ * The computed details of the @e num_sigs coins to keep,
* including the denomination-signatures in their @e .denom_sig field.
*/
const struct TALER_EXCHANGE_WithdrawCoinPrivateDetails *coin_details;
@@ -137,47 +256,215 @@ struct TALER_EXCHANGE_WithdrawResponse
* age-restriction. The response is input to prepare the required
* follow-up call to /reveal-withdraw.
*/
- struct TALER_EXCHANGE_WithdrawCreated
- {
- /**
- * Index that should not be revealed during the reveal-withdraw
- * phase.
- */
- uint8_t noreveal_index;
+ struct TALER_EXCHANGE_WithdrawCreated created;
- /**
- * The commitment of the withdraw request, needed for the
- * subsequent call to /reveal-withdraw and later calls to /recoup
- */
- struct TALER_HashBlindedPlanchetsP planchets_h;
+ /**
+ * Details if the status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS.
+ */
+ struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
- /**
- * The hash of the selected batch of blinded coin envelopes.
- */
- struct TALER_HashBlindedPlanchetsP selected_h;
+ } details;
+};
- /**
- * The number of elements in @e coins, each referring to
- * TALER_CNC_KAPPA elements
- */
- size_t num_coins;
+#ifndef TALER_EXCHANGE_POST_WITHDRAW_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostWithdrawCallback.
+ */
+#define TALER_EXCHANGE_POST_WITHDRAW_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_WITHDRAW_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /withdraw request (high-level variant).
+ *
+ * @param cls closure
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostWithdrawCallback)(
+ TALER_EXCHANGE_POST_WITHDRAW_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostWithdrawResponse *result);
+
+
+/**
+ * Start POST /withdraw operation (high-level variant).
+ *
+ * @param[in,out] pwh 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_withdraw_start (
+ struct TALER_EXCHANGE_PostWithdrawHandle *pwh,
+ TALER_EXCHANGE_PostWithdrawCallback cb,
+ TALER_EXCHANGE_POST_WITHDRAW_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /withdraw operation (high-level variant). This function must
+ * not be called by clients after the TALER_EXCHANGE_PostWithdrawCallback has
+ * been invoked (as in those cases it'll be called internally by the
+ * implementation already).
+ *
+ * @param[in] pwh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_withdraw_cancel (
+ struct TALER_EXCHANGE_PostWithdrawHandle *pwh);
+
+
+/* *** Low-level withdraw (with pre-blinded planchets) *** */
+
+
+/**
+ * @brief Information needed to withdraw coins (low-level, pre-blinded).
+ */
+struct TALER_EXCHANGE_WithdrawBlindedCoinInput
+{
+ /**
+ * The denomination of the coin.
+ */
+ const struct TALER_EXCHANGE_DenomPublicKey *denom_pub;
+
+ /**
+ * Blinded planchet for a single coin.
+ */
+ struct TALER_PlanchetDetail planchet_details;
+};
+
+/**
+ * @brief Information needed to withdraw age-restricted coins (low-level, pre-blinded).
+ */
+struct TALER_EXCHANGE_WithdrawBlindedAgeRestrictedCoinInput
+{
+ /**
+ * The denomination of the coin. MUST support age restriction.
+ */
+ const struct TALER_EXCHANGE_DenomPublicKey *denom_pub;
+
+ /**
+ * Tuple of length kappa of planchet candidates for a single coin.
+ */
+ struct TALER_PlanchetDetail planchet_details[TALER_CNC_KAPPA];
+};
+
+
+/**
+ * Handle for an operation to POST /withdraw (low-level, pre-blinded variant).
+ */
+struct TALER_EXCHANGE_PostWithdrawBlindedHandle;
+
+
+/**
+ * Set up POST /withdraw operation for non-age-restricted coins
+ * (low-level variant with pre-blinded planchets).
+ * Note that you must explicitly start the operation after setup.
+ *
+ * This variant does not do the blinding/unblinding and only
+ * fetches the blind signatures on the already blinded planchets.
+ *
+ * @param curl_ctx The curl context to use
+ * @param keys The /keys material from the exchange
+ * @param exchange_url The base-URL of the exchange
+ * @param reserve_priv private key of the reserve to withdraw from
+ * @param blinding_seed seed used for blinding of CS denominations, might be NULL
+ * @param num_input number of entries in the @a blinded_input array
+ * @param blinded_input array of planchet details to withdraw
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostWithdrawBlindedHandle *
+TALER_EXCHANGE_post_withdraw_blinded_create (
+ struct GNUNET_CURL_Context *curl_ctx,
+ struct TALER_EXCHANGE_Keys *keys,
+ const char *exchange_url,
+ const struct TALER_ReservePrivateKeyP *reserve_priv,
+ const struct TALER_BlindingMasterSeedP *blinding_seed,
+ size_t num_input,
+ const struct TALER_EXCHANGE_WithdrawBlindedCoinInput
+ blinded_input[static num_input]);
+
+
+/**
+ * Set up POST /withdraw operation for age-restricted coins
+ * (low-level variant with pre-blinded planchets).
+ * Note that you must explicitly start the operation after setup.
+ *
+ * Withdrawing age-restricted coins with age-proof requires an additional
+ * step, /reveal-withdraw, for which the wallet will need to provide
+ * to all but one index all of the coin secrets.
+ *
+ * @param curl_ctx The curl context to use
+ * @param keys The /keys material from the exchange
+ * @param exchange_url The base-URL of the exchange
+ * @param reserve_priv private key of the reserve to withdraw from
+ * @param blinding_seed seed used for blinding of CS denominations, might be NULL
+ * @param max_age the maximum age to commit to
+ * @param num_coins number of entries in the @a blinded_input array
+ * @param blinded_input array of planchet candidates to withdraw
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostWithdrawBlindedHandle *
+TALER_EXCHANGE_post_withdraw_blinded_create_with_age_proof (
+ struct GNUNET_CURL_Context *curl_ctx,
+ struct TALER_EXCHANGE_Keys *keys,
+ const char *exchange_url,
+ const struct TALER_ReservePrivateKeyP *reserve_priv,
+ const struct TALER_BlindingMasterSeedP *blinding_seed,
+ uint8_t max_age,
+ unsigned int num_coins,
+ const struct TALER_EXCHANGE_WithdrawBlindedAgeRestrictedCoinInput
+ blinded_input[static num_coins]);
+
+
+/**
+ * Response from a POST /withdraw request (low-level, pre-blinded variant).
+ */
+struct TALER_EXCHANGE_PostWithdrawBlindedResponse
+{
+ /**
+ * HTTP response data.
+ */
+ struct TALER_EXCHANGE_HttpResponse hr;
+
+ /**
+ * Details about the response
+ */
+ union
+ {
+ /**
+ * Details if the status is #MHD_HTTP_OK
+ */
+ struct
+ {
/**
- * The computed details of the non-revealed @e num_coins coins to keep.
+ * Number of signatures returned.
*/
- const struct TALER_EXCHANGE_WithdrawCoinPrivateDetails *coin_details;
+ unsigned int num_sigs;
/**
- * Key used by the exchange to sign the response.
+ * Array of @e num_sigs blinded denomination signatures, giving each
+ * coin its value and validity. The array gives these coins in the same
+ * order (and should have the same length) in which the original
+ * withdraw request specified the respective denomination keys.
*/
- struct TALER_ExchangePublicKeyP exchange_pub;
+ const struct TALER_BlindedDenominationSignature *blinded_denom_sigs;
/**
- * The #TALER_CNC_KAPPA seeds that were used per batch of coin candidates
+ * The commitment of the withdraw request, needed for the later calls to /recoup
*/
- struct TALER_KappaWithdrawMasterSeedP kappa_seed;
+ struct TALER_HashBlindedPlanchetsP planchets_h;
- } created;
+ } ok;
+
+ /**
+ * Details if the status is MHD_HTTP_CREATED, i.e. in case of
+ * age-restriction. The response is input to prepare the required
+ * follow-up call to /reveal-withdraw.
+ */
+ struct TALER_EXCHANGE_WithdrawCreated created;
/**
* Details if the status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS.
@@ -188,39 +475,93 @@ struct TALER_EXCHANGE_WithdrawResponse
};
+#ifndef TALER_EXCHANGE_POST_WITHDRAW_BLINDED_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostWithdrawBlindedCallback.
+ */
+#define TALER_EXCHANGE_POST_WITHDRAW_BLINDED_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_WITHDRAW_BLINDED_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /withdraw request (low-level, pre-blinded variant).
+ *
+ * @param cls closure
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostWithdrawBlindedCallback)(
+ TALER_EXCHANGE_POST_WITHDRAW_BLINDED_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostWithdrawBlindedResponse *result);
+
+
+/**
+ * Start POST /withdraw operation (low-level, pre-blinded variant).
+ *
+ * @param[in,out] pwbh 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_withdraw_blinded_start (
+ struct TALER_EXCHANGE_PostWithdrawBlindedHandle *pwbh,
+ TALER_EXCHANGE_PostWithdrawBlindedCallback cb,
+ TALER_EXCHANGE_POST_WITHDRAW_BLINDED_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /withdraw operation (low-level, pre-blinded variant). This
+ * function must not be called by clients after the
+ * TALER_EXCHANGE_PostWithdrawBlindedCallback has been invoked (as in those
+ * cases it'll be called internally by the implementation already).
+ *
+ * @param[in] pwbh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_withdraw_blinded_cancel (
+ struct TALER_EXCHANGE_PostWithdrawBlindedHandle *pwbh);
+
+
+/* **************** deprecated legacy API ***************** */
+
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostWithdrawResponse instead.
+ */
+struct TALER_EXCHANGE_WithdrawResponse
+{
+ struct TALER_EXCHANGE_HttpResponse hr;
+ union
+ {
+ struct
+ {
+ unsigned int num_sigs;
+ const struct TALER_EXCHANGE_WithdrawCoinPrivateDetails *coin_details;
+ struct TALER_HashBlindedPlanchetsP planchets_h;
+ } ok;
+ struct TALER_EXCHANGE_WithdrawCreated created;
+ struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
+ } details;
+};
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_PostWithdrawCallback instead.
+ */
typedef void
(*TALER_EXCHANGE_WithdrawCallback)(
void *cls,
const struct TALER_EXCHANGE_WithdrawResponse *awr);
/**
- * Submit an withdraw request to the exchange and get the exchange's
- * response. The coin's planchet secrets are derived from a single seed.
- *
- * Note that a client can opaquely set a maximum age on the coins
- * (if the denominations do support it), that remains opaque to the exchange.
- * Only when the corresponding reserve has a birthday associated with it, the
- * exchange might require a _proof_ for the correct age-restriction to be set.
- * In that case, the exchange will respond with 409 and the client will need
- * to call TALER_EXCHANGE_withdraw_with_age_proof instead.
- *
- * 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 rd should be committed to persistent storage
- * prior to calling this function.
- *
- * @param curl_ctx The curl context
- * @param exchange_url The base url of the exchange
- * @param keys The denomination keys from the exchange
- * @param reserve_priv The private key to the reserve
- * @param num_coins Number of coins to withdraw in a batch
- * @param denoms_pub Array of @e num_coins of denominations of the coins to withdraw
- * @param seed seed from which @e num_coins secrets for each coin are derived from
- * @param opaque_max_age The age to commit to opaquely. If not zero, the denominations MUST support age restriction.
- * @param callback A callback for the result, maybe NULL
- * @param callback_cls A closure for @e res_cb, maybe NULL
- * @return a handle for this request; NULL if the argument was invalid.
- * In this case, the callback will not be called.
+ * @deprecated Use #TALER_EXCHANGE_PostWithdrawHandle instead.
+ */
+struct TALER_EXCHANGE_WithdrawHandle;
+
+/**
+ * @deprecated Use #TALER_EXCHANGE_post_withdraw_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_WithdrawHandle *
TALER_EXCHANGE_withdraw (
@@ -235,31 +576,9 @@ TALER_EXCHANGE_withdraw (
TALER_EXCHANGE_WithdrawCallback callback,
void *callback_cls);
-
/**
- * Submit an withdraw request for age-restricted coins
- * to the exchange and get the exchange's response.
- * Note that this variant of withdraw requires an additional
- * protocol step, /reval-withdraw, to proof that the age-restriction
- * is correctly set by the client.
- *
- * 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 rd should be committed to persistent storage
- * prior to calling this function.
- *
- * @param curl_ctx The curl context
- * @param exchange_url The base url of the exchange
- * @param keys The denomination keys from the exchange
- * @param reserve_priv The private key to the reserve
- * @param num_coins Number of coins to withdraw in a batch
- * @param denoms_pub Array of @e num_coins of denominations of the coins to withdraw, MUST support age restriction
- * @param seed seed from which all @e num_coins coin candidates and other secrets are derived from
- * @param max_age maximum age to (provably) commit to
- * @param callback A callback for the result, maybe NULL
- * @param callback_cls A closure for @e res_cb, maybe NULL
- * @return a handle for this request; NULL if the argument was invalid.
- * In this case, the callback will not be called.
+ * @deprecated Use #TALER_EXCHANGE_post_withdraw_create_with_age_proof() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_WithdrawHandle *
TALER_EXCHANGE_withdraw_with_age_proof (
@@ -274,12 +593,8 @@ TALER_EXCHANGE_withdraw_with_age_proof (
TALER_EXCHANGE_WithdrawCallback callback,
void *callback_cls);
-
/**
- * Cancel a withdraw request. This function cannot be used
- * on a request handle if a response is already served for it.
- *
- * @param awh the withdraw handle
+ * @deprecated Use #TALER_EXCHANGE_post_withdraw_cancel() instead.
*/
void
TALER_EXCHANGE_withdraw_cancel (
@@ -329,150 +644,42 @@ TALER_EXCHANGE_withdraw_with_age_proof_extra_blinding_seed (
#endif
-/**++++++ withdraw with pre-blinded planchets ***************************/
-
/**
- * @brief A handle to a /withdraw request with pre-blinded coins
- */
-struct TALER_EXCHANGE_WithdrawBlindedHandle;
-
-/**
- * @brief Details about the response for a withdraw request
+ * @deprecated Use #TALER_EXCHANGE_PostWithdrawBlindedResponse instead.
*/
struct TALER_EXCHANGE_WithdrawBlindedResponse
{
- /**
- * HTTP response data.
- */
struct TALER_EXCHANGE_HttpResponse hr;
-
- /**
- * Details about the response
- */
union
{
-
- /**
- * Details if the status is #MHD_HTTP_OK
- */
struct
{
- /**
- * Number of signatures returned.
- */
unsigned int num_sigs;
-
- /**
- * Array of @e num_coins blinded denomination signatures, giving each
- * coin its value and validity. The array give these coins in the same
- * order (and should have the same length) in which the original
- * withdraw request specified the respective denomination keys.
- */
const struct TALER_BlindedDenominationSignature *blinded_denom_sigs;
-
- /**
- * The commitment of the withdraw request, needed for the later calls to /recoup
- */
struct TALER_HashBlindedPlanchetsP planchets_h;
-
} ok;
-
- /**
- * Details if the status is MHD_HTTP_CREATED, i.e. in case of
- * age-restriction. The response is input to prepare the required
- * follow-up call to /reveal-withdraw.
- */
struct TALER_EXCHANGE_WithdrawCreated created;
-
- /**
- * Details if the status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS.
- */
struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons;
-
} details;
};
/**
- * @brief Information needed to withdraw coins.
- */
-struct TALER_EXCHANGE_WithdrawBlindedCoinInput
-{
- /**
- * The denomination of the coin.
- */
- const struct TALER_EXCHANGE_DenomPublicKey *denom_pub;
-
- /**
- * Blinded planchet for a single coin.
- */
- struct TALER_PlanchetDetail planchet_details;
-};
-
-/**
- * @brief Information needed to withdraw (and potentially reveal age-restriced) coins.
- */
-struct TALER_EXCHANGE_WithdrawBlindedAgeRestrictedCoinInput
-{
- /**
- * The denomination of the coin. MUST support age restriction.
- */
- const struct TALER_EXCHANGE_DenomPublicKey *denom_pub;
-
- /**
- * Tuple of length kappa of planchet candidates for a single coin.
- */
- struct TALER_PlanchetDetail planchet_details[TALER_CNC_KAPPA];
-};
-
-/**
- * Callbacks of this type are used to serve the result of submitting an
- * withdraw request to a exchange with pre-blinded planchets
- * without the (un)blinding factor.
- *
- * @param cls closure
- * @param awbr response data
+ * @deprecated Use #TALER_EXCHANGE_PostWithdrawBlindedCallback instead.
*/
typedef void
(*TALER_EXCHANGE_WithdrawBlindedCallback) (
void *cls,
const struct TALER_EXCHANGE_WithdrawBlindedResponse *awbr);
-
/**
- * @brief A /withdraw Handle, 2nd variant with pre-blinded planchets.
- *
- * This variant does not do the blinding/unblinding and only
- * fetches the blind signatures on the already blinded planchets.
- * Used internally by the `struct TALER_EXCHANGE_WithdrawHandle`
- * implementation as well as for the reward logic of merchants.
+ * @deprecated Use #TALER_EXCHANGE_PostWithdrawBlindedHandle instead.
*/
struct TALER_EXCHANGE_WithdrawBlindedHandle;
/**
- * Withdraw coins from the exchange via a /withdraw request.
- * The coins are not age restricted.
- * This API is typically used on behalf of a wallet
- * by an intermediary who receives pre-blinded planchets
- * and the blinding factor is unknown to the intermediary.
- *
- * Note that to ensure that no money is lost in case of hardware
- * failures, the caller must have committed (most of) the arguments to
- * disk before calling, and be ready to repeat the request with the
- * same arguments in case of failures.
- *
- * @param curl_ctx The curl context to use
- * @param keys The /keys material from the exchange
- * @param exchange_url The base-URL of the exchange
- * @param reserve_priv private key of the reserve to withdraw from
- * @param blinding_seed seed used for blinding of CS denominations, might be NULL
- * @param num_input number of entries in the @a blinded_input array
- * @param blinded_input array of planchet details of the planchet to withdraw
- * @param res_cb the callback to call when the final result for this request is available
- * @param res_cb_cls closure for @a res_cb
- * @return NULL
- * if the inputs are invalid (i.e. denomination key not with this exchange).
- * In this case, the callback is not called.
+ * @deprecated Use #TALER_EXCHANGE_post_withdraw_blinded_create() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_WithdrawBlindedHandle *
TALER_EXCHANGE_withdraw_blinded (
@@ -488,30 +695,8 @@ TALER_EXCHANGE_withdraw_blinded (
void *res_cb_cls);
/**
- * Withdraw age-restricted coins from the exchange via a /withdraw request,
- * similar to @a TALER_EXCHANGE_withdraw_blinded.
- * In comparison to the unrestricted variant, this function requires a maximum
- * age parameter and the @a num_coin coin inputs contain
- * TALER_CNC_KAPPA candidates of blinded planchets.
- *
- * Note: Withdrawing age-restricted coins with age-proof requires an additional
- * step, /reveal-withdraw, for which the wallet will need to provide
- * to all but one index all of the coin secrets to the intermediary.
- *
- * @param curl_ctx The curl context to use
- * @param keys The /keys material from the exchange
- * @param exchange_url The base-URL of the exchange
- * @param reserve_priv private key of the reserve to withdraw from
- * @param blinding_seed seed used for blinding of CS denominations, might be NULL
- * @param max_age the maximum age to commit to
- * @param num_coins number of entries in the @a blinded_input array
- * @param blinded_input array of planchet details of the planchet to withdraw
- * @param res_cb the callback to call when the final result for this request is available
- * @param res_cb_cls closure for @a res_cb
- * @return NULL
- * if the inputs are invalid (i.e. denomination keys not with this exchange or
- * they do not all support age-restriction).
- * In this case, the callback is not called.
+ * @deprecated Use #TALER_EXCHANGE_post_withdraw_blinded_create_with_age_proof() and
+ * the new API instead.
*/
struct TALER_EXCHANGE_WithdrawBlindedHandle *
TALER_EXCHANGE_withdraw_blinded_with_age_proof (
@@ -527,15 +712,12 @@ TALER_EXCHANGE_withdraw_blinded_with_age_proof (
TALER_EXCHANGE_WithdrawBlindedCallback res_cb,
void *res_cb_cls);
-
/**
- * Cancel an withdraw request. This function cannot be used
- * on a request handle if a response is already served for it.
- *
- * @param awbh the withdraw handle
+ * @deprecated Use #TALER_EXCHANGE_post_withdraw_blinded_cancel() instead.
*/
void
TALER_EXCHANGE_withdraw_blinded_cancel (
struct TALER_EXCHANGE_WithdrawBlindedHandle *awbh);
-#endif
+
+#endif /* _TALER_EXCHANGE__POST_WITHDRAW_H */
diff --git a/src/include/taler/taler-exchange/reserves_get.h b/src/include/taler/taler-exchange/reserves_get.h
@@ -1,476 +0,0 @@
-/*
- This file is part of TALER
- Copyright (C) 2025 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/taler-exchange/reserves_get.h
- * @brief C interface for the GET /reserves/$RESERVE_PUB endpoint
- * @author Christian Grothoff
- */
-#ifndef _TALER_EXCHANGE__RESERVES_GET_H
-#define _TALER_EXCHANGE__RESERVES_GET_H
-
-#include <taler/taler-exchange/common.h>
-
-
-/**
- * Ways how a reserve's balance may change.
- */
-enum TALER_EXCHANGE_ReserveTransactionType
-{
-
- /**
- * Deposit into the reserve.
- */
- TALER_EXCHANGE_RTT_CREDIT,
-
- /**
- * Withdrawal from the reserve.
- */
- TALER_EXCHANGE_RTT_WITHDRAWAL,
-
- /**
- * /recoup operation.
- */
- TALER_EXCHANGE_RTT_RECOUP,
-
- /**
- * Reserve closed operation.
- */
- TALER_EXCHANGE_RTT_CLOSING,
-
- /**
- * Reserve purse merge operation.
- */
- TALER_EXCHANGE_RTT_MERGE,
-
- /**
- * Reserve open request operation.
- */
- TALER_EXCHANGE_RTT_OPEN,
-
- /**
- * Reserve close request operation.
- */
- TALER_EXCHANGE_RTT_CLOSE
-
-};
-
-
-/**
- * @brief Entry in the reserve's transaction history.
- */
-struct TALER_EXCHANGE_ReserveHistoryEntry
-{
-
- /**
- * Type of the transaction.
- */
- enum TALER_EXCHANGE_ReserveTransactionType type;
-
- /**
- * Amount transferred (in or out).
- */
- struct TALER_Amount amount;
-
- /**
- * Details depending on @e type.
- */
- union
- {
-
- /**
- * Information about a deposit that filled this reserve.
- * @e type is #TALER_EXCHANGE_RTT_CREDIT.
- */
- struct
- {
- /**
- * Sender account payto://-URL of the incoming transfer.
- */
- struct TALER_FullPayto sender_url;
-
- /**
- * Information that uniquely identifies the wire transfer.
- */
- uint64_t wire_reference;
-
- /**
- * When did the wire transfer happen?
- */
- struct GNUNET_TIME_Timestamp timestamp;
-
- } in_details;
-
- /**
- * Information about withdraw operation with age-restriction.
- * @e type is #TALER_EXCHANGE_RTT_WITHDRAWAL.
- */
- struct
- {
- /**
- * Signature authorizing the withdrawal for outgoing transaction.
- */
- json_t *out_authorization_sig;
-
- /**
- * The running hash over all hashes of blinded planchets of the withrdawal
- */
- struct TALER_HashBlindedPlanchetsP planchets_h;
-
- /**
- * If age restriction was required during the protocol
- */
- bool age_restricted;
-
- /**
- * Maximum age committed, if age_restricted is true
- */
- uint8_t max_age;
-
- /**
- * If @e age_restricted is true, the index that is not to be revealed
- * after the initial commitment in /withdraw
- */
- uint8_t noreveal_index;
-
- /**
- * If @e age_restricted is true, the hash of the selected blinded planchets
- */
- struct TALER_HashBlindedPlanchetsP selected_h;
-
- /**
- * True, if no blinding_seed was provided. The value of
- * @e blinding_seed is then zero.
- */
- bool no_blinding_seed;
-
- /**
- * In case of denominations of cipher type Clause-Schnorr, the
- * seed for the prior call to /blinding-prepare
- */
- struct TALER_BlindingMasterSeedP blinding_seed;
-
- /**
- * Fee that was charged for the withdrawal.
- */
- struct TALER_Amount fee;
-
- /**
- * Number of coins withdrawn
- */
- uint16_t num_coins;
-
- } withdraw;
-
- /**
- * Information provided if the reserve was filled via /recoup.
- * @e type is #TALER_EXCHANGE_RTT_RECOUP.
- */
- struct
- {
-
- /**
- * Public key of the coin that was paid back.
- */
- struct TALER_CoinSpendPublicKeyP coin_pub;
-
- /**
- * Signature of the coin of type
- * #TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP.
- */
- struct TALER_ExchangeSignatureP exchange_sig;
-
- /**
- * Public key of the exchange that was used for @e exchange_sig.
- */
- struct TALER_ExchangePublicKeyP exchange_pub;
-
- /**
- * When did the /recoup operation happen?
- */
- struct GNUNET_TIME_Timestamp timestamp;
-
- } recoup_details;
-
- /**
- * Information about a close operation of the reserve.
- * @e type is #TALER_EXCHANGE_RTT_CLOSE.
- */
- struct
- {
- /**
- * Receiver account information for the outgoing wire transfer as a payto://-URI.
- */
- struct TALER_FullPayto receiver_account_details;
-
- /**
- * Wire transfer details for the outgoing wire transfer.
- */
- struct TALER_WireTransferIdentifierRawP wtid;
-
- /**
- * Signature of the coin of type
- * #TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED.
- */
- struct TALER_ExchangeSignatureP exchange_sig;
-
- /**
- * Public key of the exchange that was used for @e exchange_sig.
- */
- struct TALER_ExchangePublicKeyP exchange_pub;
-
- /**
- * When did the wire transfer happen?
- */
- struct GNUNET_TIME_Timestamp timestamp;
-
- /**
- * Fee that was charged for the closing.
- */
- struct TALER_Amount fee;
-
- } close_details;
-
- /**
- * Information about a merge operation on the reserve.
- * @e type is #TALER_EXCHANGE_RTT_MERGE.
- */
- struct
- {
-
- /**
- * Fee paid for the purse.
- */
- struct TALER_Amount purse_fee;
-
- /**
- * Hash over the contract.
- */
- struct TALER_PrivateContractHashP h_contract_terms;
-
- /**
- * Merge capability key.
- */
- struct TALER_PurseMergePublicKeyP merge_pub;
-
- /**
- * Purse public key.
- */
- struct TALER_PurseContractPublicKeyP purse_pub;
-
- /**
- * Signature by the reserve approving the merge.
- */
- struct TALER_ReserveSignatureP reserve_sig;
-
- /**
- * When was the merge made.
- */
- struct GNUNET_TIME_Timestamp merge_timestamp;
-
- /**
- * When was the purse set to expire.
- */
- struct GNUNET_TIME_Timestamp purse_expiration;
-
- /**
- * Minimum age required for depositing into the purse.
- */
- uint32_t min_age;
-
- /**
- * Flags of the purse.
- */
- enum TALER_WalletAccountMergeFlags flags;
-
- /**
- * True if the purse was actually merged, false
- * if only the @e purse_fee was charged.
- */
- bool merged;
-
- } merge_details;
-
- /**
- * Information about an open request operation on the reserve.
- * @e type is #TALER_EXCHANGE_RTT_OPEN.
- */
- struct
- {
-
- /**
- * Signature by the reserve approving the open.
- */
- struct TALER_ReserveSignatureP reserve_sig;
-
- /**
- * Amount to be paid from the reserve balance to open
- * the reserve.
- */
- struct TALER_Amount reserve_payment;
-
- /**
- * When was the request created.
- */
- struct GNUNET_TIME_Timestamp request_timestamp;
-
- /**
- * For how long should the reserve be kept open.
- * (Determines amount to be paid.)
- */
- struct GNUNET_TIME_Timestamp reserve_expiration;
-
- /**
- * How many open purses should be included with the
- * open reserve?
- * (Determines amount to be paid.)
- */
- uint32_t purse_limit;
-
- } open_request;
-
- /**
- * Information about an close request operation on the reserve.
- * @e type is #TALER_EXCHANGE_RTT_CLOSE.
- */
- struct
- {
-
- /**
- * Signature by the reserve approving the close.
- */
- struct TALER_ReserveSignatureP reserve_sig;
-
- /**
- * When was the request created.
- */
- struct GNUNET_TIME_Timestamp request_timestamp;
-
- /**
- * Hash of the payto://-URI of the target account
- * for the closure, or all zeros for the reserve
- * origin account.
- */
- struct TALER_FullPaytoHashP target_account_h_payto;
-
- } close_request;
-
-
- } details;
-
-};
-
-
-/**
- * @brief A /reserves/ GET Handle
- */
-struct TALER_EXCHANGE_ReservesGetHandle;
-
-
-/**
- * @brief Reserve summary.
- */
-struct TALER_EXCHANGE_ReserveSummary
-{
-
- /**
- * High-level HTTP response details.
- */
- struct TALER_EXCHANGE_HttpResponse hr;
-
- /**
- * Details depending on @e hr.http_status.
- */
- union
- {
-
- /**
- * Information returned on success, if
- * @e hr.http_status is #MHD_HTTP_OK
- */
- struct
- {
-
- /**
- * Reserve balance.
- */
- struct TALER_Amount balance;
-
- /**
- * payto://-URI of the last bank account that wired funds
- * to the reserve, NULL for none (can happen if reserve
- * was funded via P2P merge).
- */
- struct TALER_FullPayto last_origin;
- } ok;
-
- } details;
-
-};
-
-
-/**
- * Callbacks of this type are used to serve the result of submitting a
- * reserve status request to a exchange.
- *
- * @param cls closure
- * @param rs HTTP response data
- */
-typedef void
-(*TALER_EXCHANGE_ReservesGetCallback) (
- void *cls,
- const struct TALER_EXCHANGE_ReserveSummary *rs);
-
-
-/**
- * Submit a request to obtain the transaction history of a reserve
- * from the exchange. Note that while we return the full response to the
- * caller for further processing, we do already verify that the
- * response is well-formed (i.e. that signatures included in the
- * response are all valid and add up to the balance). If the exchange's
- * reply is not well-formed, we return an HTTP status code of zero to
- * @a cb.
- *
- * @param ctx curl context
- * @param url exchange base URL
- * @param reserve_pub public key of the reserve to inspect
- * @param timeout how long to wait for an affirmative reply
- * (enables long polling if the reserve does not yet exist)
- * @param cb the callback to call when a reply for this request is available
- * @param cb_cls closure for the above callback
- * @return a handle for this request; NULL if the inputs are invalid (i.e.
- * signatures fail to verify). In this case, the callback is not called.
- */
-struct TALER_EXCHANGE_ReservesGetHandle *
-TALER_EXCHANGE_reserves_get (
- struct GNUNET_CURL_Context *ctx,
- const char *url,
- const struct TALER_ReservePublicKeyP *reserve_pub,
- struct GNUNET_TIME_Relative timeout,
- TALER_EXCHANGE_ReservesGetCallback cb,
- void *cb_cls);
-
-
-/**
- * Cancel a reserve GET request. This function cannot be used
- * on a request handle if a response is already served for it.
- *
- * @param rgh the reserve request handle
- */
-void
-TALER_EXCHANGE_reserves_get_cancel (
- struct TALER_EXCHANGE_ReservesGetHandle *rgh);
-
-#endif
diff --git a/src/include/taler/taler_exchange_service.h b/src/include/taler/taler_exchange_service.h
@@ -29,7 +29,7 @@
* Version of the Taler Exchange API, in hex.
* Thus 0.8.4-1 = 0x00080401.
*/
-#define TALER_EXCHANGE_API_VERSION 0x00100007
+#define TALER_EXCHANGE_API_VERSION 0x00105000
#include <taler/taler-exchange/common.h>
#include <taler/taler-exchange/get-keys.h>
diff --git a/src/lib/exchange_api_aml_legitimizations_get.c b/src/lib/exchange_api_aml_legitimizations_get.c
@@ -35,7 +35,7 @@
/**
* Handle for an operation to GET /aml/$OFFICER_PUB/legitimizations.
*/
-struct TALER_EXCHANGE_AmlLegitimizationsGetHandle
+struct TALER_EXCHANGE_GetAmlLegitimizationsHandle
{
/**
@@ -66,12 +66,12 @@ struct TALER_EXCHANGE_AmlLegitimizationsGetHandle
/**
* Function to call with the result.
*/
- TALER_EXCHANGE_AmlLegitimizationsGetCallback cb;
+ TALER_EXCHANGE_GetAmlLegitimizationsCallback cb;
/**
* Closure for @a cb.
*/
- TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE *cb_cls;
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_RESULT_CLOSURE *cb_cls;
/**
* The url for this request.
@@ -123,7 +123,7 @@ struct TALER_EXCHANGE_AmlLegitimizationsGetHandle
static enum GNUNET_GenericReturnValue
parse_measure_details (
const json_t *md_json,
- struct TALER_EXCHANGE_AmlLegitimizationsGetMeasureDetails *md)
+ struct TALER_EXCHANGE_GetAmlLegitimizationsMeasureDetails *md)
{
struct GNUNET_JSON_Specification spec[] = {
GNUNET_JSON_spec_fixed_auto ("h_payto",
@@ -162,10 +162,10 @@ parse_measure_details (
*/
static enum GNUNET_GenericReturnValue
handle_aml_legitimizations_get_ok (
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh,
+ struct TALER_EXCHANGE_GetAmlLegitimizationsHandle *algh,
const json_t *j)
{
- struct TALER_EXCHANGE_AmlLegitimizationsGetResult result = {
+ struct TALER_EXCHANGE_GetAmlLegitimizationsResponse result = {
.hr.reply = j,
.hr.http_status = MHD_HTTP_OK
};
@@ -175,7 +175,7 @@ handle_aml_legitimizations_get_ok (
&measures_array),
GNUNET_JSON_spec_end ()
};
- struct TALER_EXCHANGE_AmlLegitimizationsGetMeasureDetails *measures;
+ struct TALER_EXCHANGE_GetAmlLegitimizationsMeasureDetails *measures;
if (GNUNET_OK !=
GNUNET_JSON_parse (j,
@@ -197,7 +197,7 @@ handle_aml_legitimizations_get_ok (
measures
= GNUNET_new_array (
result.details.ok.measures_length,
- struct TALER_EXCHANGE_AmlLegitimizationsGetMeasureDetails);
+ struct TALER_EXCHANGE_GetAmlLegitimizationsMeasureDetails);
}
for (size_t i = 0; i < result.details.ok.measures_length; i++)
{
@@ -225,7 +225,7 @@ handle_aml_legitimizations_get_ok (
* Function called when we're done processing the
* HTTP /aml/$OFFICER_PUB/legitimizations GET request.
*
- * @param cls the `struct TALER_EXCHANGE_AmlLegitimizationsGetHandle`
+ * @param cls the `struct TALER_EXCHANGE_GetAmlLegitimizationsHandle`
* @param response_code HTTP response code, 0 on error
* @param response parsed JSON result, NULL on error
*/
@@ -234,9 +234,9 @@ handle_aml_legitimizations_get_finished (void *cls,
long response_code,
const void *response)
{
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh = cls;
+ struct TALER_EXCHANGE_GetAmlLegitimizationsHandle *algh = cls;
const json_t *j = response;
- struct TALER_EXCHANGE_AmlLegitimizationsGetResult result = {
+ struct TALER_EXCHANGE_GetAmlLegitimizationsResponse result = {
.hr.reply = j,
.hr.http_status = (unsigned int) response_code
};
@@ -304,19 +304,19 @@ handle_aml_legitimizations_get_finished (void *cls,
&result);
algh->cb = NULL;
}
- TALER_EXCHANGE_aml_legitimizations_get_cancel (algh);
+ TALER_EXCHANGE_get_aml_legitimizations_cancel (algh);
}
-struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *
-TALER_EXCHANGE_aml_legitimizations_get_create (
+struct TALER_EXCHANGE_GetAmlLegitimizationsHandle *
+TALER_EXCHANGE_get_aml_legitimizations_create (
struct GNUNET_CURL_Context *ctx,
const char *exchange_base_url,
const struct TALER_AmlOfficerPrivateKeyP *officer_priv)
{
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh;
+ struct TALER_EXCHANGE_GetAmlLegitimizationsHandle *algh;
- algh = GNUNET_new (struct TALER_EXCHANGE_AmlLegitimizationsGetHandle);
+ algh = GNUNET_new (struct TALER_EXCHANGE_GetAmlLegitimizationsHandle);
algh->ctx = ctx;
algh->exchange_base_url = GNUNET_strdup (exchange_base_url);
GNUNET_CRYPTO_eddsa_key_get_public (&officer_priv->eddsa_priv,
@@ -331,27 +331,27 @@ TALER_EXCHANGE_aml_legitimizations_get_create (
enum GNUNET_GenericReturnValue
-TALER_EXCHANGE_aml_legitimizations_get_set_options_ (
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh,
+TALER_EXCHANGE_get_aml_legitimizations_set_options_ (
+ struct TALER_EXCHANGE_GetAmlLegitimizationsHandle *algh,
unsigned int num_options,
- const struct TALER_EXCHANGE_AmlLegitimizationsGetOptionValue *options)
+ const struct TALER_EXCHANGE_GetAmlLegitimizationsOptionValue *options)
{
for (unsigned int i = 0; i < num_options; i++)
{
switch (options[i].option)
{
- case TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_END:
+ case TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_END:
return GNUNET_OK;
- case TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_LIMIT:
+ case TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_LIMIT:
algh->options.limit = options[i].details.limit;
break;
- case TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_OFFSET:
+ case TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_OFFSET:
algh->options.offset = options[i].details.offset;
break;
- case TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_H_PAYTO:
+ case TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_H_PAYTO:
algh->options.h_payto = options[i].details.h_payto;
break;
- case TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_OPTION_ACTIVE:
+ case TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_OPTION_ACTIVE:
algh->options.active = options[i].details.active;
break;
default:
@@ -364,10 +364,10 @@ TALER_EXCHANGE_aml_legitimizations_get_set_options_ (
enum TALER_EXCHANGE_AmlLegitimizationsGetStartError
-TALER_EXCHANGE_aml_legitimizations_get_start (
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh,
- TALER_EXCHANGE_AmlLegitimizationsGetCallback cb,
- TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE *cb_cls)
+TALER_EXCHANGE_get_aml_legitimizations_start (
+ struct TALER_EXCHANGE_GetAmlLegitimizationsHandle *algh,
+ TALER_EXCHANGE_GetAmlLegitimizationsCallback cb,
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_RESULT_CLOSURE *cb_cls)
{
char officer_pub_str[sizeof (struct TALER_AmlOfficerPublicKeyP) * 2];
char arg_str[sizeof (officer_pub_str) + 64];
@@ -378,7 +378,7 @@ TALER_EXCHANGE_aml_legitimizations_get_start (
if (NULL != algh->job)
{
GNUNET_break (0);
- return TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_E_AGAIN;
+ return TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_START_E_AGAIN;
}
algh->cb = cb;
algh->cb_cls = cb_cls;
@@ -444,7 +444,7 @@ TALER_EXCHANGE_aml_legitimizations_get_start (
if (NULL == algh->url)
{
GNUNET_break (0);
- return TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_E_INTERNAL;
+ return TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_START_E_INTERNAL;
}
{
@@ -456,7 +456,7 @@ TALER_EXCHANGE_aml_legitimizations_get_start (
GNUNET_break (0);
GNUNET_free (algh->url);
algh->url = NULL;
- return TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_E_INTERNAL;
+ return TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_START_E_INTERNAL;
}
/* Add authentication header for AML officer */
@@ -487,13 +487,13 @@ TALER_EXCHANGE_aml_legitimizations_get_start (
&handle_aml_legitimizations_get_finished,
algh);
}
- return TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_OK;
+ return TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_START_OK;
}
void
-TALER_EXCHANGE_aml_legitimizations_get_cancel (
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *algh)
+TALER_EXCHANGE_get_aml_legitimizations_cancel (
+ struct TALER_EXCHANGE_GetAmlLegitimizationsHandle *algh)
{
if (NULL != algh->job)
{
diff --git a/src/lib/exchange_api_management_get_keys.c b/src/lib/exchange_api_management_get_keys.c
@@ -39,7 +39,7 @@
/**
* @brief Handle for a GET /management/keys request.
*/
-struct TALER_EXCHANGE_ManagementGetKeysHandle
+struct TALER_EXCHANGE_GetManagementKeysHandle
{
/**
@@ -77,7 +77,7 @@ struct TALER_EXCHANGE_ManagementGetKeysHandle
* @return #GNUNET_OK if the response was well-formed
*/
static enum GNUNET_GenericReturnValue
-handle_ok (struct TALER_EXCHANGE_ManagementGetKeysHandle *gh,
+handle_ok (struct TALER_EXCHANGE_GetManagementKeysHandle *gh,
const json_t *response)
{
struct TALER_EXCHANGE_ManagementGetKeysResponse gkr = {
@@ -299,7 +299,7 @@ handle_ok (struct TALER_EXCHANGE_ManagementGetKeysHandle *gh,
* Function called when we're done processing the
* HTTP GET /management/keys request.
*
- * @param cls the `struct TALER_EXCHANGE_ManagementGetKeysHandle *`
+ * @param cls the `struct TALER_EXCHANGE_GetManagementKeysHandle *`
* @param response_code HTTP response code, 0 on error
* @param response response body, NULL if not in JSON
*/
@@ -308,7 +308,7 @@ handle_get_keys_finished (void *cls,
long response_code,
const void *response)
{
- struct TALER_EXCHANGE_ManagementGetKeysHandle *gh = cls;
+ struct TALER_EXCHANGE_GetManagementKeysHandle *gh = cls;
const json_t *json = response;
struct TALER_EXCHANGE_ManagementGetKeysResponse gkr = {
.hr.http_status = (unsigned int) response_code,
@@ -373,16 +373,16 @@ handle_get_keys_finished (void *cls,
};
-struct TALER_EXCHANGE_ManagementGetKeysHandle *
+struct TALER_EXCHANGE_GetManagementKeysHandle *
TALER_EXCHANGE_get_management_keys (struct GNUNET_CURL_Context *ctx,
const char *url,
TALER_EXCHANGE_ManagementGetKeysCallback cb,
void *cb_cls)
{
- struct TALER_EXCHANGE_ManagementGetKeysHandle *gh;
+ struct TALER_EXCHANGE_GetManagementKeysHandle *gh;
CURL *eh;
- gh = GNUNET_new (struct TALER_EXCHANGE_ManagementGetKeysHandle);
+ gh = GNUNET_new (struct TALER_EXCHANGE_GetManagementKeysHandle);
gh->cb = cb;
gh->cb_cls = cb_cls;
gh->ctx = ctx;
@@ -415,7 +415,7 @@ TALER_EXCHANGE_get_management_keys (struct GNUNET_CURL_Context *ctx,
void
TALER_EXCHANGE_get_management_keys_cancel (
- struct TALER_EXCHANGE_ManagementGetKeysHandle *gh)
+ struct TALER_EXCHANGE_GetManagementKeysHandle *gh)
{
if (NULL != gh->job)
{
diff --git a/src/testing/testing_api_cmd_get_active_legitimization_measures.c b/src/testing/testing_api_cmd_get_active_legitimization_measures.c
@@ -26,7 +26,7 @@
* State for a GET "active_legitimization_measures" CMD.
*/
struct GetLegitimizationMeasuresState;
-#define TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE \
+#define TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_RESULT_CLOSURE \
struct GetLegitimizationMeasuresState
#include "taler/platform.h"
@@ -43,7 +43,7 @@ struct GetLegitimizationMeasuresState
/**
* Handle while operation is running.
*/
- struct TALER_EXCHANGE_AmlLegitimizationsGetHandle *dh;
+ struct TALER_EXCHANGE_GetAmlLegitimizationsHandle *dh;
/**
* Our interpreter.
@@ -88,8 +88,8 @@ struct GetLegitimizationMeasuresState
*/
static void
get_active_legitimization_measures_cb (
- TALER_EXCHANGE__AML_LEGITIMIZATIONS_GET_RESULT_CLOSURE *ds,
- const struct TALER_EXCHANGE_AmlLegitimizationsGetResult *result)
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_RESULT_CLOSURE *ds,
+ const struct TALER_EXCHANGE_GetAmlLegitimizationsResponse *result)
{
const struct TALER_EXCHANGE_HttpResponse *hr = &result->hr;
@@ -122,7 +122,7 @@ get_active_legitimization_measures_cb (
}
for (size_t i = 0; i<result->details.ok.measures_length; i++)
{
- const struct TALER_EXCHANGE_AmlLegitimizationsGetMeasureDetails *d
+ const struct TALER_EXCHANGE_GetAmlLegitimizationsMeasureDetails *d
= &result->details.ok.measures[i];
json_dumpf (d->measures,
@@ -214,7 +214,7 @@ get_active_legitimization_measures_run (
return;
}
ds->h_payto = *h_payto;
- ds->dh = TALER_EXCHANGE_aml_legitimizations_get_create (
+ ds->dh = TALER_EXCHANGE_get_aml_legitimizations_create (
TALER_TESTING_interpreter_get_context (is),
exchange_url,
officer_priv);
@@ -225,15 +225,16 @@ get_active_legitimization_measures_run (
return;
}
GNUNET_assert (GNUNET_OK ==
- TALER_EXCHANGE_aml_legitimizations_get_set_options (
+ TALER_EXCHANGE_get_aml_legitimizations_set_options (
ds->dh,
- TALER_EXCHANGE_aml_legitimizations_get_option_h_payto (
+ TALER_EXCHANGE_get_aml_legitimizations_option_filter_h_payto
+ (
h_payto),
- TALER_EXCHANGE_aml_legitimizations_get_option_active (
+ TALER_EXCHANGE_get_aml_legitimizations_option_filter_active (
TALER_EXCHANGE_YNA_YES)));
GNUNET_assert (
- TALER_EXCHANGE_AML_LEGITIMIZATIONS_GET_START_OK ==
- TALER_EXCHANGE_aml_legitimizations_get_start (
+ TALER_EXCHANGE_GET_AML_LEGITIMIZATIONS_START_OK ==
+ TALER_EXCHANGE_get_aml_legitimizations_start (
ds->dh,
&get_active_legitimization_measures_cb,
ds));
@@ -258,7 +259,7 @@ get_active_legitimization_measures_cleanup (
{
TALER_TESTING_command_incomplete (ds->is,
cmd->label);
- TALER_EXCHANGE_aml_legitimizations_get_cancel (ds->dh);
+ TALER_EXCHANGE_get_aml_legitimizations_cancel (ds->dh);
ds->dh = NULL;
}
json_decref (ds->expected_measures);
