[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] [taler-exchange] 03/03: Commenting the main "testing" heade
|
From: |
gnunet |
|
Subject: |
[GNUnet-SVN] [taler-exchange] 03/03: Commenting the main "testing" header file. |
|
Date: |
Tue, 29 May 2018 12:18:43 +0200 |
This is an automated email from the git hooks/post-receive script.
marcello pushed a commit to branch master
in repository exchange.
commit 3cb0454dc0d123f3a943d787c67cd4bcfb23a325
Author: Marcello Stanisci <address@hidden>
AuthorDate: Tue May 29 12:18:18 2018 +0200
Commenting the main "testing" header file.
---
src/exchange-lib/testing_api_cmd_bank_check.c | 2 +
src/exchange-lib/testing_api_cmd_exec_wirewatch.c | 23 +-
src/exchange-lib/testing_api_helpers.c | 9 +-
src/exchange-lib/testing_api_trait_amount.c | 14 +-
src/exchange-lib/testing_api_trait_reserve_priv.c | 1 -
src/exchange-lib/testing_api_trait_wtid.c | 4 +-
src/include/taler_testing_lib.h | 863 ++++++++++++++--------
7 files changed, 600 insertions(+), 316 deletions(-)
diff --git a/src/exchange-lib/testing_api_cmd_bank_check.c
b/src/exchange-lib/testing_api_cmd_bank_check.c
index df6c139..c46aa10 100644
--- a/src/exchange-lib/testing_api_cmd_bank_check.c
+++ b/src/exchange-lib/testing_api_cmd_bank_check.c
@@ -355,6 +355,8 @@ TALER_TESTING_cmd_check_bank_empty (const char *label)
* @param deposit_reference reference to a CMD that is
* able to provide the "check bank transfer" operation
* input data.
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_check_bank_transfer_with_ref
diff --git a/src/exchange-lib/testing_api_cmd_exec_wirewatch.c
b/src/exchange-lib/testing_api_cmd_exec_wirewatch.c
index 989dae0..aebf46e 100644
--- a/src/exchange-lib/testing_api_cmd_exec_wirewatch.c
+++ b/src/exchange-lib/testing_api_cmd_exec_wirewatch.c
@@ -2,18 +2,21 @@
This file is part of TALER
Copyright (C) 2018 Taler Systems SA
- TALER is free software; you can redistribute it and/or modify it under the
- terms of the GNU General Public License as published by the Free Software
- Foundation; either version 3, or (at your option) any later version.
-
- TALER is distributed in the hope that it will be useful, but WITHOUT ANY
- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
- A PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License along with
- TALER; see the file COPYING. If not, see
+ TALER is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as
+ published by the Free Software Foundation; either version 3,
+ or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public
+ License along with TALER; see the file COPYING. If not, see
<http://www.gnu.org/licenses/>
*/
+
/**
* @file exchange-lib/testing_api_cmd_exec_wirewatch.c
* @brief run the taler-exchange-wirewatch command
diff --git a/src/exchange-lib/testing_api_helpers.c
b/src/exchange-lib/testing_api_helpers.c
index c6459a5..b3e32fc 100644
--- a/src/exchange-lib/testing_api_helpers.c
+++ b/src/exchange-lib/testing_api_helpers.c
@@ -568,10 +568,11 @@ TALER_TESTING_prepare_fakebank (const char
*config_filename,
"payto://x-taler-bank/",
strlen ("payto://x-taler-bank/")))
{
- GNUNET_log_config_invalid (GNUNET_ERROR_TYPE_WARNING,
- config_section,
- "URL",
- "expected `x-taler-bank' payto://-URL");
+ GNUNET_log_config_invalid
+ (GNUNET_ERROR_TYPE_WARNING,
+ config_section,
+ "URL",
+ "expected `x-taler-bank' payto://-URL");
GNUNET_CONFIGURATION_destroy (cfg);
GNUNET_free (payto_url);
return NULL;
diff --git a/src/exchange-lib/testing_api_trait_amount.c
b/src/exchange-lib/testing_api_trait_amount.c
index 9c37783..35bc86a 100644
--- a/src/exchange-lib/testing_api_trait_amount.c
+++ b/src/exchange-lib/testing_api_trait_amount.c
@@ -43,10 +43,10 @@
* @return #GNUNET_OK on success
*/
int
-TALER_TESTING_get_trait_amount_obj (
- const struct TALER_TESTING_Command *cmd,
- unsigned int index,
- const struct TALER_Amount **amount)
+TALER_TESTING_get_trait_amount_obj
+ (const struct TALER_TESTING_Command *cmd,
+ unsigned int index,
+ const struct TALER_Amount **amount)
{
return cmd->traits (cmd->cls,
(void **) amount,
@@ -65,9 +65,9 @@ TALER_TESTING_get_trait_amount_obj (
* @return the trait.
*/
struct TALER_TESTING_Trait
-TALER_TESTING_make_trait_amount_obj (
- unsigned int index,
- const struct TALER_Amount *amount)
+TALER_TESTING_make_trait_amount_obj
+ (unsigned int index,
+ const struct TALER_Amount *amount)
{
struct TALER_TESTING_Trait ret = {
.index = index,
diff --git a/src/exchange-lib/testing_api_trait_reserve_priv.c
b/src/exchange-lib/testing_api_trait_reserve_priv.c
index 587a11c..aa1ce3d 100644
--- a/src/exchange-lib/testing_api_trait_reserve_priv.c
+++ b/src/exchange-lib/testing_api_trait_reserve_priv.c
@@ -54,7 +54,6 @@ TALER_TESTING_get_trait_reserve_priv
}
-
/**
* Offer a reserve private key.
*
diff --git a/src/exchange-lib/testing_api_trait_wtid.c
b/src/exchange-lib/testing_api_trait_wtid.c
index 140a2ac..8406dbb 100644
--- a/src/exchange-lib/testing_api_trait_wtid.c
+++ b/src/exchange-lib/testing_api_trait_wtid.c
@@ -53,10 +53,12 @@ TALER_TESTING_get_trait_wtid
}
/**
+ * Offer a WTID.
+ *
* @param index associate the object with this index
* @param wtid which object should be returned
*
- * @return the trait, to be put in the traits array of the command
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_wtid
diff --git a/src/include/taler_testing_lib.h b/src/include/taler_testing_lib.h
index f7d3cca..5997f89 100644
--- a/src/include/taler_testing_lib.h
+++ b/src/include/taler_testing_lib.h
@@ -74,6 +74,7 @@
*
* @param account_no account number
* @param bank_url the bank_url
+ *
* @return JSON describing the account, including the
* payto://-URL of the account, must be manually decref'd
*/
@@ -132,7 +133,8 @@ TALER_TESTING_url_port_free (const char *url);
* If everything is OK, return the configured URL of the fakebank.
*
* @param config_filename configuration file to use
- * @param config_section which account to use (must match x-taler-bank)
+ * @param config_section which account to use
+ * (must match x-taler-bank)
* @return NULL on error, fakebank URL otherwise
*/
char *
@@ -176,8 +178,8 @@ struct TALER_TESTING_Interpreter
struct GNUNET_CURL_RescheduleContext *rc;
/**
- * Handle to our fakebank, if #TALER_TESTING_run_with_fakebank() was used.
- * Otherwise NULL.
+ * Handle to our fakebank, if #TALER_TESTING_run_with_fakebank()
+ * was used. Otherwise NULL.
*/
struct TALER_FAKEBANK_Handle *fakebank;
@@ -261,6 +263,8 @@ struct TALER_TESTING_Command
* #TALER_TESTING_interpreter_next() or
* #TALER_TESTING_interpreter_fail().
*
+ * @param cls closure
+ * @param cmd command being run
* @param i interpreter state
*/
void
@@ -274,6 +278,7 @@ struct TALER_TESTING_Command
* (CTRL-C) or test failure or test success.
*
* @param cls closure
+ * @param cmd command being cleaned up
*/
void
(*cleanup)(void *cls,
@@ -301,6 +306,10 @@ struct TALER_TESTING_Command
/**
* Lookup command by label.
+ *
+ * @param i interpreter state.
+ * @param label label of the command to lookup.
+ * @return the command, if it is found, or NULL.
*/
const struct TALER_TESTING_Command *
TALER_TESTING_interpreter_lookup_command
@@ -309,32 +318,40 @@ TALER_TESTING_interpreter_lookup_command
/**
* Obtain main execution context for the main loop.
+ *
+ * @param is interpreter state.
+ * @return CURL execution context.
*/
struct GNUNET_CURL_Context *
TALER_TESTING_interpreter_get_context
(struct TALER_TESTING_Interpreter *is);
/**
- * Obtain current label.
+ * Obtain label of the command being now run.
+ *
+ * @param is interpreter state.
+ * @return the label.
*/
const char *
TALER_TESTING_interpreter_get_current_label
(struct TALER_TESTING_Interpreter *is);
-/**
- * Obtain main execution context for the main loop.
- */
-struct GNUNET_CURL_Context *
-TALER_TESTING_interpreter_get_context
- (struct TALER_TESTING_Interpreter *is);
+/**
+ * Get connection handle to the fakebank.
+ *
+ * @param is interpreter state.
+ * @return the handle.
+ */
struct TALER_FAKEBANK_Handle *
TALER_TESTING_interpreter_get_fakebank
(struct TALER_TESTING_Interpreter *is);
/**
* Current command is done, run the next one.
+ *
+ * @param is interpreter state.
*/
void
TALER_TESTING_interpreter_next
@@ -342,6 +359,8 @@ TALER_TESTING_interpreter_next
/**
* Current command failed, clean up and fail the test case.
+ *
+ * @param is interpreter state.
*/
void
TALER_TESTING_interpreter_fail
@@ -361,18 +380,35 @@ TALER_TESTING_cmd_end ();
* Then obtain the process trait of the current
* command, wait on the the zombie and continue
* with the next command.
+ *
+ * @param is interpreter state.
*/
void
TALER_TESTING_wait_for_sigchld
(struct TALER_TESTING_Interpreter *is);
+/**
+ * Schedule the first CMD in the CMDs array.
+ *
+ * @param is interpreter state.
+ * @param commands array of all the commands to execute.
+ */
void
TALER_TESTING_run (struct TALER_TESTING_Interpreter *is,
struct TALER_TESTING_Command *commands);
+
+/**
+ * First launch the fakebank, then schedule the first CMD
+ * in the array of all the CMDs to execute.
+ *
+ * @param is interpreter state.
+ * @param commands array of all the commands to execute.
+ * @param bank_url base URL of the fake bank.
+ */
void
TALER_TESTING_run_with_fakebank
(struct TALER_TESTING_Interpreter *is,
@@ -381,7 +417,13 @@ TALER_TESTING_run_with_fakebank
/**
- * FIXME
+ * The function that contains the array of all the CMDs to run,
+ * which is then on charge to call some fashion of
+ * TALER_TESTING_run*. In all the test cases, this function is
+ * always the GNUnet-ish "run" method.
+ *
+ * @param cls closure.
+ * @param is interpreter state.
*/
typedef void
(*TALER_TESTING_Main)(void *cls,
@@ -396,9 +438,8 @@ typedef void
* @param main_cb_cls a closure for "run", typically NULL.
* @param config_filename configuration filename.
* @param exchanged exchange process handle: will be put in the
- * state as some commands - e.g. revoke - need to send
- * signal to it, for example to let it know to reload the
- * key state..
+ * state as some commands - e.g. revoke - need to signal it,
+ * for example to let it know to reload the key state.
*
* @return FIXME: not sure what 'is.result' is at this stage.
*/
@@ -410,24 +451,49 @@ TALER_TESTING_setup (TALER_TESTING_Main main_cb,
/**
- * Initialize scheduler loop and curl context for the testcase
+ * Initialize scheduler loop and curl context for the test case
* including starting and stopping the exchange using the given
* configuration file.
+ *
+ * @param main_cb main method.
+ * @param main_cb_cls main method closure.
+ * @param config_filename configuration file name. Is is used
+ * by both this function and the exchange itself. In the
+ * first case it gives out the exchange port number and
+ * the exchange base URL so as to check whether the port
+ * is available and the exchange responds when requested
+ * at its base URL.
+ * @return #GNUNET_OK if no errors occurred.
*/
int
TALER_TESTING_setup_with_exchange (TALER_TESTING_Main main_cb,
void *main_cb_cls,
const char *config_file);
-
-
-
/* ************** Specific interpreter commands ************ */
/**
- * Perform a wire transfer (formerly Admin-add-incoming)
+ * Create fakebank_transfer command, the subject line will be
+ * derived from a randomly created reserve priv. Note that that
+ * reserve priv will then be offered as trait.
+ *
+ * @param label command label.
+ * @param amount amount to transfer.
+ * @param bank_url base URL of the bank that implements this
+ * wire transer. For simplicity, both credit and debit
+ * bank account exist at the same bank.
+ * @param debit_account_no which account (expressed as a number)
+ * gives money.
+ * @param credit_account_no which account (expressed as a number)
+ * receives money.
+ * @param auth_username username identifying the @a
+ * debit_account_no at the bank.
+ * @param auth_password password for @a auth_username.
+ * @param exchange_url which exchange is involved in this transfer.
+ * This data is used for tracking purposes (FIXME: explain
+ * _how_).
*
- * @return NULL on failure
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_fakebank_transfer (const char *label,
@@ -441,8 +507,28 @@ TALER_TESTING_cmd_fakebank_transfer (const char *label,
/**
- * Create fakebank_transfer command with custom subject.
+ * Create "fakebank transfer" CMD, letting the caller specifying
+ * the subject line.
+ *
+ * @param label command label.
+ * @param amount amount to transfer.
+ * @param bank_url base URL of the bank that implements this
+ * wire transer. For simplicity, both credit and debit
+ * bank account exist at the same bank.
+ * @param debit_account_no which account (expressed as a number)
+ * gives money.
+ * @param credit_account_no which account (expressed as a number)
+ * receives money.
*
+ * @param auth_username username identifying the @a
+ * debit_account_no at the bank.
+ * @param auth_password password for @a auth_username.
+ * @param subject wire transfer's subject line.
+ * @param exchange_url which exchange is involved in this transfer.
+ * This data is used for tracking purposes (FIXME: explain
+ * _how_).
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_fakebank_transfer_with_subject
@@ -458,8 +544,27 @@ TALER_TESTING_cmd_fakebank_transfer_with_subject
/**
- * Create fakebank_transfer command with custom subject.
+ * Create "fakebank transfer" CMD, letting the caller specify
+ * a reference to a command that can offer a reserve private key.
+ * This private key will then be used to construct the subject line
+ * of the wire transfer.
+ *
+ * @param label command label.
+ * @param amount the amount to transfer.
+ * @param bank_url base URL of the bank running the transfer.
+ * @param debit_account_no which account (expressed as a number)
+ * gives money.
+ * @param credit_account_no which account (expressed as a number)
+ * receives money.
+ * @param auth_username username identifying the @a
+ * debit_account_no at the bank.
+ * @param auth_password password for @a auth_username.
+ * @param ref reference to a command that can offer a reserve
+ * private key.
+ * @param exchange_url the exchage involved in the transfer,
+ * tipically receiving the money in order to fuel a reserve.
*
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_fakebank_transfer_with_ref
@@ -474,8 +579,35 @@ TALER_TESTING_cmd_fakebank_transfer_with_ref
const char *exchange_url);
/**
- * Create fakebank_transfer command with custom subject.
+ * Create "fakebank transfer" CMD, letting the caller specifying
+ * the merchant instance. This version is useful when a tip
+ * reserve should be topped up, in fact the interpreter will need
+ * the "tipping instance" in order to get the instance public key
+ * and make a wire transfer subject out of it.
+ *
+ * @param label command label.
+ * @param amount amount to transfer.
+ * @param bank_url base URL of the bank that implements this
+ * wire transer. For simplicity, both credit and debit
+ * bank account exist at the same bank.
+ * @param debit_account_no which account (expressed as a number)
+ * gives money.
+ * @param credit_account_no which account (expressed as a number)
+ * receives money.
+ *
+ * @param auth_username username identifying the @a
+ * debit_account_no at the bank.
+ * @param auth_password password for @a auth_username.
+ * @param instance the instance that runs the tipping. Under this
+ * instance, the configuration file will provide the private
+ * key of the tipping reserve. This data will then used to
+ * construct the wire transfer subject line.
+ * @param exchange_url which exchange is involved in this transfer.
+ * This data is used for tracking purposes (FIXME: explain
+ * _how_).
+ * @param config_filename configuration file to use.
*
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_fakebank_transfer_with_instance
@@ -491,10 +623,10 @@ TALER_TESTING_cmd_fakebank_transfer_with_instance
const char *config_filename);
/**
- * Execute taler-exchange-wirewatch process.
+ * Make a "wirewatch" CMD.
*
- * @param label command label
- * @param config_filanem configuration filename.
+ * @param label command label.
+ * @param config_filename configuration filename.
*
* @return the command.
*/
@@ -503,10 +635,11 @@ TALER_TESTING_cmd_exec_wirewatch (const char *label,
const char *config_filename);
/**
- * Execute taler-exchange-aggregator process.
+ * Make a "aggregator" CMD.
*
- * @param label command label
- * @param config_filename configuration filename
+ * @param label command label.
+ * @param config_filename configuration file for the
+ * aggregator to use.
*
* @return the command.
*/
@@ -515,10 +648,10 @@ TALER_TESTING_cmd_exec_aggregator (const char *label,
const char *config_filename);
/**
- * Execute taler-exchange-keyup process.
+ * Make the "keyup" CMD.
*
- * @param label command label
- * @param config_filename configuration filename
+ * @param label command label.
+ * @param config_filename configuration filename.
*
* @return the command.
*/
@@ -527,7 +660,7 @@ TALER_TESTING_cmd_exec_keyup (const char *label,
const char *config_filename);
/**
- * Execute taler-auditor-sign process.
+ * Make a "auditor sign" CMD.
*
* @param label command label
* @param config_filename configuration filename
@@ -540,9 +673,16 @@ TALER_TESTING_cmd_exec_auditor_sign (const char *label,
/**
- * Create withdraw command.
+ * Create a withdraw command, letting the caller specify
+ * the desired amount as string.
*
- * @return NULL on failure
+ * @param label command label.
+ * @param exchange handle to the exchange.
+ * @param amount how much we withdraw.
+ * @param expected_response_code which HTTP response code
+ * we expect from the exchange.
+ *
+ * @return the withdraw command to be executed by the interpreter.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_withdraw_amount
@@ -554,8 +694,17 @@ TALER_TESTING_cmd_withdraw_amount
/**
- * Create withdraw command.
+ * Create withdraw command, letting the caller specify the
+ * amount by a denomination key.
*
+ * @param label command label.
+ * @param exchange connection handle to the exchange.
+ * @param reserve_reference reference to the reserve to withdraw
+ * from; will provide reserve priv to sign the request.
+ * @param dk denomination public key.
+ * @param expected_response_code expected HTTP response code.
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_withdraw_denomination
@@ -567,7 +716,7 @@ TALER_TESTING_cmd_withdraw_denomination
/**
- * Create a /wire command.
+ * Create a "wire" command.
*
* @param label the command label.
* @param exchange the exchange to connect to.
@@ -577,7 +726,7 @@ TALER_TESTING_cmd_withdraw_denomination
* @param expected_response_code the HTTP response the exchange
* should return.
*
- * @return the command to be executed by the interpreter.
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_wire (const char *label,
@@ -588,16 +737,15 @@ TALER_TESTING_cmd_wire (const char *label,
/**
- * Create a /reserve/status command.
+ * Create a "reserve status" command.
*
* @param label the command label.
* @param exchange the exchange to connect to.
* @param reserve_reference reference to the reserve to check.
- * @param expected_balance balance expected to be at the
- * referenced reserve.
+ * @param expected_balance expected balance for the reserve.
* @param expected_response_code expected HTTP response code.
*
- * @return the command to be executed by the interpreter.
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_status (const char *label,
@@ -607,26 +755,25 @@ TALER_TESTING_cmd_status (const char *label,
unsigned int expected_response_code);
/**
- * Create a deposit command.
+ * Create a "deposit" command.
*
- * @param label command label
- * @param exchange exchange connection
+ * @param label command label.
+ * @param exchange exchange connection.
* @param coin_reference reference to any operation that can
- * provide a coin
+ * provide a coin.
* @param coin_index if @a withdraw_reference offers an array of
- * coins, this parameter selects which one in that array
+ * coins, this parameter selects which one in that array.
* This value is currently ignored, as only one-coin
* withdrawals are implemented.
- * @param wire_details JSON including payto://-URL of the merchant performing
the
- * deposit, reference is captured by this command
+ * @param wire_details wire details associated with the "deposit"
+ * request.
* @param contract_terms contract terms to be signed over by the
- * coin
- * @param refund_deadline refund deadline
- * @param amount how much is going to be deposited
- * @param expected_response_code which HTTP status code we expect
- * in the response
+ * coin.
+ * @param refund_deadline refund deadline, zero means 'no refunds'.
+ * @param amount how much is going to be deposited.
+ * @param expected_response_code expected HTTP response code.
*
- * @return the deposit command to be run by the interpreter
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_deposit
@@ -644,14 +791,15 @@ TALER_TESTING_cmd_deposit
/**
* Create a "refresh melt" command.
*
- * @param label command label
- * @param exchange connection to the exchange
- * @param amount Fixme
- * @param coin_reference reference to a command that will provide
- * a coin to refresh
- * @param expected_response_code expected HTTP code
+ * @param label command label.
+ * @param exchange connection to the exchange.
+ * @param amount amount to be melted.
+ * @param coin_reference reference to a command
+ * that will provide a coin to refresh.
+ * @param expected_response_code expected HTTP code.
+ *
+ * @return the command.
*/
-
struct TALER_TESTING_Command
TALER_TESTING_cmd_refresh_melt
(const char *label,
@@ -661,17 +809,19 @@ TALER_TESTING_cmd_refresh_melt
unsigned int expected_response_code);
/**
- * Create a "refresh melt" command, that does TWO /refresh/melt
- * requests.
+ * Create a "refresh melt" CMD that does TWO /refresh/melt
+ * requests. This was needed to test the replay of a valid melt
+ * request, see #5312.
*
* @param label command label
* @param exchange connection to the exchange
- * @param amount Fixme
+ * @param amount FIXME not used.
* @param coin_reference reference to a command that will provide
* a coin to refresh
* @param expected_response_code expected HTTP code
+ *
+ * @return the command.
*/
-
struct TALER_TESTING_Command
TALER_TESTING_cmd_refresh_melt_double
(const char *label,
@@ -684,12 +834,12 @@ TALER_TESTING_cmd_refresh_melt_double
/**
* Create a "refresh reveal" command.
*
- * @param label command label
- * @param exchange connection to the exchange
- * @param melt_reference reference to a "refresh melt" command
- * @param expected_response_code expected HTTP response code
+ * @param label command label.
+ * @param exchange connection to the exchange.
+ * @param melt_reference reference to a "refresh melt" command.
+ * @param expected_response_code expected HTTP response code.
*
- * @return the "refresh reveal" command
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_refresh_reveal
@@ -702,9 +852,9 @@ TALER_TESTING_cmd_refresh_reveal
/**
* Create a "refresh link" command.
*
- * @param label command label
- * @param exchange connection to the exchange
- * @param melt_reference reference to a "refresh melt" command
+ * @param label command label.
+ * @param exchange connection to the exchange.
+ * @param reveal_reference reference to a "refresh reveal" CMD.
* @param expected_response_code expected HTTP response code
*
* @return the "refresh link" command
@@ -718,18 +868,19 @@ TALER_TESTING_cmd_refresh_link
/**
- * Create a /track/transaction command.
+ * Create a "track transaction" command.
*
* @param label the command label.
* @param exchange the exchange to connect to.
- * @param transaction_reference reference to a deposit operation.
- * @param coin_index index of the coin involved in the transaction
+ * @param transaction_reference reference to a deposit operation,
+ * will be used to get the input data for the track.
+ * @param coin_index index of the coin involved in the transaction.
* @param expected_response_code expected HTTP response code.
- * @param bank_transfer_reference which #OC_CHECK_BANK_TRANSFER
- * wtid should this match? NULL
- * for none
+ * @param bank_transfer_reference reference to a command that
+ * can offer a WTID so as to check that against what WTID
+ * the tracked operation has. Set as NULL if not needed.
*
- * @return the command to be executed by the interpreter.
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_track_transaction
@@ -741,18 +892,22 @@ TALER_TESTING_cmd_track_transaction
const char *bank_transfer_reference);
/**
- * Make a /track/transfer command, expecting the transfer
- * not being done (yet).
+ * Make a "track transfer" CMD where no "expected"-arguments,
+ * except the HTTP response code, are given. The best use case
+ * is when what matters to check is the HTTP response code, e.g.
+ * when a bogus WTID was passed.
*
* @param label the command label
- * @param exchange connection to the exchange
+ * @param exchange connection to the exchange.
* @param wtid_reference reference to any command which can provide
- * a wtid
- * @param index in case there are multiple wtid offered, this
- * parameter selects a particular one
- * @param expected_response_code expected HTTP response code
+ * a wtid. If NULL is given, then a all zeroed WTID is
+ * used that will at 99.9999% probability NOT match any
+ * existing WTID known to the exchange.
+ * @param index index number of the WTID to track, in case there
+ * are multiple on offer.
+ * @param expected_response_code expected HTTP response code.
*
- * @return the command
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_track_transfer_empty
@@ -764,18 +919,18 @@ TALER_TESTING_cmd_track_transfer_empty
/**
- * Make a /track/transfer command, specifying which amount and
+ * Make a "track transfer" command, specifying which amount and
* wire fee are expected.
*
- * @param label the command label
- * @param exchange connection to the exchange
+ * @param label the command label.
+ * @param exchange connection to the exchange.
* @param wtid_reference reference to any command which can provide
- * a wtid
- * @param index in case there are multiple wtid offered, this
- * parameter selects a particular one
- * @param expected_response_code expected HTTP response code
- * @param expected_amount how much money we expect being
- * moved with this wire-transfer.
+ * a wtid. Will be the one tracked.
+ * @param index in case there are multiple WTID offered, this
+ * parameter selects a particular one.
+ * @param expected_response_code expected HTTP response code.
+ * @param expected_amount how much money we expect being moved
+ * with this wire-transfer.
* @param expected_wire_fee expected wire fee.
*
* @return the command
@@ -791,14 +946,15 @@ TALER_TESTING_cmd_track_transfer
const char *expected_wire_fee);
/**
- * Command to check whether a particular wire transfer has been
- * made or not.
+ * Make a "bank check" CMD. It checks whether a
+ * particular wire transfer has been made or not.
*
- * @param label the command label
- * @param exchange_base_url base url of the exchange (Fixme: why?)
- * @param amount the amount expected to be transferred
- * @param debit_account the account that gave money
- * @param credit_account the account that received money
+ * @param label the command label.
+ * @param exchange_base_url base url of the exchange involved in
+ * the wire transfer.
+ * @param amount the amount expected to be transferred.
+ * @param debit_account the account that gave money.
+ * @param credit_account the account that received money.
*
* @return the command
*/
@@ -810,8 +966,18 @@ TALER_TESTING_cmd_check_bank_transfer
uint64_t debit_account,
uint64_t credit_account);
+
+
/**
- * FIXME.
+ * Define a "bank check" CMD that takes the input
+ * data from another CMD that offers it.
+ *
+ * @param label command label.
+ * @param deposit_reference reference to a CMD that is
+ * able to provide the "check bank transfer" operation
+ * input data.
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_check_bank_transfer_with_ref
@@ -819,9 +985,10 @@ TALER_TESTING_cmd_check_bank_transfer_with_ref
const char *deposit_reference);
/**
- * Check bank's balance is zero.
+ * Checks wheter all the wire transfers got "checked"
+ * by the "bank check" CMD.
*
- * @param credit_account the account that received money
+ * @param label command label.
*
* @return the command
*/
@@ -829,15 +996,19 @@ struct TALER_TESTING_Command
TALER_TESTING_cmd_check_bank_empty (const char *label);
/**
- * Create a /refund test command, allows to specify refund
- * transaction id.
+ * Create a "refund" command, allow to specify refund transaction
+ * id. Mainly used to create conflicting requests.
*
- * @param label command label
- * @param expected_response_code expected HTTP status code
- * @param refund_amount the amount to ask a refund for
- * @param refund_fee expected refund fee
+ * @param label command label.
+ * @param expected_response_code expected HTTP status code.
+ * @param refund_amount the amount to ask a refund for.
+ * @param refund_fee expected refund fee.
* @param coin_reference reference to a command that can
* provide a coin to be refunded.
+ * @param refund_transaction_id transaction id to use
+ * in the request.
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_refund_with_id
@@ -849,14 +1020,16 @@ TALER_TESTING_cmd_refund_with_id
uint64_t refund_transaction_id);
/**
- * Create a /refund test command.
+ * Create a "refund" command.
*
- * @param label command label
- * @param expected_response_code expected HTTP status code
- * @param refund_amount the amount to ask a refund for
- * @param refund_fee expected refund fee
+ * @param label command label.
+ * @param expected_response_code expected HTTP status code.
+ * @param refund_amount the amount to ask a refund for.
+ * @param refund_fee expected refund fee.
* @param coin_reference reference to a command that can
* provide a coin to be refunded.
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_refund (const char *label,
@@ -867,15 +1040,15 @@ TALER_TESTING_cmd_refund (const char *label,
/**
- * Make a /payback command.
+ * Make a "payback" command.
*
* @param label the command label
* @param expected_response_code expected HTTP status code
- * @param coin_reference reference to any command which offers
- * a reserve private key plus a coin to be paid back.
+ * @param coin_reference reference to any command which
+ * offers a coin & reserve private key.
* @param amount denomination to pay back.
*
- * @return a /revoke command
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_payback (const char *label,
@@ -885,15 +1058,15 @@ TALER_TESTING_cmd_payback (const char *label,
/**
- * Make a /revoke command.
+ * Make a "revoke" command.
*
- * @param label the command label
- * @param expected_response_code expected HTTP status code
- * @param coin_reference reference to any command which offers
- * a coin trait
+ * @param label the command label.
+ * @param expected_response_code expected HTTP status code.
+ * @param coin_reference reference to a CMD that will offer the
+ * denomination to revoke.
* @param config_filename configuration file name.
*
- * @return a /revoke command
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_revoke (const char *label,
@@ -902,11 +1075,11 @@ TALER_TESTING_cmd_revoke (const char *label,
const char *config_filename);
/**
- * Send a signal to a process.
+ * Create a "signal" CMD.
*
- * @param label command label
- * @param process handle to the process
- * @param signal signal to send
+ * @param label command label.
+ * @param process handle to the process to signal.
+ * @param signal signal to send.
*
* @return the command.
*/
@@ -916,12 +1089,15 @@ TALER_TESTING_cmd_signal (const char *label,
int signal);
/**
- * Make a "check keys" command.
+ * Make a "check keys" command. This type of command
+ * checks whether the number of denomination keys from
+ * @a exchange matches @a num_denom_keys.
*
* @param label command label
- * @param generation FIXME
- * @param num_denom_keys FIXME
- * @param exchange connection to the exchange
+ * @param generation how many /keys responses are expected to
+ * have been returned when this CMD will be run.
+ * @param num_denom_keys expected number of denomination keys.
+ * @param exchange connection handle to the exchange to test.
*
* @return the command.
*/
@@ -939,19 +1115,44 @@ TALER_TESTING_cmd_check_keys
*/
struct TALER_TESTING_Trait
{
+ /**
+ * Index number associated with the trait. This gives the
+ * possibility to have _multiple_ traits on offer under the
+ * same name.
+ */
unsigned int index;
+ /**
+ * Trait type, for example "reserve-pub" or "coin-priv".
+ */
const char *trait_name;
+ /**
+ * Pointer to the piece of data to offer.
+ */
const void *ptr;
};
+/**
+ * "end" trait. Because traits are offered into arrays,
+ * this type of trait is used to mark the end of such arrays;
+ * useful when iterating over those.
+ */
struct TALER_TESTING_Trait
TALER_TESTING_trait_end (void);
+/**
+ * Extract a trait.
+ *
+ * @param traits the array of all the traits.
+ * @param ret[out] where to store the result.
+ * @param trait type of the trait to extract.
+ * @param index index number of the trait to extract.
+ * @return #GNUNET_OK when the trait is found.
+ */
int
TALER_TESTING_get_trait (const struct TALER_TESTING_Trait *traits,
void **ret,
@@ -961,6 +1162,16 @@ TALER_TESTING_get_trait (const struct TALER_TESTING_Trait
*traits,
/* ****** Specific traits supported by this component ******* */
+
+/**
+ * Offer a reserve private key.
+ *
+ * @param index reserve priv's index number.
+ * @param reserve_priv reserve private key to offer.
+ *
+ * @return the trait.
+ */
+
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_reserve_priv
(unsigned int index,
@@ -970,11 +1181,11 @@ TALER_TESTING_make_trait_reserve_priv
/**
* Obtain a reserve private key from a @a cmd.
*
- * @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- * offer
- * @param reserve_priv[out] set to the private key of the reserve
- * @return #GNUNET_OK on success
+ * @param cmd command to extract the reserve priv from.
+ * @param index reserve priv's index number.
+ * @param reserve_priv[out] set to the reserve priv.
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_reserve_priv
@@ -984,14 +1195,15 @@ TALER_TESTING_get_trait_reserve_priv
/**
- * Obtain location where a command stores a pointer to a process
+ * Obtain location where a command stores a pointer to a process.
*
- * @param cmd command to extract trait from
- * @param selector which process to pick if @a cmd has multiple
- * on offer
- * @param processp[out] set to address of the pointer to the
- * process
- * @return #GNUNET_OK on success
+ * @param cmd command to extract trait from.
+ * @param index which process to pick if @a cmd
+ * has multiple on offer.
+ * @param coin_priv[out] set to the address of the pointer to the
+ * process.
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_process
@@ -1000,6 +1212,16 @@ TALER_TESTING_get_trait_process
struct GNUNET_OS_Process ***processp);
+
+/**
+ * Offer location where a command stores a pointer to a process.
+ *
+ * @param index offered location index number, in case there are
+ * multiple on offer.
+ * @param processp process location to offer.
+ *
+ * @return the trait.
+ */
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_process
(unsigned int index,
@@ -1007,7 +1229,12 @@ TALER_TESTING_make_trait_process
/**
- * @param selector FIXME
+ * Offer coin private key.
+ *
+ * @param index index number to associate with offered coin priv.
+ * @param coin_priv coin private key to offer.
+ *
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_coin_priv
@@ -1017,11 +1244,11 @@ TALER_TESTING_make_trait_coin_priv
/**
* Obtain a coin private key from a @a cmd.
*
- * @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- * offer
- * @param coin_priv[out] set to the private key of the coin
- * @return #GNUNET_OK on success
+ * @param cmd command to extract trait from.
+ * @param index index of the coin priv to obtain.
+ * @param coin_priv[out] set to the private key of the coin.
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_coin_priv
@@ -1030,10 +1257,12 @@ TALER_TESTING_get_trait_coin_priv
struct TALER_CoinSpendPrivateKeyP **coin_priv);
/**
- * @param selector a "tag" to associate the object with
- * @param blinding_key which object should be returned
+ * Offer blinding key.
*
- * @return the trait, to be put in the traits array of the command
+ * @param index index number to associate to the offered key.
+ * @param blinding_key blinding key to offer.
+ *
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_blinding_key
@@ -1041,13 +1270,13 @@ TALER_TESTING_make_trait_blinding_key
const struct TALER_DenominationBlindingKeyP *blinding_key);
/**
- * Obtain a coin's blinding key from a @a cmd.
+ * Obtain a blinding key from a @a cmd.
*
* @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- * offer
- * @param blinding_key[out] set to the blinding key of the coin
- * @return #GNUNET_OK on success
+ * @param index which coin to pick if @a cmd has multiple on offer.
+ * @param blinding_key[out] set to the offered blinding key.
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_blinding_key
@@ -1056,10 +1285,12 @@ TALER_TESTING_get_trait_blinding_key
struct TALER_DenominationBlindingKeyP **blinding_key);
/**
- * @param selector a "tag" to associate the object with
- * @param pdk which object should be returned
+ * Make a trait for a denomination public key.
+ *
+ * @param index index number to associate to the offered denom pub.
+ * @param denom_pub denom pub to offer with this trait.
*
- * @return the trait, to be put in the traits array of the command
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_denom_pub
@@ -1067,13 +1298,13 @@ TALER_TESTING_make_trait_denom_pub
const struct TALER_EXCHANGE_DenomPublicKey *dpk);
/**
- * Obtain a coin private key from a @a cmd.
+ * Obtain a denomination public key from a @a cmd.
*
* @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- * offer
- * @param dpk[out] set to a denomination key of the coin
- * @return #GNUNET_OK on success
+ * @param index index number of the denom to obtain.
+ * @param denom_pub[out] set to the offered denom pub.
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_denom_pub
@@ -1083,13 +1314,13 @@ TALER_TESTING_get_trait_denom_pub
/**
- * Obtain a coin denomination signature from a @a cmd.
+ * Obtain a denomination signature from a @a cmd.
*
- * @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- * offer
- * @param sig[out] set to a denomination signature over the coin
- * @return #GNUNET_OK on success
+ * @param cmd command to extract the denom sig from.
+ * @param index index number associated with the denom sig.
+ * @param denom_sig[out] set to the offered signature.
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_denom_sig
@@ -1098,7 +1329,13 @@ TALER_TESTING_get_trait_denom_sig
struct TALER_DenominationSignature **dpk);
/**
- * @param selector
+ * Offer denom sig.
+ *
+ * @param index index number to associate to the signature on
+ * offer.
+ * @param denom_sig the denom sig on offer.
+ *
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_denom_sig
@@ -1107,24 +1344,24 @@ TALER_TESTING_make_trait_denom_sig
/**
- * @param selector associate the object with this "tag"
- * @param i which object should be returned
+ * Offer number trait, 64-bit version.
*
- * @return the trait, to be put in the traits array of the command
+ * @param index the number's index number.
+ * @param n number to offer.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_uint64
(unsigned int index,
- const uint64_t *i);
+ const uint64_t *n);
/**
- * Obtain a "number" value from @a cmd.
+ * Obtain a "number" value from @a cmd, 64-bit version.
*
- * @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- * offer
+ * @param cmd command to extract the number from.
+ * @param index the number's index number.
* @param n[out] set to the number coming from @a cmd.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_uint64
@@ -1133,10 +1370,12 @@ TALER_TESTING_get_trait_uint64
const uint64_t **n);
/**
- * @param selector associate the object with this "tag"
- * @param i which object should be returned
+ * Offer a number.
*
- * @return the trait, to be put in the traits array of the command
+ * @param index the number's index number.
+ * @param n the number to offer.
+ *
+ * @return #GNUNET_OK on success.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_uint
@@ -1144,13 +1383,13 @@ TALER_TESTING_make_trait_uint
const unsigned int *i);
/**
- * Obtain a "number" value from @a cmd.
+ * Obtain a number from @a cmd.
*
- * @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- * offer
+ * @param cmd command to extract the number from.
+ * @param index the number's index number.
* @param n[out] set to the number coming from @a cmd.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_uint
@@ -1185,10 +1424,14 @@ struct FreshCoin
};
/**
- * @param selector associate the object with this "tag"
- * @param fresh_coins array of fresh coins to return
+ * Offer a _array_ of fresh coins.
+ *
+ * @param index which array of fresh coins to offer,
+ * if there are multiple on offer. Tipically passed as
+ * zero.
+ * @param fresh_coins the array of fresh coins to offer
*
- * @return the trait, to be put in the traits array of the command
+ * @return the trait,
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_fresh_coins
@@ -1196,13 +1439,14 @@ TALER_TESTING_make_trait_fresh_coins
struct FreshCoin *fresh_coins);
/**
- * Obtain a "number" value from @a cmd.
+ * Get a array of fresh coins.
*
- * @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- * offer
- * @param fresh_coins[out] will point to array of fresh coins
- * @return #GNUNET_OK on success
+ * @param cmd command to extract the fresh coin from.
+ * @param index which array to pick if @a cmd has multiple
+ * on offer.
+ * @param fresh_coins[out] will point to the offered array.
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_fresh_coins
@@ -1210,17 +1454,15 @@ TALER_TESTING_get_trait_fresh_coins
unsigned int index,
struct FreshCoin **fresh_coins);
-
-
/**
* Obtain contract terms from @a cmd.
*
- * @param cmd command to extract trait from
- * @param index always (?) zero, as one command sticks
- * to one bank account
+ * @param cmd command to extract the contract terms from.
+ * @param index contract terms index number.
* @param contract_terms[out] where to write the contract
* terms.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_contract_terms
@@ -1229,10 +1471,12 @@ TALER_TESTING_get_trait_contract_terms
const char **contract_terms);
/**
- * @param index always (?) zero, as one command sticks
- * to one bank account
- * @param contract_terms contract terms to offer
- * @return the trait, to be put in the traits array of the command
+ * Offer contract terms.
+ *
+ * @param index contract terms index number.
+ * @param contract_terms contract terms to offer.
+ *
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_contract_terms
@@ -1243,11 +1487,13 @@ TALER_TESTING_make_trait_contract_terms
/**
* Obtain wire details from @a cmd.
*
- * @param cmd command to extract trait from
- * @param index always (?) zero, as one command sticks
- * to one bank account
+ * @param cmd command to extract the wire details from.
+ * @param index index number associate with the wire details
+ * on offer; usually zero, as one command sticks to
+ * one bank account.
* @param wire_details[out] where to write the wire details.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_wire_details
@@ -1259,10 +1505,12 @@ TALER_TESTING_get_trait_wire_details
/**
* Offer wire details in a trait.
*
- * @param index always (?) zero, as one command sticks
- * to one bank account
- * @param wire_details wire details to offer
- * @return the trait, to be put in the traits array of the command
+ * @param index index number associate with the wire details
+ * on offer; usually zero, as one command sticks to
+ * one bank account.
+ * @param wire_details wire details to offer.
+ *
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_wire_details
@@ -1273,12 +1521,12 @@ TALER_TESTING_make_trait_wire_details
* Obtain a private key from a "peer". Used e.g. to obtain
* a merchant's priv to sign a /track request.
*
- * @param index (tipically zero) which key to return if they
- * exist in an array.
- * @param selector which coin to pick if @a cmd has multiple on
- * offer
+ * @param cmd command that is offering the key.
+ * @param index (tipically zero) which key to return if there
+ * are multiple on offer.
* @param priv[out] set to the key coming from @a cmd.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_peer_key
@@ -1286,13 +1534,15 @@ TALER_TESTING_get_trait_peer_key
unsigned int index,
const struct GNUNET_CRYPTO_EddsaPrivateKey **priv);
-
/**
- * @param index (tipically zero) which key to return if they
- * exist in an array.
- * @param priv which object should be returned
+ * Offer private key, typically done when CMD_1 needs it to
+ * sign a request.
+ *
+ * @param index (tipically zero) which key to return if there are
+ * multiple on offer.
+ * @param priv which object should be offered.
*
- * @return the trait, to be put in the traits array of the command
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_peer_key
@@ -1304,10 +1554,12 @@ TALER_TESTING_make_trait_peer_key
* Obtain a public key from a "peer". Used e.g. to obtain
* a merchant's public key to use backend's API.
*
- * @param index (tipically zero) which key to return if they
- * exist in an array.
+ * @param cmd command offering the key.
+ * @param index (tipically zero) which key to return if there
+ * are multiple on offer.
* @param pub[out] set to the key coming from @a cmd.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_peer_key_pub
@@ -1316,11 +1568,14 @@ TALER_TESTING_get_trait_peer_key_pub
const struct GNUNET_CRYPTO_EddsaPublicKey **pub);
/**
- * @param index (tipically zero) which key to return if they
- * exist in an array.
- * @param pub which object should be returned
+ * Offer public key.
+ *
+ * @param index (tipically zero) which key to return if there
+ * are multiple on offer. NOTE: if one key is offered, it
+ * is mandatory to set this as zero.
+ * @param pub which object should be returned.
*
- * @return the trait, to be put in the traits array of the command
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_peer_key_pub
@@ -1330,11 +1585,13 @@ TALER_TESTING_make_trait_peer_key_pub
/**
* Obtain a transfer subject from @a cmd.
*
- * @param cmd command to extract trait from
- * @param index always (?) zero, as one command sticks
- * to one bank transfer
- * @param transfer_subject[out] where to write the wire details.
- * @return #GNUNET_OK on success
+ * @param cmd command to extract the subject from.
+ * @param index index number associated with the transfer
+ * subject to offer.
+ * @param transfer_subject[out] where to write the offered
+ * transfer subject.
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_transfer_subject
@@ -1344,12 +1601,13 @@ TALER_TESTING_get_trait_transfer_subject
/**
- * Offer wire wire transfer subject in a trait.
+ * Offer transfer subject.
+ *
+ * @param index index number associated with the transfer
+ * subject being offered.
+ * @param transfer_subject transfer subject to offer.
*
- * @param index always (?) zero, as one command sticks
- * to one bank account
- * @param transfer_subject wire transfer subject to offer
- * @return the trait, to be put in the traits array of the command
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_transfer_subject
@@ -1373,10 +1631,12 @@ TALER_TESTING_get_trait_wtid
struct TALER_WireTransferIdentifierRawP **wtid);
/**
- * @param index associate the object with this index
- * @param wtid which object should be returned
+ * Offer a WTID.
*
- * @return the trait, to be put in the traits array of the command
+ * @param index associate the WTID with this index.
+ * @param wtid pointer to the WTID to offer.
+ *
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_wtid
@@ -1387,10 +1647,11 @@ TALER_TESTING_make_trait_wtid
/**
* Offer amount in a trait.
*
- * @param index which amount is to be picked, in case
- * multiple are offered.
- * @param amount the amount to offer
- * @return the trait, to be put in the traits array of the command
+ * @param index which amount is to be offered,
+ * in case multiple are offered.
+ * @param amount the amount to offer.
+ *
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_amount
@@ -1400,11 +1661,12 @@ TALER_TESTING_make_trait_amount
/**
* Obtain an amount from @a cmd.
*
- * @param cmd command to extract trait from
+ * @param cmd command to extract the amount from.
* @param index which amount is to be picked, in case
* multiple are offered.
* @param amount[out] where to write the wire details.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_amount
@@ -1416,10 +1678,11 @@ TALER_TESTING_get_trait_amount
/**
* Offer url in a trait.
*
- * @param index which url is to be picked, in case
- * multiple are offered.
- * @param url the url to offer
- * @return the trait, to be put in the traits array of the command
+ * @param index which url is to be picked,
+ * in case multiple are offered.
+ * @param url the url to offer.
+ *
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_url
@@ -1429,11 +1692,12 @@ TALER_TESTING_make_trait_url
/**
* Obtain a url from @a cmd.
*
- * @param cmd command to extract trait from
+ * @param cmd command to extract the url from.
* @param index which url is to be picked, in case
* multiple are offered.
- * @param amount[out] where to write the url.
- * @return #GNUNET_OK on success
+ * @param url[out] where to write the url.
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_url
@@ -1445,11 +1709,12 @@ TALER_TESTING_get_trait_url
/**
* Obtain a order id from @a cmd.
*
- * @param cmd command to extract trait from
+ * @param cmd command to extract the order id from.
* @param index which order id is to be picked, in case
* multiple are offered.
* @param order_id[out] where to write the order id.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_order_id
@@ -1460,10 +1725,11 @@ TALER_TESTING_get_trait_order_id
/**
* Offer order id in a trait.
*
- * @param index which order id is to be picked, in case
- * multiple are offered.
- * @param order_id the url to offer
- * @return the trait, to be put in the traits array of the command
+ * @param index which order id is to be offered,
+ * in case multiple are offered.
+ * @param order_id the order id to offer.
+ *
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_order_id
@@ -1474,47 +1740,58 @@ TALER_TESTING_make_trait_order_id
/**
* Obtain an amount from a @a cmd.
*
- * @param cmd command to extract trait from
- * @param selector which amount to pick if @a cmd has multiple
+ * @param cmd command to extract the amount from.
+ * @param index which amount to pick if @a cmd has multiple
* on offer
- * @param amount[out] set to the amount
+ * @param amount[out] set to the amount.
+ *
* @return #GNUNET_OK on success
*/
int
-TALER_TESTING_get_trait_amount_obj (
- const struct TALER_TESTING_Command *cmd,
- unsigned int index,
- const struct TALER_Amount **amount);
-
+TALER_TESTING_get_trait_amount_obj
+ (const struct TALER_TESTING_Command *cmd,
+ unsigned int index,
+ const struct TALER_Amount **amount);
+/**
+ * Offer amount.
+ *
+ * @param index which amount to offer, in case there are
+ * multiple available.
+ * @param amount the amount to offer.
+ *
+ * @return the trait.
+ */
struct TALER_TESTING_Trait
-TALER_TESTING_make_trait_amount_obj (
- unsigned int index,
- const struct TALER_Amount *amount);
+TALER_TESTING_make_trait_amount_obj
+ (unsigned int index,
+ const struct TALER_Amount *amount);
/**
- * Offer reference to a bank transfer which has been
- * rejected.
+ * Offer a "reject" CMD reference.
*
- * @param index which reference is to be picked, in case
- * multiple are offered.
- * @param rejected_reference the url to offer
- * @return the trait, to be put in the traits array of the command
+ * @param index which reference is to be offered,
+ * in case multiple are offered.
+ * @param rejected_reference the reference to offer.
+ *
+ * @return the trait.
*/
struct TALER_TESTING_Trait
TALER_TESTING_make_trait_rejected
(unsigned int index,
const char *rejected);
+
/**
- * Obtain the reference from a bank transfer which has
- * been rejected.
+ * Obtain the reference to a "reject" CMD. Usually offered
+ * by _rejected_ bank transfers.
*
- * @param cmd command to extract trait from
+ * @param cmd command to extract the reference from.
* @param index which reference is to be picked, in case
* multiple are offered.
- * @param rejected_reference[out] where to write the order id.
- * @return #GNUNET_OK on success
+ * @param rejected_reference[out] where to write the reference.
+ *
+ * @return #GNUNET_OK on success.
*/
int
TALER_TESTING_get_trait_rejected
--
To stop receiving notification emails like this one, please contact
address@hidden