diff options
author | Christian Grothoff <christian@grothoff.org> | 2016-01-25 10:20:40 +0100 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2016-01-25 10:20:40 +0100 |
commit | 941cb8182f052bbd6344ba7daf91f3aa792027bd (patch) | |
tree | 2981759aae0048edd0948e6fcf73b6029c9f6eeb /src/bank-lib/bank_api_context.h | |
parent | 5c58c43609609e6871c7105c7ca8fc3d794dca04 (diff) | |
download | exchange-941cb8182f052bbd6344ba7daf91f3aa792027bd.tar.xz |
adding first version of thebank-lib
Diffstat (limited to 'src/bank-lib/bank_api_context.h')
-rw-r--r-- | src/bank-lib/bank_api_context.h | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/src/bank-lib/bank_api_context.h b/src/bank-lib/bank_api_context.h new file mode 100644 index 000000000..552cbe440 --- /dev/null +++ b/src/bank-lib/bank_api_context.h @@ -0,0 +1,181 @@ +/* + This file is part of TALER + Copyright (C) 2014, 2015 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, If not, see + <http://www.gnu.org/licenses/> +*/ +/** + * @file bank-lib/bank_api_context.h + * @brief Internal interface to the context part of the bank's HTTP API + * @author Sree Harsha Totakura <sreeharsha@totakura.in> + * @author Christian Grothoff + */ +#include "platform.h" +#include <curl/curl.h> +#include <gnunet/gnunet_util_lib.h> +#include "taler_bank_service.h" +#include "taler_signatures.h" + + +/** + * Entry in the context's job queue. + */ +struct BAC_Job; + +/** + * Function to call upon completion of a job. + * + * @param cls closure + * @param eh original easy handle (for inspection) + */ +typedef void +(*BAC_JobCompletionCallback)(void *cls, + CURL *eh); + + +/** + * Schedule a CURL request to be executed and call the given @a jcc + * upon its completion. Note that the context will make use of the + * CURLOPT_PRIVATE facility of the CURL @a eh. Applications can + * instead use #BAC_easy_to_closure to extract the @a jcc_cls argument + * from a valid @a eh afterwards. + * + * This function modifies the CURL handle to add the + * "Content-Type: application/json" header if @a add_json is set. + * + * @param ctx context to execute the job in + * @param eh curl easy handle for the request, will + * be executed AND cleaned up + * @param add_json add "application/json" content type header + * @param jcc callback to invoke upon completion + * @param jcc_cls closure for @a jcc + */ +struct BAC_Job * +BAC_job_add (struct TALER_BANK_Context *ctx, + CURL *eh, + int add_json, + BAC_JobCompletionCallback jcc, + void *jcc_cls); + + +/** + * Obtain the `jcc_cls` argument from an `eh` that was + * given to #BAC_job_add(). + * + * @param eh easy handle that was used + * @return the `jcc_cls` that was given to #BAC_job_add(). + */ +void * +BAC_easy_to_closure (CURL *eh); + + +/** + * Cancel a job. Must only be called before the job completion + * callback is called for the respective job. + * + * @param job job to cancel + */ +void +BAC_job_cancel (struct BAC_Job *job); + + +/** + * @brief Buffer data structure we use to buffer the HTTP download + * before giving it to the JSON parser. + */ +struct BAC_DownloadBuffer +{ + + /** + * Download buffer + */ + void *buf; + + /** + * The size of the download buffer + */ + size_t buf_size; + + /** + * Error code (based on libc errno) if we failed to download + * (i.e. response too large). + */ + int eno; + +}; + + +/** + * Callback used when downloading the reply to an HTTP request. + * Just appends all of the data to the `buf` in the + * `struct BAC_DownloadBuffer` for further processing. The size of + * the download is limited to #GNUNET_MAX_MALLOC_CHECKED, if + * the download exceeds this size, we abort with an error. + * + * Should be used by the various routines as the + * CURLOPT_WRITEFUNCTION. A `struct BAC_DownloadBuffer` needs to be + * passed to the CURLOPT_WRITEDATA. + * + * Afterwards, `eno` needs to be checked to ensure that the download + * completed correctly. + * + * @param bufptr data downloaded via HTTP + * @param size size of an item in @a bufptr + * @param nitems number of items in @a bufptr + * @param cls the `struct KeysRequest` + * @return number of bytes processed from @a bufptr + */ +size_t +BAC_download_cb (char *bufptr, + size_t size, + size_t nitems, + void *cls); + + +/** + * Obtain information about the final result about the + * HTTP download. If the download was successful, parses + * the JSON in the @a db and returns it. Also returns + * the HTTP @a response_code. If the download failed, + * the return value is NULL. The response code is set + * in any case, on download errors to zero. + * + * Calling this function also cleans up @a db. + * + * @param db download buffer + * @param eh CURL handle (to get the response code) + * @param[out] response_code set to the HTTP response code + * (or zero if we aborted the download, i.e. + * because the response was too big, or if + * the JSON we received was malformed). + * @return NULL if downloading a JSON reply failed + */ +json_t * +BAC_download_get_result (struct BAC_DownloadBuffer *db, + CURL *eh, + long *response_code); + + +/** + * Obtain the URL to use for an API request. + * + * @param h the bank handle to query + * @param path Taler API path (i.e. "/reserve/withdraw") + * @return the full URI to use with cURL + */ +char * +BAC_path_to_url (struct TALER_BANK_Context *h, + const char *path); + + +/* end of bank_api_context.h */ |