From 899f2b4070ec04af0e0040f6b7fa62d3d860ffee Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 14 Sep 2015 15:29:40 +0200 Subject: implement /wire api (#3947) --- src/include/taler_mint_service.h | 82 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) (limited to 'src/include') diff --git a/src/include/taler_mint_service.h b/src/include/taler_mint_service.h index 02407a3a9..3f89b0745 100644 --- a/src/include/taler_mint_service.h +++ b/src/include/taler_mint_service.h @@ -353,6 +353,88 @@ TALER_MINT_get_denomination_key (const struct TALER_MINT_Keys *keys, const struct TALER_DenominationPublicKey *pk); +/* ********************* /wire *********************** */ + + +/** + * @brief A Wire format inquiry handle + */ +struct TALER_MINT_WireHandle; + + +/** + * Callbacks of this type are used to serve the result of submitting a + * wire format inquiry request to a mint. + * + * The callback is invoked multiple times, once for each supported @a + * method. Finally, it is invoked one more time with cls/0/NULL/NULL + * to indicate the end of the iteration. If any request fails to + * generate a valid response from the mint, @a http_status will also + * be zero and the iteration will also end. Thus, the iteration + * always ends with a final call with an @a http_status of 0. If the + * @a http_status is already 0 on the first call, then the response to + * the /wire request was invalid. Later, clients can tell the + * difference between @a http_status of 0 indicating a failed + * /wire/method request and a regular end of the iteration by @a + * method being non-NULL. If the mint simply correctly asserts that + * it does not support any methods, @a method will be NULL but the @a + * http_status will be #MHD_HTTP_OK for the first call (followed by a + * cls/0/NULL/NULL call to signal the end of the iteration). + * + * @param cls closure + * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful request; + * 0 if the mint's reply is bogus (fails to follow the protocol) + * @param method wire format method supported, i.e. "test" or "sepa", or NULL + * if already the /wire request failed. + * @param obj the received JSON reply, if successful this should be the wire + * format details as provided by /wire/METHOD/, or NULL if the + * reply was not in JSON format (in this case, the client might + * want to do an HTTP request to /wire/METHOD/ with a browser to + * provide more information to the user about the @a method). + */ +typedef void +(*TALER_MINT_WireResultCallback) (void *cls, + unsigned int http_status, + const char *method, + json_t *obj); + + +/** + * Obtain information about a mint's wire instructions. + * A mint may provide wire instructions for creating + * a reserve. The wire instructions also indicate + * which wire formats merchants may use with the mint. + * This API is typically used by a wallet for wiring + * funds, and possibly by a merchant to determine + * supported wire formats. + * + * Note that while we return the (main) response verbatim to the + * caller for further processing, we do already verify that the + * response is well-formed (i.e. that signatures included in the + * response are all valid). If the mint's reply is not well-formed, + * we return an HTTP status code of zero to @a cb. + * + * @param mint the mint handle; the mint must be ready to operate + * @param wire_cb the callback to call when a reply for this request is available + * @param wire_cb_cls closure for the above callback + * @return a handle for this request + */ +struct TALER_MINT_WireHandle * +TALER_MINT_wire (struct TALER_MINT_Handle *mint, + TALER_MINT_WireResultCallback wire_cb, + void *wire_cb_cls); + + +/** + * Cancel a wire information request. This function cannot be used + * on a request handle if a response is already served for it. + * + * @param wh the wire information request handle + */ +void +TALER_MINT_wire_cancel (struct TALER_MINT_WireHandle *wh); + + /* ********************* /deposit *********************** */ -- cgit v1.2.3