adding support for transaction history to wire plugin API (#4959)

2 files changed, 81 insertions, 14 deletions

diff --git a/src/include/taler_bank_service.h b/src/include/taler_bank_service.h
index a564bd336..75220233d 100644
--- a/src/include/taler_bank_service.h
+++ b/src/include/taler_bank_service.h
@@ -150,11 +150,16 @@ TALER_BANK_admin_add_incoming_cancel (struct TALER_BANK_AdminAddIncomingHandle *
 
 
 /**
- * Which types of transactions should be returned?
+ * Which types of transactions should be (or is being) returned?
  */
 enum TALER_BANK_Direction {
 
   /**
+   * Base case, used to indicate errors or end of list.
+   */
+  TALER_BANK_DIRECTION_NONE = 0,
+
+  /**
    * Transactions where the bank account receives money.
    */
   TALER_BANK_DIRECTION_CREDIT = 1,
@@ -193,14 +198,9 @@ struct TALER_BANK_TransferDetails
   struct GNUNET_TIME_Absolute execution_date;
 
   /**
-   * monotonically increasing counter corresponding to the transaction
-   */
-  uint64_t serial_id;
-
-  /**
    * wire transfer subject
    */
-  char *wire_transfer_subject;
+  const char *wire_transfer_subject;
 
   /**
    * what was the other account that was involved
@@ -220,6 +220,7 @@ struct TALER_BANK_TransferDetails
  *                    last callback is always of this status (even if `abs(num_results)` were
  *                    already returned).
  * @param dir direction of the transfer
+ * @param serial_id monotonically increasing counter corresponding to the transaction
  * @param details details about the wire transfer
  * @param json detailed response from the HTTPD, or NULL if reply was not in JSON
  */
@@ -227,22 +228,20 @@ typedef void
 (*TALER_BANK_HistoryResultCallback) (void *cls,
                                      unsigned int http_status,
                                      enum TALER_BANK_Direction dir,
+                                     uint64_t serial_id,
                                      const struct TALER_BANK_TransferDetails *details,
                                      const json_t *json);
 
 
 /**
- * Notify the bank that we have received an incoming transaction
- * which fills a reserve.  Note that this API is an administrative
- * API and thus not accessible to typical bank clients, but only
- * to the operators of the bank.
+ * Request the wire transfer history of a bank account.
  *
  * @param ctx curl context for the event loop
  * @param bank_base_url URL of the bank (used to execute this request)
  * @param auth authentication data to use
  * @param account_number which account number should we query
  * @param direction what kinds of wire transfers should be returned
- * @param start_row from which row on do we want to get results, use UINT64_MAX for the latest
+ * @param start_row from which row on do we want to get results, use UINT64_MAX for the latest; exclusive
  * @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.
diff --git a/src/include/taler_wire_plugin.h b/src/include/taler_wire_plugin.h
index e9f873eb7..5e3936804 100644
--- a/src/include/taler_wire_plugin.h
+++ b/src/include/taler_wire_plugin.h
@@ -1,6 +1,6 @@
 /*
   This file is part of TALER
-  Copyright (C) 2016 GNUnet e.V.
+  Copyright (C) 2016, 2017 GNUnet e.V. & Inria
 
   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
@@ -25,6 +25,7 @@
 #include <jansson.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` */
 
 
 /**
@@ -41,16 +42,46 @@ typedef void
 
 
 /**
+ * Callbacks of this type are used to serve the result of asking
+ * the bank for the transaction history.
+ *
+ * @param cls closure
+ * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request
+ *                    0 if the bank's reply is bogus (fails to follow the protocol),
+ *                    #MHD_HTTP_NO_CONTENT if there are no more results; on success the
+ *                    last callback is always of this status (even if `abs(num_results)` were
+ *                    already returned).
+ * @param dir direction of the transfer
+ * @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
+ * @param json detailed response from the HTTPD, or NULL if reply was not in JSON
+ */
+typedef void
+(*TALER_WIRE_HistoryResultCallback) (void *cls,
+                                     unsigned int http_status,
+                                     enum TALER_BANK_Direction dir,
+                                     const void *row_off,
+                                     size_t row_off_size,
+                                     const struct TALER_BANK_TransferDetails *details,
+                                     const json_t *json);
+
+
+/**
  * 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 transaction history.
+ */
+struct TALER_WIRE_HistoryHandle;
+
 
 /**
  * Function called with the result from the execute step.
@@ -217,6 +248,43 @@ struct TALER_WIRE_Plugin
                                    struct TALER_WIRE_ExecuteHandle *eh);
 
 
+  /**
+   * Query transfer history of an 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 direction what kinds of wire transfers should be returned
+   * @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_HistoryHandle *
+  (*get_history) (void *cls,
+                  enum TALER_BANK_Direction direction,
+                  const void *start_off,
+                  size_t start_off_len,
+                  int64_t num_results,
+                  TALER_WIRE_HistoryResultCallback hres_cb,
+                  void *hres_cb_cls);
+
+  /**
+   * Cancel going over the account's history.
+   *
+   * @param whh operation to cancel
+   */
+  void
+  (*get_history_cancel) (struct TALER_WIRE_HistoryHandle *whh);
+
 };