diff options
author | Christian Grothoff <christian@grothoff.org> | 2016-04-17 15:09:23 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2016-04-17 15:09:23 +0000 |
commit | 16642c4cb25faae335591b39795c71dedbeb37f1 (patch) | |
tree | 99eced0e91cb1455f4dc5afd1fd3918259aa5dd3 /src/include/gnunet_curl_lib.h | |
parent | da7b8273d9f2229fe163ef4fbdcf046fb6227b73 (diff) | |
download | gnunet-16642c4cb25faae335591b39795c71dedbeb37f1.tar.gz gnunet-16642c4cb25faae335591b39795c71dedbeb37f1.zip |
adding libgnunetcurl
Diffstat (limited to 'src/include/gnunet_curl_lib.h')
-rw-r--r-- | src/include/gnunet_curl_lib.h | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/src/include/gnunet_curl_lib.h b/src/include/gnunet_curl_lib.h new file mode 100644 index 000000000..098b4dc37 --- /dev/null +++ b/src/include/gnunet_curl_lib.h | |||
@@ -0,0 +1,155 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | Copyright (C) 2014, 2015, 2016 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software; you can redistribute it and/or modify it under the | ||
6 | terms of the GNU General Public License as published by the Free Software | ||
7 | Foundation; either version 3, or (at your option) any later version. | ||
8 | |||
9 | GNUnet is distributed in the hope that it will be useful, but WITHOUT ANY | ||
10 | WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR | ||
11 | A PARTICULAR PURPOSE. See the GNU General Public License for more details. | ||
12 | |||
13 | You should have received a copy of the GNU General Public License along with | ||
14 | GNUnet; see the file COPYING. If not, If not, see | ||
15 | <http://www.gnu.org/licenses/> | ||
16 | */ | ||
17 | /** | ||
18 | * @file src/include/gnunet_curl_lib.h | ||
19 | * @brief library to make it easy to download JSON replies over HTTP | ||
20 | * @author Sree Harsha Totakura <sreeharsha@totakura.in> | ||
21 | * @author Christian Grothoff | ||
22 | * | ||
23 | * @defgroup curl CURL integration library | ||
24 | * Download JSON using libcurl. | ||
25 | * @{ | ||
26 | */ | ||
27 | #ifndef GNUNET_CURL_LIB_H | ||
28 | #define GNUNET_CURL_LIB_H | ||
29 | #include <curl/curl.h> | ||
30 | #include <jansson.h> | ||
31 | #include <gnunet/gnunet_util_lib.h> | ||
32 | |||
33 | |||
34 | /** | ||
35 | * Initialise this library. This function should be called before using any of | ||
36 | * the following functions. | ||
37 | * | ||
38 | * @return library context | ||
39 | */ | ||
40 | struct GNUNET_CURL_Context * | ||
41 | GNUNET_CURL_init (void); | ||
42 | |||
43 | |||
44 | /** | ||
45 | * Obtain the information for a select() call to wait until | ||
46 | * #GNUNET_CURL_perform() is ready again. Note that calling | ||
47 | * any other TALER_EXCHANGE-API may also imply that the library | ||
48 | * is again ready for #GNUNET_CURL_perform(). | ||
49 | * | ||
50 | * Basically, a client should use this API to prepare for select(), | ||
51 | * then block on select(), then call #GNUNET_CURL_perform() and then | ||
52 | * start again until the work with the context is done. | ||
53 | * | ||
54 | * This function will NOT zero out the sets and assumes that @a max_fd | ||
55 | * and @a timeout are already set to minimal applicable values. It is | ||
56 | * safe to give this API FD-sets and @a max_fd and @a timeout that are | ||
57 | * already initialized to some other descriptors that need to go into | ||
58 | * the select() call. | ||
59 | * | ||
60 | * @param ctx context to get the event loop information for | ||
61 | * @param read_fd_set will be set for any pending read operations | ||
62 | * @param write_fd_set will be set for any pending write operations | ||
63 | * @param except_fd_set is here because curl_multi_fdset() has this argument | ||
64 | * @param max_fd set to the highest FD included in any set; | ||
65 | * if the existing sets have no FDs in it, the initial | ||
66 | * value should be "-1". (Note that `max_fd + 1` will need | ||
67 | * to be passed to select().) | ||
68 | * @param timeout set to the timeout in milliseconds (!); -1 means | ||
69 | * no timeout (NULL, blocking forever is OK), 0 means to | ||
70 | * proceed immediately with #GNUNET_CURL_perform(). | ||
71 | */ | ||
72 | void | ||
73 | GNUNET_CURL_get_select_info (struct GNUNET_CURL_Context *ctx, | ||
74 | fd_set *read_fd_set, | ||
75 | fd_set *write_fd_set, | ||
76 | fd_set *except_fd_set, | ||
77 | int *max_fd, | ||
78 | long *timeout); | ||
79 | |||
80 | |||
81 | /** | ||
82 | * Run the main event loop for the Taler interaction. | ||
83 | * | ||
84 | * @param ctx the library context | ||
85 | */ | ||
86 | void | ||
87 | GNUNET_CURL_perform (struct GNUNET_CURL_Context *ctx); | ||
88 | |||
89 | |||
90 | /** | ||
91 | * Cleanup library initialisation resources. This function should be called | ||
92 | * after using this library to cleanup the resources occupied during library's | ||
93 | * initialisation. | ||
94 | * | ||
95 | * @param ctx the library context | ||
96 | */ | ||
97 | void | ||
98 | GNUNET_CURL_fini (struct GNUNET_CURL_Context *ctx); | ||
99 | |||
100 | |||
101 | /** | ||
102 | * Entry in the context's job queue. | ||
103 | */ | ||
104 | struct GNUNET_CURL_Job; | ||
105 | |||
106 | /** | ||
107 | * Function to call upon completion of a job. | ||
108 | * | ||
109 | * @param cls closure | ||
110 | * @param response_code HTTP response code from server, 0 on hard error | ||
111 | * @param json response, NULL if response was not in JSON format | ||
112 | */ | ||
113 | typedef void | ||
114 | (*GNUNET_CURL_JobCompletionCallback)(void *cls, | ||
115 | long response_code, | ||
116 | json_t *json); | ||
117 | |||
118 | |||
119 | /** | ||
120 | * Schedule a CURL request to be executed and call the given @a jcc | ||
121 | * upon its completion. Note that the context will make use of the | ||
122 | * CURLOPT_PRIVATE facility of the CURL @a eh. | ||
123 | * | ||
124 | * This function modifies the CURL handle to add the | ||
125 | * "Content-Type: application/json" header if @a add_json is set. | ||
126 | * | ||
127 | * @param ctx context to execute the job in | ||
128 | * @param eh curl easy handle for the request, will | ||
129 | * be executed AND cleaned up | ||
130 | * @param add_json add "application/json" content type header | ||
131 | * @param jcc callback to invoke upon completion | ||
132 | * @param jcc_cls closure for @a jcc | ||
133 | * @return NULL on error (in this case, @eh is still released!) | ||
134 | */ | ||
135 | struct GNUNET_CURL_Job * | ||
136 | GNUNET_CURL_job_add (struct GNUNET_CURL_Context *ctx, | ||
137 | CURL *eh, | ||
138 | int add_json, | ||
139 | GNUNET_CURL_JobCompletionCallback jcc, | ||
140 | void *jcc_cls); | ||
141 | |||
142 | |||
143 | /** | ||
144 | * Cancel a job. Must only be called before the job completion | ||
145 | * callback is called for the respective job. | ||
146 | * | ||
147 | * @param job job to cancel | ||
148 | */ | ||
149 | void | ||
150 | GNUNET_CURL_job_cancel (struct GNUNET_CURL_Job *job); | ||
151 | |||
152 | #endif | ||
153 | /** @} */ /* end of group */ | ||
154 | |||
155 | /* end of gnunet_curl_lib.h */ | ||