308 lines
9.4 KiB
C
308 lines
9.4 KiB
C
/*
|
||
This file is part of TALER
|
||
Copyright (C) 2014, 2015 Christian Grothoff (and other contributing authors)
|
||
|
||
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
|
||
Foundation; either version 3, or (at your option) any later version.
|
||
|
||
TALER is distributed in the hope that it will be useful, but WITHOUT ANY
|
||
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
|
||
A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
|
||
|
||
You should have received a copy of the GNU Affero General Public License along with
|
||
TALER; see the file COPYING. If not, If not, see <http://www.gnu.org/licenses/>
|
||
*/
|
||
/**
|
||
* @file include/taler_mint_service.h
|
||
* @brief C interface of libtalermint, a C library to use mint's HTTP API
|
||
* @author Sree Harsha Totakura <sreeharsha@totakura.in>
|
||
*/
|
||
#ifndef _TALER_MINT_SERVICE_H
|
||
#define _TALER_MINT_SERVICE_H
|
||
|
||
#include "taler_util.h"
|
||
#include <jansson.h>
|
||
|
||
/**
|
||
* Handle to this library context
|
||
*/
|
||
struct TALER_MINT_Context;
|
||
|
||
/**
|
||
* Handle to the mint
|
||
*/
|
||
struct TALER_MINT_Handle;
|
||
|
||
/**
|
||
* Mint's signature key
|
||
*/
|
||
struct TALER_MINT_SigningPublicKey
|
||
{
|
||
/**
|
||
* The signing public key
|
||
*/
|
||
struct TALER_MintPublicKeyP key;
|
||
|
||
/**
|
||
* Validity start time
|
||
*/
|
||
struct GNUNET_TIME_Absolute valid_from;
|
||
|
||
/**
|
||
* Validity expiration time
|
||
*/
|
||
struct GNUNET_TIME_Absolute valid_until;
|
||
};
|
||
|
||
|
||
/**
|
||
* Mint's denomination key
|
||
*/
|
||
struct TALER_MINT_DenomPublicKey
|
||
{
|
||
/**
|
||
* The public key
|
||
*/
|
||
struct TALER_DenominationPublicKey key;
|
||
|
||
/**
|
||
* Timestamp indicating when the denomination key becomes valid
|
||
*/
|
||
struct GNUNET_TIME_Absolute valid_from;
|
||
|
||
/**
|
||
* Timestamp indicating when the denomination key can’t be used anymore to
|
||
* withdraw new coins.
|
||
*/
|
||
struct GNUNET_TIME_Absolute withdraw_valid_until;
|
||
|
||
/**
|
||
* Timestamp indicating when coins of this denomination become invalid.
|
||
*/
|
||
struct GNUNET_TIME_Absolute deposit_valid_until;
|
||
|
||
/**
|
||
* The value of this denomination
|
||
*/
|
||
struct TALER_Amount value;
|
||
|
||
/**
|
||
* The applicable fee for withdrawing a coin of this denomination
|
||
*/
|
||
struct TALER_Amount fee_withdraw;
|
||
|
||
/**
|
||
* The applicable fee to spend a coin of this denomination
|
||
*/
|
||
struct TALER_Amount fee_deposit;
|
||
|
||
/**
|
||
*The applicable fee to refresh a coin of this denomination
|
||
*/
|
||
struct TALER_Amount fee_refresh;
|
||
};
|
||
|
||
|
||
/**
|
||
* Initialise a context. A context should be used for each thread and should
|
||
* not be shared among multiple threads.
|
||
*
|
||
* @return the context
|
||
*/
|
||
struct TALER_MINT_Context *
|
||
TALER_MINT_init (void);
|
||
|
||
|
||
/**
|
||
* Cleanup library initialisation resources. This function should be called
|
||
* after using this library to cleanup the resources occupied during library's
|
||
* initialisation.
|
||
*
|
||
* @param ctx the library context
|
||
*/
|
||
void
|
||
TALER_MINT_cleanup (struct TALER_MINT_Context *ctx);
|
||
|
||
|
||
/**
|
||
* Initialise a connection to the mint.
|
||
*
|
||
* @param ctx the context
|
||
* @param hostname the hostname of the mint
|
||
* @param port the point where the mint's HTTP service is running. If port is
|
||
* given as 0, ports 80 or 443 are chosen depending on @a url.
|
||
* @param master_key the public master key of the mint. This is used to verify the
|
||
* responses of the mint.
|
||
* @return the mint handle; NULL upon error
|
||
*/
|
||
struct TALER_MINT_Handle *
|
||
TALER_MINT_connect (struct TALER_MINT_Context *ctx,
|
||
const char *hostname,
|
||
uint16_t port,
|
||
const struct TALER_MasterPublicKeyP *master_key);
|
||
|
||
/**
|
||
* Disconnect from the mint
|
||
*
|
||
* @param mint the mint handle
|
||
*/
|
||
void
|
||
TALER_MINT_disconnect (struct TALER_MINT_Handle *mint);
|
||
|
||
|
||
/**
|
||
* A handle to get the keys of a mint
|
||
*/
|
||
struct TALER_MINT_KeysGetHandle;
|
||
|
||
/**
|
||
* Functions of this type are called to signal completion of an asynchronous call.
|
||
*
|
||
* @param cls closure
|
||
* @param emsg if the asynchronous call could not be completed due to an error,
|
||
* this parameter contains a human readable error message
|
||
*/
|
||
typedef void
|
||
(*TALER_MINT_ContinuationCallback) (void *cls,
|
||
const char *emsg);
|
||
|
||
/**
|
||
* Functions of this type are called to provide the retrieved signing and
|
||
* denomination keys of the mint. No TALER_MINT_*() functions should be called
|
||
* in this callback.
|
||
*
|
||
* @param cls closure passed to TALER_MINT_keys_get()
|
||
* @param sign_keys NULL-terminated array of pointers to the mint's signing
|
||
* keys. NULL if no signing keys are retrieved.
|
||
* @param denom_keys NULL-terminated array of pointers to the mint's
|
||
* denomination keys; will be NULL if no signing keys are retrieved.
|
||
*/
|
||
typedef void
|
||
(*TALER_MINT_KeysGetCallback) (void *cls,
|
||
struct TALER_MINT_SigningPublicKey **sign_keys,
|
||
struct TALER_MINT_DenomPublicKey **denom_keys);
|
||
|
||
|
||
/**
|
||
* Get the signing and denomination key of the mint.
|
||
*
|
||
* @param mint handle to the mint
|
||
* @param cb the callback to call with the keys
|
||
* @param cb_cls closure for the @a cb callback
|
||
* @param cont_cb the callback to call after completing this asynchronous call
|
||
* @param cont_cls the closure for the @a cont_cb callback
|
||
* @return a handle to this asynchronous call; NULL upon eror
|
||
*/
|
||
struct TALER_MINT_KeysGetHandle *
|
||
TALER_MINT_keys_get (struct TALER_MINT_Handle *mint,
|
||
TALER_MINT_KeysGetCallback cb,
|
||
void *cb_cls,
|
||
TALER_MINT_ContinuationCallback cont_cb,
|
||
void *cont_cls);
|
||
|
||
|
||
/**
|
||
* Cancel the asynchronous call initiated by TALER_MINT_keys_get(). This should
|
||
* not be called if either of the @a TALER_MINT_KeysGetCallback or @a
|
||
* TALER_MINT_ContinuationCallback passed to TALER_MINT_keys_get() have been
|
||
* called.
|
||
*
|
||
* @param get the handle for retrieving the keys
|
||
*/
|
||
void
|
||
TALER_MINT_keys_get_cancel (struct TALER_MINT_KeysGetHandle *get);
|
||
|
||
|
||
/**
|
||
* A Deposit Handle
|
||
*/
|
||
struct TALER_MINT_DepositHandle;
|
||
|
||
|
||
/**
|
||
* Callbacks of this type are used to serve the result of submitting a deposit
|
||
* permission object to a mint
|
||
*
|
||
* @param cls closure
|
||
* @param status 1 for successful deposit, 2 for retry, 0 for failure
|
||
* @param obj the received JSON object; can be NULL if it cannot be constructed
|
||
* from the reply
|
||
* @param emsg in case of unsuccessful deposit, this contains a human readable
|
||
* explanation.
|
||
*/
|
||
typedef void
|
||
(*TALER_MINT_DepositResultCallback) (void *cls,
|
||
int status,
|
||
json_t *obj,
|
||
char *emsg);
|
||
|
||
|
||
/**
|
||
* Submit a deposit permission to the mint and get the mint's response
|
||
*
|
||
* @param mint the mint handle
|
||
* @param cb the callback to call when a reply for this request is available
|
||
* @param cls closure for the above callback
|
||
* @param deposit_obj the deposit permission received from the customer along
|
||
* with the wireformat JSON object
|
||
* @return a handle for this request; NULL if the JSON object could not be
|
||
* parsed or is of incorrect format or any other error. In this case,
|
||
* the callback is not called.
|
||
*/
|
||
struct TALER_MINT_DepositHandle *
|
||
TALER_MINT_deposit_submit_json (struct TALER_MINT_Handle *mint,
|
||
TALER_MINT_DepositResultCallback cb,
|
||
void *cls,
|
||
json_t *deposit_obj);
|
||
|
||
|
||
#if 0
|
||
/**
|
||
* Submit a deposit permission to the mint and get the mint's response.
|
||
*
|
||
* @param mint the mint handle
|
||
* @param cb the callback to call when a reply for this request is available
|
||
* @param cls closure for the above callback
|
||
* @param coin the public key of the coin
|
||
* @param denom_key denomination key of the mint which is used to blind-sign the
|
||
* coin
|
||
* @param ubsig the mint's unblinded signature
|
||
* @param transaction_id transaction identifier
|
||
* @param amount the amount to deposit
|
||
* @param merchant_pub the public key of the merchant
|
||
* @param h_contract hash of the contract
|
||
* @param h_wire hash of the wire format used
|
||
* @param csig signature of the coin over the transaction_id, amount,
|
||
* merchant_pub, h_contract and, h_wire
|
||
* @param wire_obj the wireformat object corresponding to h_wire
|
||
* @return a handle for this request
|
||
*/
|
||
struct TALER_MINT_DepositHandle *
|
||
TALER_MINT_deposit_submit_json_ (struct TALER_MINT_Handle *mint,
|
||
TALER_MINT_DepositResultCallback *cb,
|
||
void *cls,
|
||
const struct TALER_CoinPublicKey *coin_pub,
|
||
const struct TALER_BLIND_SigningPublicKey *denom_pub,
|
||
struct TALER_BLIND_Signature *ubsig,
|
||
uint64_t transaction_id,
|
||
struct TALER_Amount *amount,
|
||
const struct TALER_MerchantPublicKeyP *merchant_pub,
|
||
const struct GNUNET_HashCode *h_contract,
|
||
const struct GNUNET_HashCode *h_wire,
|
||
const struct TALER_CoinSignature *csig,
|
||
json_t *wire_obj);
|
||
#endif
|
||
|
||
|
||
/**
|
||
* Cancel a deposit permission request. This function cannot be used on a
|
||
* request handle if a response is already served for it.
|
||
*
|
||
* @param the deposit permission request handle
|
||
*/
|
||
void
|
||
TALER_MINT_deposit_submit_cancel (struct TALER_MINT_DepositHandle *deposit);
|
||
|
||
#endif /* _TALER_MINT_SERVICE_H */
|