diff options
Diffstat (limited to 'src/include/taler_extensions.h')
| -rw-r--r-- | src/include/taler_extensions.h | 149 |
1 files changed, 130 insertions, 19 deletions
diff --git a/src/include/taler_extensions.h b/src/include/taler_extensions.h index b2d25678..5a5841e5 100644 --- a/src/include/taler_extensions.h +++ b/src/include/taler_extensions.h @@ -53,6 +53,10 @@ struct TALER_Extensions const struct TALER_Extension *extension; }; +/* Forward declarations */ +enum TALER_PolicyFulfilmentState; +struct TALER_PolicyFulfilmentOutcome; + /* * @brief Represents the implementation of an extension. * @@ -159,6 +163,7 @@ struct TALER_Extension * Policy related handlers * ========================= */ + /** * @brief Handler to check a policy. Can be NULL; * @@ -166,44 +171,55 @@ struct TALER_Extension * (see https://docs.taler.net/core/api-exchange.html#deposit), this handler * will be called before the deposit transaction. * - * @param[in] policy_details Details about the policy, provided by the client - * during a deposit request. + * @param[in] policy_details Details about the policy, provided by the client + * during a deposit request. * @param[out] serial On success, will contain the serial-ID under which the - * exchange should save the policy_details in the deposit table. + * exchange should save the policy_details in the deposit table. * @param[out] deadline On success, set to the deadline until the policy must - * be fulfilled. Might be "forever". This value is used by an external + * be fulfilled. Might be "forever". This value is used by an + * external mechanism to detect timeouts. + * @param[out] state_on_timeout On GNUNET_OK, which state shall the + * fulfilment of this policy be put in. MUST be either + * TALER_PolicyFulfilmentTimeoutTransfer or + * TALER_PolicyFulfilmentTimeoutRefreshable * @param[out] error_hint On error, will contain a hint - * mechanism to detect timeouts. - * @return GNUNET_OK if the data was accepted by the extension. + * @return GNUNET_OK if the data was accepted by the extension. */ enum GNUNET_GenericReturnValue (*parse_policy_details)( const json_t *policy_details, struct GNUNET_HashCode *serial, struct GNUNET_TIME_Timestamp *deadline, + enum TALER_PolicyFulfilmentState *state_on_timeout, const char **error_hint); /** - * @brief Handler for POST-requests to the /policy/$name endpoint. Can be NULL. + * @brief Handler for POST-requests to the /extensions/$name endpoint. Can be NULL. * - * @param connection The current connection - * @param root The JSON body from the request - * @param args Additional query parameters of the request. - * @return MDH result + * @param[in] root The JSON body from the request + * @param[in] args Additional query parameters of the request. + * @param[in] serial_id_check Helper function to check the presence of serial_ids in policy_details. Can be used by the handler to ensure the presence of entries before starting calculations. + * @param[out] outcome Result of the operation. Must be freed via TALER_policy_fulfilment_outcome_free after use. + * @param[out] output JSON output to return to the client + * @return GNUNET_OK on success. */ - MHD_RESULT (*http_post_handler)( - struct MHD_Connection *connection, + enum GNUNET_GenericReturnValue (*policy_post_handler)( const json_t *root, - const char *const args[]); + const char *const args[], + enum GNUNET_GenericReturnValue (*serial_id_check)(struct GNUNET_HashCode + serial_ids[], size_t + size), + struct TALER_PolicyFulfilmentOutcome **outcome, + json_t **output); /** - * @brief Handler for GET-requests to the /policy/$name endpoint. Can be NULL. + * @brief Handler for GET-requests to the /extensions/$name endpoint. Can be NULL. * * @param connection The current connection * @param root The JSON body from the request * @param args Additional query parameters of the request. * @return MDH result */ - MHD_RESULT (*http_get_handler)( + MHD_RESULT (*policy_get_handler)( struct MHD_Connection *connection, const char *const args[]); }; @@ -382,28 +398,123 @@ TALER_extensions_get_age_restriction_mask (); /* * =================================== - * Policy extensions related functions + * Policy extensions related API * =================================== */ + +/* + * @brief Describes the states of fulfilment of a policy bound to a deposit + */ +enum TALER_PolicyFulfilmentState +{ + /* Initial state of the policy */ + TALER_PolicyFulfilmentPending = 0, + + /* + * Policy provably fulfilled. The semantics of the policy require that + * the exchange MUST transfer amount in the associated deposit to the + * payto-URI */ + TALER_PolicyFulfilmentSuccessTransfer = 1, + + /* + * Policy provably fulfilled. The semantics of the policy require that + * the coins' value in the associated deposit remains and the owner can + * refresh them. */ + TALER_PolicyFulfilmentSuccessRefreshable = 2, + + /* + * Policy provably UNfulfilled. The semantics of the policy require + * that the exchange MUST transfer amount in the associated deposit to + * the payto-URI. */ + TALER_PolicyFulfilmentFailureTransfer = 3, + + /* + * Policy provably UNfulfilled. The semantics of the policy require that + * the coins' value in the associated deposit remains and the owner can + * refresh them. */ + TALER_PolicyFulfilmentFailureRefreshable = 4, + + /* + * Policy timed out. The semantics of the policy require that the + * exchange MUST transfer amount in the associated deposit to the + * payto-URI. */ + TALER_PolicyFulfilmentTimeoutTransfer = 5, + + /* + * Policy timed out. The semantics of the policy require that the + * coins' value in the associated deposit remains and the owner can + * refresh them. */ + TALER_PolicyFulfilmentTimeoutRefreshable = 6, + + TALER_PolicyFulfilmentStateMax = TALER_PolicyFulfilmentTimeoutRefreshable +}; + + +const char * +TALER_policy_fulfilment_state_str (enum TALER_PolicyFulfilmentState state); + +/* + * @brief Respresents the outcome of a policy fulfilment evaluation + * returned by a http_post_handler. + */ +struct TALER_PolicyFulfilmentOutcome +{ + size_t len; + struct TALER_PolicyFulfilmentOutcomePosition + { + /* Identifies the particular policy in the policy_details */ + struct GNUNET_HashCode serial_id; + + /* The state that the policy should be be put into. */ + enum TALER_PolicyFulfilmentState state; + + /* If @e has_new_amount is true, the actual amount to be transfered + * according to the @e state is not taken from the associated deposit + * entry, but provided with @new_amount + */ + bool has_new_amount; + struct TALER_Amount new_amount; + + } *positions; +}; + + /* - * @brief Finds the extension for a given policy + * @brief allocate a TALER_PolicyFulfilmentOutcome + */ +struct TALER_PolicyFulfilmentOutcome * +TALER_policy_fulfilment_outcome_new (size_t len); + +/* + * @brief free the content of a TALER_PolicyFulfilmentOutcome + */ +void +TALER_policy_fulfilment_outcome_free ( + struct TALER_PolicyFulfilmentOutcome *outcome); + + +/* + * @brief Extracts meta information from policy_details * * @param[in] policy_details JSON of the policy detail from a deposit request * @param[out] serial On GNUNET_OK, the hash code that should be used to save the policy_details in the policy_details table * @param[out] deadline On GNUNET_OK, the deadline that should be saved in the policy_details table + * @param[out] state_on_timeout On GNUNET_OK, which state shall the fulfilment of this policy be put in * @param[out] error_hint On GNUNET_SYSERR, will contain a hint for the reason why it failed * @return GNUNET_OK on success, with *extension set to the correct extension. * GNUNET_NO, when no extension was found. GNUNET_SYSERR when the JSON was * invalid, with *error_hint maybe non-NULL. */ enum GNUNET_GenericReturnValue -TALER_extensions_serial_from_policy_details ( +TALER_extensions_extract_meta_data_from_policy_details ( const json_t *policy_details, struct GNUNET_HashCode *serial, struct GNUNET_TIME_Timestamp *deadline, + enum TALER_PolicyFulfilmentState *state_on_timeout, const char **error_hint); + /* * ================================ * Merchant refund policy |