summaryrefslogtreecommitdiff
path: root/src/include/taler_wire_plugin.h
blob: b5621e686c476413df1406a84bb41863522fce33 (plain)
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
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
/*
  This file is part of TALER
  Copyright (C) 2016-2020 Taler Systems SA

  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 "taler_util.h"
#include "taler_error_codes.h"
#include "taler_bank_service.h" /* for `enum TALER_BANK_Direction` and `struct TALER_BANK_TransferDetails` */


/**
 * 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);


/**
 * Details about a valid wire transfer to the exchange.
 */
struct TALER_WIRE_CreditDetails
{
  /**
   * Amount that was transferred
   */
  struct TALER_Amount amount;

  /**
   * Time of the the transfer
   */
  struct GNUNET_TIME_Absolute execution_date;

  /**
   * Binary data that was encoded in the wire transfer subject.
   */
  struct TALER_ReservePublicKeyP reserve_pub;

  /**
   * payto://-URL of the source's account (used
   * when the reserve is closed or for debugging).
   */
  const char *source_account_url;
};


/**
 * Details about a valid wire transfer made by the
 * exchange's aggregator to a merchant.
 */
struct TALER_WIRE_DebitDetails
{
  /**
   * Amount that was transferred
   */
  struct TALER_Amount amount;

  /**
   * Time of the the transfer
   */
  struct GNUNET_TIME_Absolute execution_date;

  /**
   * Binary data that was encoded in the wire transfer subject.
   */
  struct TALER_WireTransferIdentifierRawP wtid;

  /**
   * payto://-URL of the target account which received
   * the funds.
   */
  const char *target_account_url;
};


/**
 * Callbacks of this type are used to serve the result of asking
 * the bank for the transaction history.  NOTE: this function will
 * NOT get the list of history elements, but rather get (iteratively)
 * called for each (parsed) history element.
 *
 * @param cls closure
 * @param ec taler error code
 * @param row_off identification of the position at which we are querying
 * @param row_off_size number of bytes in @a row_off
 * @param details details about the wire transfer
 * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration
 */
typedef int
(*TALER_WIRE_CreditResultCallback) (void *cls,
                                    enum TALER_ErrorCode ec,
                                    const void *row_off,
                                    size_t row_off_size,
                                    const struct
                                    TALER_WIRE_CreditDetails *details);


/**
 * Callbacks of this type are used to serve the result of asking
 * the bank for the transaction history.  NOTE: this function will
 * NOT get the list of history elements, but rather get (iteratively)
 * called for each (parsed) history element.
 *
 * @param cls closure
 * @param ec taler error code
 * @param row_off identification of the position at which we are querying
 * @param row_off_size number of bytes in @a row_off
 * @param details details about the wire transfer
 * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration
 */
typedef int
(*TALER_WIRE_DebitResultCallback) (void *cls,
                                   enum TALER_ErrorCode ec,
                                   const void *row_off,
                                   size_t row_off_size,
                                   const struct
                                   TALER_WIRE_DebitDetails *details);


/**
 * Handle returned for cancelling a preparation step.
 */
struct TALER_WIRE_PrepareHandle;

/**
 * Handle returned for cancelling an execution step.
 */
struct TALER_WIRE_ExecuteHandle;

/**
 * Handle returned for querying the credit transaction history.
 */
struct TALER_WIRE_CreditHistoryHandle;

/**
 * Handle returned for querying the debit transaction history.
 */
struct TALER_WIRE_DebitHistoryHandle;


/**
 * Function called with the result from the execute step.
 *
 * @param cls closure
 * @param success #GNUNET_OK on success, #GNUNET_SYSERR on failure
 * @param row_id unique ID of the wire transfer in the bank's records; NULL on error
 * @param row_id_size number of bytes in @e row_id
 * @param emsg NULL on success, otherwise an error message
 */
typedef void
(*TALER_WIRE_ConfirmationCallback)(void *cls,
                                   int success,
                                   const void *row_id,
                                   size_t row_id_size,
                                   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;

  /**
   * Which wire method (payto://METHOD/") is supported by this plugin?
   * For example, "x-taler-bank" or "iban".
   */
  const char *method;

  /**
   * 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 IBAN 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);


  /**
   * Check if the given payto:// URL is correctly formatted for this plugin
   *
   * @param cls the @e cls of this struct with the plugin-specific state
   * @param account_url the payto:// URL
   * @return #TALER_EC_NONE if correctly formatted
   */
  enum TALER_ErrorCode
  (*wire_validate)(void *cls,
                   const char *account_url);


  /**
   * Query credits made to exchange account.  We use the variable-size
   * @a start_off to indicate which transfers we are interested in as
   * different banking systems may have different ways to identify
   * transfers.  The @a start_off value must thus match the value of
   * a `row_off` argument previously given to the @a hres_cb.  Use
   * NULL to query transfers from the beginning of time (with
   * positive @a num_results) or from the latest committed transfers
   * (with negative @a num_results).
   *
   * @param cls the @e cls of this struct with the plugin-specific state
   * @param account_section specifies the configuration section which
   *        identifies the account for which we should get the history
   * @param start_off from which row on do we want to get results, use NULL for the latest; exclusive
   * @param start_off_len number of bytes in @a start_off
   * @param num_results how many results do we want; negative numbers to go into the past,
   *                    positive numbers to go into the future starting at @a start_row;
   *                    must not be zero.
   * @param hres_cb the callback to call with the transaction history
   * @param hres_cb_cls closure for the above callback
   */
  struct TALER_WIRE_CreditHistoryHandle *
  (*get_credits) (void *cls,
                  const char *account_section,
                  const void *start_off,
                  size_t start_off_len,
                  int64_t num_results,
                  TALER_WIRE_CreditResultCallback hres_cb,
                  void *hres_cb_cls);

  /**
   * Cancel going over the account's history.
   *
   * @param cls plugins' closure
   * @param chh operation to cancel
   */
  void
  (*get_credits_cancel) (void *cls,
                         struct TALER_WIRE_CreditHistoryHandle *chh);


  /**
   * Query debits (transfers to merchants) made by an exchange.  We use the
   * variable-size @a start_off to indicate which transfers we are interested
   * in as different banking systems may have different ways to identify
   * transfers.  The @a start_off value must thus match the value of a
   * `row_off` argument previously given to the @a hres_cb.  Use NULL to query
   * transfers from the beginning of time (with positive @a num_results) or
   * from the latest committed transfers (with negative @a num_results).
   *
   * @param cls the @e cls of this struct with the plugin-specific state
   * @param account_section specifies the configuration section which
   *        identifies the account for which we should get the history
   * @param start_off from which row on do we want to get results, use NULL for the latest; exclusive
   * @param start_off_len number of bytes in @a start_off
   * @param num_results how many results do we want; negative numbers to go into the past,
   *                    positive numbers to go into the future starting at @a start_row;
   *                    must not be zero.
   * @param hres_cb the callback to call with the transaction history
   * @param hres_cb_cls closure for the above callback
   */
  struct TALER_WIRE_DebitHistoryHandle *
  (*get_debits) (void *cls,
                 const char *account_section,
                 const void *start_off,
                 size_t start_off_len,
                 int64_t num_results,
                 TALER_WIRE_DebitResultCallback hres_cb,
                 void *hres_cb_cls);

  /**
   * Cancel going over the account's history.
   *
   * @param cls plugins' closure
   * @param dhh operation to cancel
   */
  void
  (*get_debits_cancel) (void *cls,
                        struct TALER_WIRE_DebitHistoryHandle *dhh);


};


#endif /* TALER_WIRE_PLUGIN_H */