From a93b4e9edbe7fbdc7400aaa9e5deff80590b6b66 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Fri, 25 May 2018 19:58:34 +0200 Subject: Commenting the "refresh"(es) CMDs. --- src/exchange-lib/testing_api_cmd_refresh.c | 198 +++++++++++++++-------------- 1 file changed, 101 insertions(+), 97 deletions(-) (limited to 'src') diff --git a/src/exchange-lib/testing_api_cmd_refresh.c b/src/exchange-lib/testing_api_cmd_refresh.c index 97f06cc30..56b93c1e8 100644 --- a/src/exchange-lib/testing_api_cmd_refresh.c +++ b/src/exchange-lib/testing_api_cmd_refresh.c @@ -31,9 +31,7 @@ #include "taler_signatures.h" /** - * Structure specifying details about a coin to be melted. - * Used in a NULL-terminated array as part of command - * specification. + * Data for a coin to be melted. */ struct MeltDetails { @@ -52,15 +50,15 @@ struct MeltDetails /** - * State for a "refresh melt" operation. + * State for a "refresh melt" command. */ struct RefreshMeltState { /** * if set to GNUNET_YES, then two /refresh/melt operations - * will be performed. This is needed to trigger the code - * path that manages those already-made requests. Note: it + * will be performed. This is needed to trigger the logic + * that manages those already-made requests. Note: it * is not possible to just copy-and-paste a test refresh melt * CMD to have the same effect, because every data preparation * generates new planchets that (in turn) make the whole "hash" @@ -71,7 +69,8 @@ struct RefreshMeltState unsigned int double_melt; /** - * Fixme: figure out this data purpose. + * Amount to be melted. FIXME: this value is useless + * here as the @a melted_coin field (below) has already it. */ const char *amount; @@ -81,7 +80,7 @@ struct RefreshMeltState struct MeltDetails melted_coin; /** - * Data used in the refresh operation. + * "Crypto data" used in the refresh operation. */ char *refresh_data; @@ -116,20 +115,19 @@ struct RefreshMeltState unsigned int expected_response_code; /** - * Array of the public keys corresponding to - * the @e fresh_amounts, set by the interpreter. + * Array of the denomination public keys + * corresponding to the @e fresh_amounts. */ struct TALER_EXCHANGE_DenomPublicKey *fresh_pks; /** - * Set by the interpreter (upon completion) to the - * noreveal index selected by the exchange. + * Set by the melt callback as it comes from the exchange. */ uint16_t noreveal_index; }; /** - * State for a "refresh reveal" operation. + * State for a "refresh reveal" CMD. */ struct RefreshRevealState { @@ -144,13 +142,16 @@ struct RefreshRevealState struct TALER_EXCHANGE_RefreshRevealHandle *rrh; /** - * Number of fresh coins withdrawn, set by the interpreter. - * Length of the @e fresh_coins array. + * Number of fresh coins withdrawn, set by the + * reveal callback as it comes from the exchange, + * it is the length of the @e fresh_coins array. */ unsigned int num_fresh_coins; /** - * Information about coins withdrawn, set by the interpreter. + * Convenience struct to keep in one place all the + * data related to one fresh coin, set by the reveal callback + * as it comes from the exchange. */ struct FreshCoin *fresh_coins; @@ -171,7 +172,7 @@ struct RefreshRevealState }; /** - * State for a "refresh link" operation. + * State for a "refresh link" CMD. */ struct RefreshLinkState { @@ -181,7 +182,7 @@ struct RefreshLinkState const char *reveal_reference; /** - * Link handle while operation is running. + * Handle to the ongoing operation. */ struct TALER_EXCHANGE_RefreshLinkHandle *rlh; @@ -203,22 +204,21 @@ struct RefreshLinkState /** - * Function called with the result of the /refresh/reveal operation. + * "refresh reveal" request callback; it checks that the response + * code is expected and copies into its command's state the data + * coming from the exchange, namely the fresh coins. * - * @param cls closure with the interpreter state - * @param http_status HTTP response code, #MHD_HTTP_OK (200) for - * successful status request. 0 if the exchange's reply is - * bogus (fails to follow the protocol) - * @param ec taler-specific error code, #TALER_EC_NONE on success + * @param cls closure. + * @param http_status HTTP response code. + * @param ec taler-specific error code. * @param num_coins number of fresh coins created, length of the * @a sigs and @a coin_privs arrays, 0 if the operation - * failed + * failed. * @param coin_privs array of @a num_coins private keys for the - * coins that were created, NULL on error - * @param sigs array of signature over @a num_coins coins, NULL on - * error - * @param full_response full response from the exchange (for - * logging, in case of errors) + * coins that were created, NULL on error. + * @param sigs array of signature over @a num_coins coins, + * NULL on error. + * @param full_response raw exchange response. */ static void reveal_cb (void *cls, @@ -291,7 +291,7 @@ reveal_cb (void *cls, * Run the command. * * @param cls closure. - * @param cmd the command to execute, a /wire one. + * @param cmd the command to execute. * @param is the interpreter state. */ void @@ -331,7 +331,8 @@ refresh_reveal_run (void *cls, /** - * Cleanup the state. + * Free the state from a "refresh reveal" CMD, and possibly + * cancel a pending operation thereof. * * @param cls closure. * @param cmd the command which is being cleaned up. @@ -353,7 +354,7 @@ refresh_reveal_cleanup (void *cls, rrs->rrh = NULL; } - { /* Not sure why block-ing this */ + { /* FIXME: why block-ing this? */ unsigned int j; for (j=0; j < rrs->num_fresh_coins; j++) @@ -368,23 +369,23 @@ refresh_reveal_cleanup (void *cls, /** - * Function called with the result of a /refresh/link operation. + * "refresh link" operation callback, checks that HTTP response + * code is expected _and_ that all the linked coins were actually + * withdrawn by the "refresh reveal" CMD. * - * @param cls closure with the interpreter state - * @param http_status HTTP response code, #MHD_HTTP_OK (200) for - * successful status request 0 if the exchange's reply is - * bogus (fails to follow the protocol) - * @param ec taler-specific error code, #TALER_EC_NONE on success + * @param cls closure. + * @param http_status HTTP response code. + * @param ec taler-specific error code * @param num_coins number of fresh coins created, length of the * @a sigs and @a coin_privs arrays, 0 if the operation - * failed + * failed. * @param coin_privs array of @a num_coins private keys for the - * coins that were created, NULL on error + * coins that were created, NULL on error. * @param sigs array of signature over @a num_coins coins, NULL on - * error - * @param pubs array of public keys for the @a sigs, NULL on error - * @param full_response full response from the exchange (for - * logging, in case of errors) + * error. + * @param pubs array of public keys for the @a sigs, + * NULL on error. + * @param full_response raw response from the exchange. */ static void link_cb (void *cls, @@ -504,9 +505,9 @@ link_cb (void *cls, /** * Run the command. * - * @param cls closure - * @param cmd the command to execute, a /wire one. - * @param i the interpreter state. + * @param cls closure. + * @param cmd the command to execute. + * @param is the interpreter state. */ void refresh_link_run (void *cls, @@ -581,7 +582,8 @@ refresh_link_run (void *cls, } /** - * Cleanup the state. + * Free the state of the "refresh link" CMD, and possibly + * cancel a operation thereof. * * @param cls closure * @param cmd the command which is being cleaned up. @@ -606,19 +608,17 @@ refresh_link_cleanup (void *cls, /** - * Function called with the result of the /refresh/melt operation. + * Callback for a "refresh melt" operation; checks if the HTTP + * response code is okay and re-run the melt operation if the + * CMD was set to do so. * - * @param cls closure with the interpreter state - * @param http_status HTTP response code, never #MHD_HTTP_OK (200) - * as for successful intermediate response this callback is - * skipped. 0 if the exchange's reply is bogus (fails to - * follow the protocol) - * @param ec taler-specific error code, #TALER_EC_NONE on success + * @param cls closure. + * @param http_status HTTP response code. + * @param ec taler-specific error code. * @param noreveal_index choice by the exchange in the - * cut-and-choose protocol, UINT16_MAX on error - * @param exchange_pub public key the exchange used for signing - * @param full_response full response from the exchange (for - * logging, in case of errors) + * cut-and-choose protocol, UINT16_MAX on error. + * @param exchange_pub public key the exchange used for signing. + * @param full_response raw response body from the exchange. */ static void melt_cb (void *cls, @@ -660,9 +660,9 @@ melt_cb (void *cls, /** * Run the command. * - * @param cls closure, typically a #struct WireState. - * @param cmd the command to execute, a /wire one. - * @param i the interpreter state. + * @param cls closure. + * @param cmd the command to execute. + * @param is the interpreter state. */ void refresh_melt_run (void *cls, @@ -793,7 +793,8 @@ refresh_melt_run (void *cls, } /** - * Cleanup the state. + * Free the "refresh melt" CMD state, and possibly cancel a + * pending operation thereof. * * @param cls closure, typically a #struct RefreshMeltState. * @param cmd the command which is being cleaned up. @@ -820,16 +821,16 @@ refresh_melt_cleanup (void *cls, } /** - * Extract information from a command that is useful for other - * commands. + * Offer internal data to the "refresh melt" CMD. * - * @param cls closure - * @param ret[out] result (could be anything) - * @param trait name of the trait + * @param cls closure. + * @param ret[out] result (could be anything). + * @param trait name of the trait. * @param selector more detailed information about which object * to return in case there were multiple generated - * by the command - * @return #GNUNET_OK on success + * by the command. + * + * @return #GNUNET_OK on success. */ static int refresh_melt_traits (void *cls, @@ -854,14 +855,15 @@ refresh_melt_traits (void *cls, /** * 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, @@ -893,17 +895,19 @@ TALER_TESTING_cmd_refresh_melt } /** - * 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, @@ -936,16 +940,16 @@ TALER_TESTING_cmd_refresh_melt_double } /** - * Extract information from a command that is useful for other - * commands. + * Offer internal data from a "refresh reveal" CMD. * - * @param cls closure - * @param ret[out] result (could be anything) - * @param trait name of the trait + * @param cls closure. + * @param ret[out] result (could be anything). + * @param trait name of the trait. * @param selector more detailed information about which object * to return in case there were multiple generated - * by the command - * @return #GNUNET_OK on success + * by the command. + * + * @return #GNUNET_OK on success. */ static int refresh_reveal_traits (void *cls, @@ -996,12 +1000,12 @@ refresh_reveal_traits (void *cls, /** * 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 @@ -1031,9 +1035,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 -- cgit v1.2.3