1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
/*
This file is part of TALER
Copyright (C) 2016 GNUnet e.V.
TALER is free software; you can redistribute it and/or modify it under the
terms of the GNU 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 General Public License for more details.
You should have received a copy of the GNU General Public License along with
TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
*/
/**
* @file include/taler_wire_plugin.h
* @brief Plugin API for the handling of wire transactions
* @author Christian Grothoff
*/
#ifndef TALER_WIRE_PLUGIN_H
#define TALER_WIRE_PLUGIN_H
#include <gnunet/gnunet_util_lib.h>
#include <jansson.h>
#include "taler_util.h"
#include "taler_error_codes.h"
/**
* Callback with prepared transaction.
*
* @param cls closure
* @param buf transaction data to persist, NULL on error
* @param buf_size number of bytes in @a buf, 0 on error
*/
typedef void
(*TALER_WIRE_PrepareTransactionCallback) (void *cls,
const char *buf,
size_t buf_size);
/**
* Handle returned for cancelling a preparation step.
*/
struct TALER_WIRE_PrepareHandle;
/**
* Handle returned for cancelling an execution step.
*/
struct TALER_WIRE_ExecuteHandle;
/**
* Function called with the result from the execute step.
*
* @param cls closure
* @param success #GNUNET_OK on success, #GNUNET_SYSERR on failure
* @param emsg NULL on success, otherwise an error message
*/
typedef void
(*TALER_WIRE_ConfirmationCallback)(void *cls,
int success,
const char *emsg);
/**
* @brief The plugin API, returned from the plugin's "init" function.
* The argument given to "init" is simply a configuration handle.
*/
struct TALER_WIRE_Plugin
{
/**
* Closure for all callbacks.
*/
void *cls;
/**
* Name of the library which generated this plugin. Set by the
* plugin loader.
*/
char *library_name;
/**
* Round amount DOWN to the amount that can be transferred via the wire
* method. For example, Taler may support 0.000001 EUR as a unit of
* payment, but SEPA only supports 0.01 EUR. This function would
* round 0.125 EUR to 0.12 EUR in this case.
*
* @param cls the @e cls of this struct with the plugin-specific state
* @param[in,out] amount amount to round down
* @return #GNUNET_OK on success, #GNUNET_NO if rounding was unnecessary,
* #GNUNET_SYSERR if the amount or currency was invalid
*/
int
(*amount_round) (void *cls,
struct TALER_Amount *amount);
/**
* Obtain wire transfer details in the plugin-specific format
* from the configuration.
*
* @param cls closure
* @param cfg configuration with details about wire accounts
* @param account_name which section in the configuration should we parse
* @return NULL if @a cfg fails to have valid wire details for @a account_name
*/
json_t *
(*get_wire_details)(void *cls,
const struct GNUNET_CONFIGURATION_Handle *cfg,
const char *account_name);
/**
* Sign wire transfer details in the plugin-specific format.
*
* @param cls closure
* @param in wire transfer details in JSON format
* @param key private signing key to use
* @param salt salt to add
* @param[out] sig where to write the signature
* @return #GNUNET_OK on success
*/
int
(*sign_wire_details)(void *cls,
const json_t *in,
const struct TALER_MasterPrivateKeyP *key,
const struct GNUNET_HashCode *salt,
struct TALER_MasterSignatureP *sig);
/**
* Check if the given wire format JSON object is correctly formatted
*
* @param cls the @e cls of this struct with the plugin-specific state
* @param wire the JSON wire format object
* @param master_pub public key of the exchange to verify against
* @param[out] emsg set to an error message, unless we return #TALER_EC_NONE;
* error message must be freed by the caller using GNUNET_free()
* @return #TALER_EC_NONE if correctly formatted
*/
enum TALER_ErrorCode
(*wire_validate) (void *cls,
const json_t *wire,
const struct TALER_MasterPublicKeyP *master_pub,
char **emsg);
/**
* Prepare for exeuction of a wire transfer.
*
* @param cls the @e cls of this struct with the plugin-specific state
* @param wire valid wire account information
* @param amount amount to transfer, already rounded
* @param exchange_base_url base URL of this exchange
* @param wtid wire transfer identifier to use
* @param ptc function to call with the prepared data to persist
* @param ptc_cls closure for @a ptc
* @return NULL on failure
*/
struct TALER_WIRE_PrepareHandle *
(*prepare_wire_transfer) (void *cls,
const json_t *wire,
const struct TALER_Amount *amount,
const char *exchange_base_url,
const struct TALER_WireTransferIdentifierRawP *wtid,
TALER_WIRE_PrepareTransactionCallback ptc,
void *ptc_cls);
/**
* Abort preparation of a wire transfer. For example,
* because we are shutting down.
*
* @param cls the @e cls of this struct with the plugin-specific state
* @param pth preparation to cancel
*/
void
(*prepare_wire_transfer_cancel) (void *cls,
struct TALER_WIRE_PrepareHandle *pth);
/**
* Execute a wire transfer.
*
* @param cls the @e cls of this struct with the plugin-specific state
* @param buf buffer with the prepared execution details
* @param buf_size number of bytes in @a buf
* @param cc function to call upon success
* @param cc_cls closure for @a cc
* @return NULL on error
*/
struct TALER_WIRE_ExecuteHandle *
(*execute_wire_transfer) (void *cls,
const char *buf,
size_t buf_size,
TALER_WIRE_ConfirmationCallback cc,
void *cc_cls);
/**
* Abort execution of a wire transfer. For example, because we are
* shutting down. Note that if an execution is aborted, it may or
* may not still succeed. The caller MUST run @e
* execute_wire_transfer again for the same request as soon as
* possilbe, to ensure that the request either ultimately succeeds
* or ultimately fails. Until this has been done, the transaction is
* in limbo (i.e. may or may not have been committed).
*
* @param cls the @e cls of this struct with the plugin-specific state
* @param eh execution to cancel
*/
void
(*execute_wire_transfer_cancel) (void *cls,
struct TALER_WIRE_ExecuteHandle *eh);
};
#endif /* TALER_WIRE_PLUGIN_H */
|
