From 1ecef98609edef609a41cdae98fe4bfbfeb95b23 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Mon, 28 May 2018 13:27:54 +0200 Subject: Commenting the "deposit" CMD. --- src/exchange-lib/testing_api_cmd_deposit.c | 82 ++++++++++++++++-------------- 1 file changed, 44 insertions(+), 38 deletions(-) diff --git a/src/exchange-lib/testing_api_cmd_deposit.c b/src/exchange-lib/testing_api_cmd_deposit.c index 5854bf8ba..70d41a395 100644 --- a/src/exchange-lib/testing_api_cmd_deposit.c +++ b/src/exchange-lib/testing_api_cmd_deposit.c @@ -30,6 +30,10 @@ #include "taler_testing_lib.h" #include "taler_signatures.h" + +/** + * State for a "deposit" CMD. + */ struct DepositState { @@ -44,13 +48,14 @@ struct DepositState const char *coin_reference; /** - * If this @e coin_ref refers to an operation that generated + * If @e coin_reference refers to an operation that generated * an array of coins, this value determines which coin to pick. */ unsigned int coin_index; /** - * payto://-URL of the merchant's bank account. + * Wire details of who is depositing -- this would be merchant + * wire details in a normal scenario. */ json_t *wire_details; @@ -66,7 +71,8 @@ struct DepositState struct GNUNET_TIME_Relative refund_deadline; /** - * Set (by the interpreter) to a fresh private key. + * Set (by the interpreter) to a fresh private key. This + * key will be used to sign the deposit request. */ struct TALER_MerchantPrivateKeyP merchant_priv; @@ -92,16 +98,15 @@ struct DepositState }; /** - * Function called with the result of a /deposit operation. + * Callback to analyze the /deposit response, just used to + * check if the response code is acceptable. * - * @param cls closure with the interpreter state - * @param http_status HTTP response code, #MHD_HTTP_OK (200) for - * successful deposit; 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 exchange_pub public key the exchange used for signing - * @param obj the received JSON reply, should be kept as proof - * (and, in case of errors, be forwarded to the customer) + * @param cls closure. + * @param http_status HTTP response code. + * @param ec taler-specific error code. + * @param exchange_pub public key of the exchange, + * used for signing the response. + * @param obj raw response from the exchange. */ static void deposit_cb (void *cls, @@ -130,9 +135,9 @@ deposit_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. */ static void deposit_run (void *cls, @@ -252,9 +257,10 @@ deposit_run (void *cls, dr.purpose.purpose = htonl (TALER_SIGNATURE_WALLET_COIN_DEPOSIT); dr.h_contract_terms = h_contract_terms; - GNUNET_assert (GNUNET_OK == - TALER_JSON_wire_signature_hash (ds->wire_details, - &dr.h_wire)); + GNUNET_assert + (GNUNET_OK == + TALER_JSON_wire_signature_hash (ds->wire_details, + &dr.h_wire)); dr.timestamp = GNUNET_TIME_absolute_hton (timestamp); dr.refund_deadline = GNUNET_TIME_absolute_hton (refund_deadline); @@ -295,7 +301,8 @@ deposit_run (void *cls, /** - * Cleanup the state. + * Free the state of a "deposit" CMD, and possibly cancel a + * pending operation thereof. * * @param cls closure, typically a #struct WireState. * @param cmd the command which is being cleaned up. @@ -322,16 +329,16 @@ deposit_cleanup (void *cls, /** - * Extract information from a command that is useful for other - * commands. + * Offer internal data from a "deposit" CMD, to other commands. * - * @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 deposit_traits (void *cls, @@ -378,26 +385,25 @@ deposit_traits (void *cls, } /** - * 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. * This value is currently ignored, as only one-coin * withdrawals are implemented. - * @param wire_details JSON details of the wire account 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, zero means 'no refunds' - * @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 -- cgit v1.2.3