summaryrefslogtreecommitdiff
path: root/src/include
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2016-01-25 10:20:40 +0100
committerChristian Grothoff <christian@grothoff.org>2016-01-25 10:20:40 +0100
commit941cb8182f052bbd6344ba7daf91f3aa792027bd (patch)
tree2981759aae0048edd0948e6fcf73b6029c9f6eeb /src/include
parent5c58c43609609e6871c7105c7ca8fc3d794dca04 (diff)
downloadexchange-941cb8182f052bbd6344ba7daf91f3aa792027bd.tar.gz
exchange-941cb8182f052bbd6344ba7daf91f3aa792027bd.tar.bz2
exchange-941cb8182f052bbd6344ba7daf91f3aa792027bd.zip
adding first version of thebank-lib
Diffstat (limited to 'src/include')
-rw-r--r--src/include/taler_bank_service.h160
1 files changed, 160 insertions, 0 deletions
diff --git a/src/include/taler_bank_service.h b/src/include/taler_bank_service.h
new file mode 100644
index 000000000..b19e213a8
--- /dev/null
+++ b/src/include/taler_bank_service.h
@@ -0,0 +1,160 @@
+/*
+ This file is part of TALER
+ Copyright (C) 2015, 2016 GNUnet e.V.
+
+ 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_bank_service.h
+ * @brief C interface of libtalerbank, a C library to use the Taler bank's HTTP API
+ * @author Christian Grothoff
+ */
+#ifndef _TALER_BANK_SERVICE_H
+#define _TALER_BANK_SERVICE_H
+
+#include "taler_util.h"
+
+/* ********************* event loop *********************** */
+
+/**
+ * @brief Handle to this library context. This is where the
+ * main event loop logic lives.
+ */
+struct TALER_BANK_Context;
+
+
+/**
+ * Initialise a context. A context should be used for each thread and should
+ * not be shared among multiple threads.
+ *
+ * @param url HTTP base URL for the bank
+ * @return the context, NULL on error (failure to initialize)
+ */
+struct TALER_BANK_Context *
+TALER_BANK_init (const char *url);
+
+
+/**
+ * Obtain the information for a select() call to wait until
+ * #TALER_BANK_perform() is ready again. Note that calling
+ * any other TALER_BANK-API may also imply that the library
+ * is again ready for #TALER_BANK_perform().
+ *
+ * Basically, a client should use this API to prepare for select(),
+ * then block on select(), then call #TALER_BANK_perform() and then
+ * start again until the work with the context is done.
+ *
+ * This function will NOT zero out the sets and assumes that @a max_fd
+ * and @a timeout are already set to minimal applicable values. It is
+ * safe to give this API FD-sets and @a max_fd and @a timeout that are
+ * already initialized to some other descriptors that need to go into
+ * the select() call.
+ *
+ * @param ctx context to get the event loop information for
+ * @param read_fd_set will be set for any pending read operations
+ * @param write_fd_set will be set for any pending write operations
+ * @param except_fd_set is here because curl_multi_fdset() has this argument
+ * @param max_fd set to the highest FD included in any set;
+ * if the existing sets have no FDs in it, the initial
+ * value should be "-1". (Note that `max_fd + 1` will need
+ * to be passed to select().)
+ * @param timeout set to the timeout in milliseconds (!); -1 means
+ * no timeout (NULL, blocking forever is OK), 0 means to
+ * proceed immediately with #TALER_BANK_perform().
+ */
+void
+TALER_BANK_get_select_info (struct TALER_BANK_Context *ctx,
+ fd_set *read_fd_set,
+ fd_set *write_fd_set,
+ fd_set *except_fd_set,
+ int *max_fd,
+ long *timeout);
+
+
+/**
+ * Run the main event loop for the Taler interaction.
+ *
+ * @param ctx the library context
+ */
+void
+TALER_BANK_perform (struct TALER_BANK_Context *ctx);
+
+
+/**
+ * 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_BANK_fini (struct TALER_BANK_Context *ctx);
+
+
+/* ********************* /admin/add/incoming *********************** */
+
+
+/**
+ * @brief A /admin/add/incoming Handle
+ */
+struct TALER_BANK_AdminAddIncomingHandle;
+
+
+/**
+ * Callbacks of this type are used to serve the result of submitting
+ * information about an incoming transaction to a bank.
+ *
+ * @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)
+ */
+typedef void
+(*TALER_BANK_AdminAddIncomingResultCallback) (void *cls,
+ unsigned int http_status);
+
+
+/**
+ * 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.
+ *
+ * @param bank the bank handle; the bank must be ready to operate
+ * @param reserve_pub public key of the reserve
+ * @param amount amount that was deposited
+ * @param execution_date when did we receive the amount
+ * @param wire wire details
+ * @param res_cb the callback to call when the final result for this request is available
+ * @param res_cb_cls closure for the above callback
+ * @return NULL
+ * if the inputs are invalid (i.e. invalid amount).
+ * In this case, the callback is not called.
+ */
+struct TALER_BANK_AdminAddIncomingHandle *
+TALER_BANK_admin_add_incoming (struct TALER_BANK_Context *bank,
+ const struct TALER_WireTransferIdentifierRawP *wtid,
+ const struct TALER_Amount *amount,
+ const json_t *wire,
+ TALER_BANK_AdminAddIncomingResultCallback res_cb,
+ void *res_cb_cls);
+
+
+/**
+ * Cancel an add incoming. This function cannot be used on a request
+ * handle if a response is already served for it.
+ *
+ * @param aai the admin add incoming request handle
+ */
+void
+TALER_BANK_admin_add_incoming_cancel (struct TALER_BANK_AdminAddIncomingHandle *aai);
+
+#endif /* _TALER_BANK_SERVICE_H */