X-Authentication-Warning: blacklodge.c2.net: majordom set sender to
owner-dev-lucre@c2.org using -f
X-Sender: jeremey@descartes.bluemoney.com
Date: Wed, 21 May 1997 12:32:09 -0700
To: ecash-dev@digicash.com, dev-lucre@c2.net
From: Jeremey Barrett
Subject: Ecash API
Mime-Version: 1.0
Sender: owner-dev-lucre@c2.net
Precedence: bulk
-----BEGIN PGP SIGNED MESSAGE-----
Given the absence of an API from Digicash, we need a high level API so
make the task of integrating ecash into products really easy. So here's
my stab. This is the current header from my ecash library, which is a wrapper
for -lucre. -lucre is great, but it's pretty low-level, hence the wrapper.
The documentation in here is pretty incomplete, with just basic descriptions
of what functions do what. At some point it will be improved. I welcome
comments, suggestions, questions, and feature requests.
Currently, this lib handles socket transactions only, but ascii-armor
support will be added. This library will be available in some form or another
in the future, at the moment I'm just looking for feedback.
Regards,
Jeremey.
/* Copyright (c) 1995, 1996, 1997
* The VeriWeb Internet Corporation. All Rights Reserved.
*
* Please view the full copyright at the bottom of this file.
*
* ecash.h $Revision: 1.2 $ (VeriWeb) $Date: 1997/05/21 01:48:50 $
*/
/*==========================================================================*
*
* ecash.h
*
* Written by: Jeremey Barrett
*
* $Revision: 1.2 $
*/
#ifndef _ECASH_H_
#define _ECASH_H_
#include /* utility header */
#include /* -lucre header */
/*--------------------------------------------------------------------
* Types
*/
typedef struct _ECSocket ECSocket;
typedef struct _ECPayment ECPayment;
typedef struct _ECPocket ECPocket;
typedef struct _ECConfig ECConfig;
typedef struct _ECError ECError;
/*--------------------------------------------------------------------
* Errors
*/
#define ECError_NONE 0
#define ECError_INVALID -1
#define ECError_ECSYS -2
#define ECError_SYS -3
#define ECError_TCP -4
#define ECError_READ -5
#define ECError_WRITE -6
#define ECError_BIGNUM -7
#define ECError_MSGNEW -8
#define ECError_WALLETCREATE -9
#define ECError_NOMEM -10
#define ECError_POCKETOPEN -11
#define ECError_POCKETPASSWD -12
#define ECError_NOBANKACCOUNT -13
#define ECError_WITHDRAWAMOUNTLOW -14
#define ECError_DEPOSITPAYMENT -15
#define ECError_DEPOSITALLPAYMENTS -16
#define ECError_DEPOSITRECDB -17
#define ECError_DEPOSITREJECTED -18
#define ECError_WALLETSTATUS -19
#define ECError_DEPOSIT -20
#define ECError_WITHDRAW -21
#define ECError_NOPOCKETPASSWD -22
#define ECError_ECMSGINVALID -23
#define ECError_SENDMSGCALLBACK -24
#define ECError_MAGIC -25
#define ECError_APPENDMSG -26
#define ECError_PAYMENTACCEPT -27
#define ECError_PAYMENTACCEPTBADAMOUNT -28
#define ECError_PAYMENTREJECTED -29
#define ECError_PAYMENTMAKE -30
#define ECError_PAYREQRECEIVE -31
#define ECError_PAYREQCURRENCYUNKNOWN -32
#define ECError_PAYMENTREQUEST -33
#define ECError_PAYMENTACK -34
#define ECError_PAYDB -35
#define ECError_NOPAYMENTS -36
#define ECError_WALLETCOINS -37
#define ECError_EXCHANGECOINS -38
#define ECError_EXCHANGEREJECTED -39
#define ECError_NOTENOUGHCASH -40
#define ECNoError ((ECError *)NULL)
/*--------------------------------------------------------------------
* ECPocket APIs
*
* Very preliminary documentation (will get enhanced later, I'm just
* documenting the less obvious here.
*
* EC_Pocket_open() - Open an existing pocket, with location and
* passphrase set in the ECConfig *.
*
* EC_Pocket_openAccount() - Create a new pocket with the attributes
* in the ECConfig *. This does _not_ open
* the pocket. This is for pockets which
* have mint accounts only.
*
* EC_Pocket_openNoAccount() - Create a new pocket with the attributes
* in the ECConfig *. This does _not_ open
* the pocket. This creates an accountless
* pocket, so the mintAddr and mintPort of
* the ECConfig * should point to the
* moneychanger. Note that mintID is still
* required. This will open a connection
* to the moneychanger and retrieve currency
* keys for the mint.
*
* EC_Pocket_withdraw() - Withdraw from a mint account.
*
* EC_Pocket_withdrawProtoCoins() - Complete and withdraw the coins in
* the EC_M_Withdraw3 (a -lucre struct).
* amt is the value of the coins being
* withdrawn.
*
* EC_Pocket_deposit() - Deposit amount into mint account
*
* EC_Pocket_depositWithdraw() - Deposit coins and immediately withdraw
* the same amount. This allows for exchanges
* of coins and altering the stored
* denominations. Call this when you don't have
* the right coins on hand for a payment.
*
* EC_Pocket_exchangeCoins() - Exchange coins (via moneychanger), same as
* above but w/o mint.
*
* EC_Pocket_getCoinInfo() - Returns information about the denominations
* available for a given amount. max_avail is the
* largest amount the pocket can make less than the
* amount specified. min_dep is the smallest amount
* to exchange which will guarantee the ability to
* make amount, provided min_dep is withdrawn in
* base units (i.e. 1 cent).
*
*/
ECPocket *EC_Pocket_create( void );
ECPocket *EC_Pocket_copy( ECPocket *this );
ECError *EC_Pocket_destroy( ECPocket *this );
ECError *EC_Pocket_open( ECPocket *this,
ECConfig *conf );
ECError *EC_Pocket_openAccount( ECConfig *conf );
ECError *EC_Pocket_openNoAccount( ECConfig *conf );
ECError *EC_Pocket_withdraw( ECPocket *this,
Int32 amount,
Int32 minPayments );
ECError *EC_Pocket_withdrawProtoCoins( ECPocket *this,
ECSocket *sock,
EC_M_Withdraw3 wd3,
Int32 amt );
ECError *EC_Pocket_deposit( ECPocket *this,
Int32 amount );
ECError *EC_Pocket_depositWithdraw( ECPocket *this,
Int32 amount,
Int32 payments );
ECError *EC_Pocket_exchangeCoins( ECPocket *this,
Int32 amount,
Int32 payments,
char *host,
char *port );
ECError *EC_Pocket_getMintID( ECPocket *this,
UInt32 *id );
ECError *EC_Pocket_getCurrency( ECPocket *this,
UInt32 *cur );
ECError *EC_Pocket_getAccountName( ECPocket *this,
char **name );
ECError *EC_Pocket_getCash( ECPocket *this,
UInt32 *cash );
ECError *EC_Pocket_getBalance( ECPocket *this,
UInt32 *bal );
ECError *EC_Pocket_getCashStr( ECPocket *this,
char **cash_str );
ECError *EC_Pocket_getBalanceStr( ECPocket *this,
char **bal_str );
ECError *EC_Pocket_getCoinInfo( ECPocket *this,
UInt32 amount,
UInt32 *max_avail,
UInt32 *min_dep );
Int32 EC_Pocket_isAccountless( ECPocket *this );
/*--------------------------------------------------------------------
* ECSocket APIs
*
*
* Simple set of socket APIs. These functions manage the ecash TCP
* protocol for you. Documentation later.
*
* EC_Socket_setCallbacks() - Sets send and receive callbacks for
* sending ecash messages. These will be
* called _after_ the message is encoded
* with the ecash TCP header.
*/
ECSocket *EC_Socket_create( UInt32 type );
ECError *EC_Socket_setCallbacks( ECSocket *this,
UInt32 (*sendcallback)( void *cbInfo,
UChar *msg,
UInt32 len ),
UInt32 (*recvCallback)( void *cbInfo,
UChar **msg,
UInt32 *len),
void *cbInfo );
ECSocket *EC_Socket_createFromFd( char *haddr, char *hport, Int32 fd );
ECError *EC_Socket_open( ECSocket *this, char *haddr, char *hport );
ECError *EC_Socket_accept( ECSocket *this, ECSocket *new );
ECError *EC_Socket_listen( ECSocket *this, char *hport );
ECError *EC_Socket_sendMsg( ECSocket *this, EC_M_Msg msg );
ECError *EC_Socket_recvMsg( ECSocket *this, EC_M_Msg msg );
TCPSocket *EC_Socket_getTCPSocket( ECSocket *this );
/*--------------------------------------------------------------------
* ECConfig APIs
*/
ECConfig *EC_Config_create( void );
ECConfig *EC_Config_copy( ECConfig *this );
ECError *EC_Config_destroy( ECConfig *this );
ECError *EC_Config_setAccountName( ECConfig *this, char *name );
ECError *EC_Config_setAccountPassword( ECConfig *this, char *passwd );
ECError *EC_Config_setPocketPassword( ECConfig *this, char *passwd );
ECError *EC_Config_setPocketDir( ECConfig *this, char *path );
ECError *EC_Config_setMintID( ECConfig *this, UInt32 mintID );
ECError *EC_Config_setMintAddr( ECConfig *this, char *host );
ECError *EC_Config_setMintPort( ECConfig *this, char *port );
/*--------------------------------------------------------------------
* ECPayment APIs
*
* The important functions here are accept(), make(), request(), and
* variants. Note that this is all socket based, there will be ascii
* armor variants soon, but not now.
*
* EC_Payment_accept() - accept an online payment. The this pointer
* points to an ECPayment with the expected
* amount set. This amount is checked and an
* error will be returned if the incoming payment
* does not agree. The ECSocket * is an already
* open socket to the payer. This function will
* automatically handle accountless pockets, so
* explicitly calling the NoAccount variant is
* not necessary.
*
* EC_Payment_accept1() - same as above, but the payment is _not_ acked
* to the payer.
*
* EC_Payment_acceptNoAccount() - same as accept() but for accountless
* pockets. Gets called by accept() if
* the pocket is accountless.
*
* EC_Payment_acceptNoAccount1() - same as above, but the payment is _not_
* acked to the payer.
*
* EC_Payment_handle() - Unconditionally accept a -lucre EC_M_Payment. This
* will _not_ check amounts. It will handle NoAccount
* automatically.
*
* EC_Payment_handleNoAccount() - same as above except for accountless
* pockets. Called by handle() if the pocket
* is accountless.
*
* EC_Payment_make() - make a payment over the ECSocket passed. This
* function _expects_ a payment ack. Use make1() if
* none will arrive.
*
* EC_Payment_make1() - same as above, but does not wait for an ack.
*
* EC_Payment_receiveRequest() - Receive a payment request on the ECSocket
* passed. Returns the information in the
* this pointer.
*
* EC_Payment_request() - Send a payment request over the ECSocket passed.
*/
ECPayment *EC_Payment_create( ECPocket *pocket );
ECError *EC_Payment_setAmount( ECPayment *this, Int32 amt );
ECError *EC_Payment_setTimestamp( ECPayment *this, UInt32 timestamp );
ECError *EC_Payment_setSeqNo( ECPayment *this, UInt32 timestamp );
ECError *EC_Payment_setDescription( ECPayment *this, char *desc );
ECError *EC_Payment_setRecipientName( ECPayment *this, char *name );
ECError *EC_Payment_setRecipientMint( ECPayment *this, UInt32 id );
ECError *EC_Payment_getAmount( ECPayment *this, UInt32 *amt );
ECError *EC_Payment_getSeqNo( ECPayment *this, UInt32 *seqno );
ECError *EC_Payment_getTimestamp( ECPayment *this, UInt32 *timestamp );
ECError *EC_Payment_getDescription( ECPayment *this, char **desc );
ECError *EC_Payment_getRecipientName( ECPayment *this, char **name );
ECError *EC_Payment_getRecipientMint( ECPayment *this, UInt32 *id );
ECError *EC_Payment_accept( ECPayment *this, ECPocket *pocket,
ECSocket *sock );
ECError *EC_Payment_accept1( ECPayment *this, ECPocket *pocket,
ECSocket *sock );
ECError *EC_Payment_acceptNoAccount( ECPayment *this, ECPocket *pocket,
ECSocket *sock );
ECError *EC_Payment_acceptNoAccount1( ECPayment *this, ECPocket *pocket,
ECSocket *sock );
ECError *EC_Payment_handle( ECPayment *this, ECPocket *pocket,
EC_M_Payment payment );
ECError *EC_Payment_handleNoAccount( ECPayment *this, ECPocket *pocket,
EC_M_Payment payment );
ECError *EC_Payment_make( ECPayment *this, ECPocket *pocket, ECSocket *sock );
ECError *EC_Payment_make1( ECPayment *this, ECPocket *pocket, ECSocket *sock
);
ECError *EC_Payment_receiveRequest( ECPayment *this, ECPocket *pocket,
ECSocket *sock );
ECError *EC_Payment_request( ECPayment *this, ECPocket *pocket, ECSocket
*sock
);
/*--------------------------------------------------------------------
* ECError APIs
*/
ECError *EC_Error_create( void );
ECError *EC_Error_returnValue( Int32 errno );
ECError *EC_Error_returnTCPError( TCPError *err );
ECError *EC_Error_returnLibError( Int32 errno, Int32 libErrno );
#endif /* _ECASH_H_*/
/*
*
* Copyright (c) 1995, 1996, 1997
* The VeriWeb Internet Corporation. All Rights Reserved.
*
* This is a published work of the VeriWeb Internet Corporation
* ("VeriWeb"). Permission to use and/or redistribute may be
* obtained upon prior written permission by VeriWeb, and
* provided that the following conditions are also met:
*
* 1. Redistributions of source code, including binary forms,
* must retain the above copyright notice, this list of
* conditions, and the following disclaimer.
*
* 2. Documentation and/or other materials provided with any
* redistribution must contain the above copyright notice,
* this list of conditions, and the following disclaimer.
*
* 3. All advertising materials mentioning features or use of
* this software must display the following acknowledgement:
*
* This product includes software developed by
* the VeriWeb Internet Corporation and its contributors.
*
* 4. Neither the name of the VeriWeb nor the names of its
* contributors may be used to endorse or promote products
* derived from this software without specific prior written
* permission.
*
* THIS SOFTWARE IS PROVIDED BY VERIWEB AND CONTRIBUTORS ``AS IS''.
* THEREFORE, ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL VERIWEB
* OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED, AND ON
* ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
* OF SUCH DAMAGE.
*
*
*
* ecash.h $Revision: 1.2 $ (VeriWeb) $Date: 1997/05/21 01:48:50 $
*/
/*eof*/
-----BEGIN PGP SIGNATURE-----
Version: 5.0 beta
Charset: noconv
iQCVAwUBM4NNuS/fy+vkqMxNAQEzngP7BmDg16Cmnb9uqS30xlhBvA7FaZb4YPRA
tulRHA+7FhRZttfBm/jL8gaOEzjdtPR4f7p3gGjB4YC2KvSAI1iTrpR9EYxdzHB7
0qMAjPAZbI0A08ZOPLkGDoOi9Qqs3jCgdimANjdVeTheYNNpcR1Ti4ez1CtdwmUo
he0phYP1FBg=
=qizj
-----END PGP SIGNATURE-----
--
Jeremey Barrett VeriWeb Internet Corp.
Crypto, Ecash, Commerce Systems http://www.veriweb.com/
PGP key fingerprint = 3B 42 1E D4 4B 17 0D 80 DC 59 6F 59 04 C3 83 64
