diff options
Diffstat (limited to 'src/include/taler_bank_service.h')
-rw-r--r-- | src/include/taler_bank_service.h | 333 |
1 files changed, 254 insertions, 79 deletions
diff --git a/src/include/taler_bank_service.h b/src/include/taler_bank_service.h index 0212e61f1..e8e32947b 100644 --- a/src/include/taler_bank_service.h +++ b/src/include/taler_bank_service.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2015-2020 Taler Systems SA + Copyright (C) 2015-2021 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 @@ -100,24 +100,64 @@ struct TALER_BANK_AdminAddIncomingHandle; /** + * Response details for a history request. + */ +struct TALER_BANK_AdminAddIncomingResponse +{ + + /** + * HTTP status. + */ + unsigned int http_status; + + /** + * Taler error code, #TALER_EC_NONE on success. + */ + enum TALER_ErrorCode ec; + + /** + * Full response, NULL if body was not in JSON format. + */ + const json_t *response; + + /** + * Details returned depending on the @e http_status. + */ + union + { + + /** + * Details if status was #MHD_HTTP_OK + */ + struct + { + /** + * unique ID of the wire transfer in the bank's records + */ + uint64_t serial_id; + + /** + * time when the transaction was made. + */ + struct GNUNET_TIME_Timestamp timestamp; + + } ok; + + } details; + +}; + +/** * Callbacks of this type are used to return the result of submitting * a request to transfer funds to the exchange. * * @param cls closure - * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request - * 0 if the bank's reply is bogus (fails to follow the protocol) - * @param ec detailed error code - * @param serial_id unique ID of the wire transfer in the bank's records; UINT64_MAX on error - * @param timestamp time when the transaction was made. - * @param json detailed response from the HTTPD, or NULL if reply was not in JSON + * @param air response details */ typedef void -(*TALER_BANK_AdminAddIncomingCallback) (void *cls, - unsigned int http_status, - enum TALER_ErrorCode ec, - uint64_t serial_id, - struct GNUNET_TIME_Absolute timestamp, - const json_t *json); +(*TALER_BANK_AdminAddIncomingCallback) ( + void *cls, + const struct TALER_BANK_AdminAddIncomingResponse *air); /** @@ -190,20 +230,64 @@ struct TALER_BANK_TransferHandle; /** + * Response details for a history request. + */ +struct TALER_BANK_TransferResponse +{ + + /** + * HTTP status. + */ + unsigned int http_status; + + /** + * Taler error code, #TALER_EC_NONE on success. + */ + enum TALER_ErrorCode ec; + + /** + * Full response, NULL if body was not in JSON format. + */ + const json_t *response; + + /** + * Details returned depending on the @e http_status. + */ + union + { + + /** + * Details if status was #MHD_HTTP_OK + */ + struct + { + + + /** + * unique ID of the wire transfer in the bank's records + */ + uint64_t row_id; + + /** + * when did the transaction go into effect + */ + struct GNUNET_TIME_Timestamp timestamp; + + } ok; + } details; +}; + + +/** * Function called with the result from the execute step. * * @param cls closure - * @param response_code HTTP status code - * @param ec taler error code - * @param row_id unique ID of the wire transfer in the bank's records - * @param timestamp when did the transaction go into effect + * @param tr response details */ typedef void -(*TALER_BANK_TransferCallback)(void *cls, - unsigned int response_code, - enum TALER_ErrorCode ec, - uint64_t row_id, - struct GNUNET_TIME_Absolute timestamp); +(*TALER_BANK_TransferCallback)( + void *cls, + const struct TALER_BANK_TransferResponse *tr); /** @@ -259,6 +343,11 @@ struct TALER_BANK_CreditHistoryHandle; struct TALER_BANK_CreditDetails { /** + * Serial ID of the wire transfer. + */ + uint64_t serial_id; + + /** * Amount that was transferred */ struct TALER_Amount amount; @@ -266,25 +355,75 @@ struct TALER_BANK_CreditDetails /** * Time of the the transfer */ - struct GNUNET_TIME_Absolute execution_date; + struct GNUNET_TIME_Timestamp execution_date; /** - * Reserve public key encoded in the wire - * transfer subject. + * Reserve public key encoded in the wire transfer subject. */ struct TALER_ReservePublicKeyP reserve_pub; /** - * payto://-URL of the source account that - * send the funds. + * payto://-URL of the source account that send the funds. + */ + const char *debit_account_uri; + +}; + + +/** + * Response details for a history request. + */ +struct TALER_BANK_CreditHistoryResponse +{ + + /** + * HTTP status. Note that #MHD_HTTP_OK and #MHD_HTTP_NO_CONTENT are both + * successful replies, but @e details will only contain @e success information + * if this is set to #MHD_HTTP_OK. + */ + unsigned int http_status; + + /** + * Taler error code, #TALER_EC_NONE on success. */ - const char *debit_account_url; + enum TALER_ErrorCode ec; /** - * payto://-URL of the target account that - * received the funds. + * Full response, NULL if body was not in JSON format. */ - const char *credit_account_url; + const json_t *response; + + /** + * Details returned depending on the @e http_status. + */ + union + { + + /** + * Details if status was #MHD_HTTP_OK + */ + struct + { + + /** + * payto://-URL of the target account that received the funds. + */ + const char *credit_account_uri; + + /** + * Array of transactions received. + */ + const struct TALER_BANK_CreditDetails *details; + + /** + * Length of the @e details array. + */ + unsigned int details_length; + + } ok; + + } details; + }; @@ -293,25 +432,12 @@ struct TALER_BANK_CreditDetails * the bank for the credit transaction history. * * @param cls closure - * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request - * 0 if the bank's reply is bogus (fails to follow the protocol), - * #MHD_HTTP_NO_CONTENT if there are no more results; on success the - * last callback is always of this status (even if `abs(num_results)` were - * already returned). - * @param ec detailed error code - * @param serial_id monotonically increasing counter corresponding to the transaction - * @param details details about the wire transfer - * @param json detailed response from the HTTPD, or NULL if reply was not in JSON - * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration + * @param reply details about the response */ -typedef int -(*TALER_BANK_CreditHistoryCallback) ( +typedef void +(*TALER_BANK_CreditHistoryCallback)( void *cls, - unsigned int http_status, - enum TALER_ErrorCode ec, - uint64_t serial_id, - const struct TALER_BANK_CreditDetails *details, - const json_t *json); + const struct TALER_BANK_CreditHistoryResponse *reply); /** @@ -323,6 +449,8 @@ typedef int * @param num_results how many results do we want; negative numbers to go into the past, * positive numbers to go into the future starting at @a start_row; * must not be zero. + * @param timeout how long the client is willing to wait for more results + * (only useful if @a num_results is positive) * @param hres_cb the callback to call with the transaction history * @param hres_cb_cls closure for the above callback * @return NULL @@ -330,12 +458,14 @@ typedef int * In this case, the callback is not called. */ struct TALER_BANK_CreditHistoryHandle * -TALER_BANK_credit_history (struct GNUNET_CURL_Context *ctx, - const struct TALER_BANK_AuthenticationData *auth, - uint64_t start_row, - int64_t num_results, - TALER_BANK_CreditHistoryCallback hres_cb, - void *hres_cb_cls); +TALER_BANK_credit_history ( + struct GNUNET_CURL_Context *ctx, + const struct TALER_BANK_AuthenticationData *auth, + uint64_t start_row, + int64_t num_results, + struct GNUNET_TIME_Relative timeout, + TALER_BANK_CreditHistoryCallback hres_cb, + void *hres_cb_cls); /** @@ -364,6 +494,11 @@ struct TALER_BANK_DebitHistoryHandle; struct TALER_BANK_DebitDetails { /** + * Serial ID of the wire transfer. + */ + uint64_t serial_id; + + /** * Amount that was transferred */ struct TALER_Amount amount; @@ -371,7 +506,7 @@ struct TALER_BANK_DebitDetails /** * Time of the the transfer */ - struct GNUNET_TIME_Absolute execution_date; + struct GNUNET_TIME_Timestamp execution_date; /** * Wire transfer identifier used by the exchange. @@ -384,16 +519,66 @@ struct TALER_BANK_DebitDetails const char *exchange_base_url; /** - * payto://-URL of the source account that - * send the funds. + * payto://-URI of the target account that received the funds. */ - const char *debit_account_url; + const char *credit_account_uri; + +}; + + +/** + * Response details for a history request. + */ +struct TALER_BANK_DebitHistoryResponse +{ /** - * payto://-URL of the target account that - * received the funds. + * HTTP status. Note that #MHD_HTTP_OK and #MHD_HTTP_NO_CONTENT are both + * successful replies, but @e details will only contain @e success information + * if this is set to #MHD_HTTP_OK. */ - const char *credit_account_url; + unsigned int http_status; + + /** + * Taler error code, #TALER_EC_NONE on success. + */ + enum TALER_ErrorCode ec; + + /** + * Full response, NULL if body was not in JSON format. + */ + const json_t *response; + + /** + * Details returned depending on the @e http_status. + */ + union + { + + /** + * Details if status was #MHD_HTTP_OK + */ + struct + { + + /** + * payto://-URI of the source account that send the funds. + */ + const char *debit_account_uri; + + /** + * Array of transactions initiated. + */ + const struct TALER_BANK_DebitDetails *details; + + /** + * Length of the @e details array. + */ + unsigned int details_length; + + } ok; + + } details; }; @@ -403,25 +588,12 @@ struct TALER_BANK_DebitDetails * the bank for the debit transaction history. * * @param cls closure - * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request - * 0 if the bank's reply is bogus (fails to follow the protocol), - * #MHD_HTTP_NO_CONTENT if there are no more results; on success the - * last callback is always of this status (even if `abs(num_results)` were - * already returned). - * @param ec detailed error code - * @param serial_id monotonically increasing counter corresponding to the transaction - * @param details details about the wire transfer - * @param json detailed response from the HTTPD, or NULL if reply was not in JSON - * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration + * @param reply details about the response */ -typedef int -(*TALER_BANK_DebitHistoryCallback) ( +typedef void +(*TALER_BANK_DebitHistoryCallback)( void *cls, - unsigned int http_status, - enum TALER_ErrorCode ec, - uint64_t serial_id, - const struct TALER_BANK_DebitDetails *details, - const json_t *json); + const struct TALER_BANK_DebitHistoryResponse *reply); /** @@ -433,6 +605,8 @@ typedef int * @param num_results how many results do we want; negative numbers to go into the past, * positive numbers to go into the future starting at @a start_row; * must not be zero. + * @param timeout how long the client is willing to wait for more results + * (only useful if @a num_results is positive) * @param hres_cb the callback to call with the transaction history * @param hres_cb_cls closure for the above callback * @return NULL @@ -444,6 +618,7 @@ TALER_BANK_debit_history (struct GNUNET_CURL_Context *ctx, const struct TALER_BANK_AuthenticationData *auth, uint64_t start_row, int64_t num_results, + struct GNUNET_TIME_Relative timeout, TALER_BANK_DebitHistoryCallback hres_cb, void *hres_cb_cls); @@ -471,7 +646,7 @@ TALER_BANK_debit_history_cancel (struct TALER_BANK_DebitHistoryHandle *hh); * @param[out] auth set to the configuration data found * @return #GNUNET_OK on success */ -int +enum GNUNET_GenericReturnValue TALER_BANK_auth_parse_cfg (const struct GNUNET_CONFIGURATION_Handle *cfg, const char *section, struct TALER_BANK_AuthenticationData *auth); |