curl.md (8467B)
1 # Asynchronous libcurl support
2
3 Kore allows you to schedule CURL easy handles onto its internal event loop
4 allowing you to make asynchronous requests for anything libcurl supports.
5
6 On top of that this API provides higher level interface for making HTTP
7 client requests a bit easier.
8
9 Kore must be built with CURL=1 in order to use this API.
10
11 ## Index
12
13 * [kore\_curl\_init](#init)
14 * [kore\_curl\_clean](#cleanup)
15 * [kore\_curl\_bind\_request](#bindrequest)
16 * [kore\_curl\_bind\_callback](#bindcallback)
17 * [kore\_curl\_run](#run)
18 * [kore\_curl\_success](#success)
19 * [kore\_curl\_logerror](#logerror)
20 * [kore\_curl\_strerror](#strerror)
21 * [kore\_curl\_response\_as\_bytes](#responsebytes)
22 * [kore\_curl\_response\_as\_string](#responsestring)
23 * [kore\_curl\_http\_setup](#httpsetup)
24 * [kore\_curl\_http\_set\_header](#setheader)
25 * [kore\_curl\_http\_get\_header](#getheader)
26
27 ## Examples
28
29 See the included [example](https://github.com/jorisvink/kore/tree/master/examples/async-curl) in the Kore source tree for an implementation of this API.
30
31 ## The data structure
32
33 The kore\_curl data structure contains the CURL easy handle, some information
34 about HTTP call results and book-keeping information.
35
36 Once a kore\_curl context has been initialized with [kore\_curl\_init()](#init) you
37 may access the **handle** member to configure libcurl yourself if you
38 would like modify certain libcurl options yourself. See [settings](#settings)
39 for an overview of which libcurl options are set by the API itself.
40
41 ### HTTP request status
42
43 You may be interested in the status code for an HTTP client request. This is
44 found under the http.status member of the data structure once a call was
45 made.
46
47 ---
48
49 # kore\_curl\_init {#init}
50 ### Synopsis
51 ```
52 void kore_curl_init(struct kore_curl *client, const char *url);
53 ```
54 ### Description
55 Initializes a **kore\_curl** context. This must be called before any other
56 function can be safely used.
57
58 | Parameter | Description |
59 | -- | -- |
60 | client | A kore\_curl data structure. |
61 | url | The URL to be associated with this context. |
62
63 ### Settings {#settings}
64
65 By default this function will set the following libcurl options:
66 (some of these are **required** by the Kore curl API to function, it is
67 advised you do not override these).
68
69 - CURLOPT\_NOSIGNAL is set to 1.
70 - CURLOPT\_URL is set to the URL passed.
71 - CURLOPT\_USERAGENT is set to "kore/version".
72 - CURLOPT\_PRIVATE is set to the kore\_client data structure.
73 - CURLOPT\_WRITEFUNCTION is set to the kore\_curl\_tobuf function.
74 - CURLOPT\_ERRORBUFFER is set to point to the internal error buffer.
75 - CURLOPT\_TIMEOUT is set to the configuration option value curl\_timeout.
76 - CURLOPT\_WRITEDATA is set to the response kore buffer of the data structure.
77
78 ### Returns
79 Nothing
80
81 ---
82 # kore\_curl\_cleanup {#cleanup}
83 ### Synopsis
84 ```
85 void kore_curl_cleanup(struct kore_curl *client);
86 ```
87 ### Description
88 Cleanup the **kore\_curl** context and release all resources. This must be
89 called when you no longer need the context.
90
91 | Parameter | Description |
92 | -- | -- |
93 | client | A kore\_curl data structure. |
94
95 ### Returns
96 Nothing
97
98 ---
99 # kore\_curl\_bind\_request {#bindrequest}
100 ### Synopsis
101 ```
102 void kore_curl_bind_request(struct kore_curl *client, struct http_request *req);
103 ```
104 ### Description
105 Bind an HTTP request to a kore\_curl request. Binding means that the HTTP
106 request will be woken up by Kore once the curl request has a result.
107
108 Using this in combination with the HTTP state machine allows you to build
109 request handlers in a completely asynchronous fashion.
110
111 | Parameter | Description |
112 | -- | -- |
113 | client | A kore\_curl data structure. |
114 | req | The HTTP request to be bound to the task. |
115
116 ### Returns
117 Nothing
118
119 ---
120 # kore\_curl\_bind\_callback {#bindcallback}
121 ### Synopsis
122 ```
123 void kore_curl_bind_callback(struct kore_curl *client,
124 void (*cb)(struct kore_curl *, void *), void *arg)
125 ```
126 ### Description
127 Bind a callback to a curl request. Much like the HTTP binding this will cause
128 Kore to call this callback once a curl request has a result.
129
130 You may **not** bind both a callback and an HTTP request.
131
132 | Parameter | Description |
133 | -- | -- |
134 | client | A kore\_curl data structure. |
135 | cb | The callback to call. |
136 | arg | User-supplied pointer that is passed to the callback. |
137
138 ### Returns
139 Nothing
140
141 ---
142 # kore\_curl\_run {#run}
143 ### Synopsis
144 ```
145 void kore_curl_run(struct kore_curl *client)
146 ```
147 ### Description
148 Schedules the kore\_curl context onto the event loop. After calling this
149 Kore will wake-up the bound HTTP request or call the bound callback once
150 there is a result.
151
152 | Parameter | Description |
153 | -- | -- |
154 | client | A kore\_curl data structure. |
155
156 ### Returns
157 Nothing
158
159 ---
160 # kore\_curl\_success {#success}
161 ### Synopsis
162 ```
163 int kore_curl_success(struct kore_curl *client)
164 ```
165 ### Description
166 Check if a curl request was successful (checks if the curl handle is CURLE\_OK).
167
168 | Parameter | Description |
169 | -- | -- |
170 | client | A kore\_curl data structure. |
171
172 ### Returns
173 Returns 1 if the curl handle its result value was CURLE\_OK or 0 otherwise.
174
175 ---
176 # kore\_curl\_logerror {#logerror}
177 ### Synopsis
178 ```
179 void kore_curl_logerror(struct kore_task *client)
180 ```
181 ### Description
182 Log a notice with the error that the curl handle has returned.
183
184 | Parameter | Description |
185 | -- | -- |
186 | client | A kore\_curl data structure. |
187
188 ### Returns
189 Nothing
190
191 ---
192 # kore\_curl\_strerror {#strerror}
193 ### Synopsis
194 ```
195 const char *kore_curl_strerror(struct kore_task *client)
196 ```
197 ### Description
198 Returns a pointer to a human readable error string set by libcurl.
199
200 | Parameter | Description |
201 | -- | -- |
202 | client | A kore\_curl data structure. |
203
204 ### Returns
205 A pointer to a human readable error string.
206
207 ---
208
209 # kore\_curl\_response\_as\_bytes {#responsebytes}
210 ### Synopsis
211 ```
212 void kore_curl_response_as_bytes(struct kore_curl *client, const u_int8_t **body, size_t *len)
213 ```
214 ### Description
215 Obtain the response from a curl request as plain bytes. The **bytes** and **len** pointers are populated to point to the response that was obtained.
216
217 | Parameter | Description |
218 | -- | -- |
219 | client | A kore\_curl data structure. |
220 | body | Pointer which will be pointed to the response bytes. |
221 | len | Pointer to a size\_t that will contain the length of the response. |
222
223 ### Returns
224 Nothing
225
226 ---
227
228 # kore\_curl\_response\_as\_string {#responsestring}
229 ### Synopsis
230 ```
231 char *kore_curl_response_as_string(struct kore_curl *client);
232 ```
233 ### Description
234 Obtain the response from a curl request as a pointer to a C string.
235
236 You must not free the returned pointer.
237
238 | Parameter | Description |
239 | -- | -- |
240 | client | A kore\_curl data structure. |
241
242 ### Returns
243 A pointer to the response as a C string.
244
245 ---
246
247 # kore\_curl\_http\_setup {#httpsetup}
248 ### Synopsis
249 ```
250 void kore_curl_http_setup(struct kore_curl *client, int method, const void *data, size_t len);
251 ```
252 ### Description
253 Setup an HTTP client request. You must have called [kore\_curl\_init()](#init) first.
254
255 | Parameter | Description |
256 | -- | -- |
257 | client | A kore\_curl data structure. |
258 | method | The HTTP method to be used, see [below](#httpmethod) |
259 | data | Pointer to the HTTP body to be sent (may be NULL). |
260 | len | The length of the HTTP body data (may be 0). |
261
262 ### HTTP methods {#httpmethod}
263
264 Supported HTTP methods are:
265
266 - HTTP\_METHOD\_GET
267 - HTTP\_METHOD\_PUT
268 - HTTP\_METHOD\_HEAD
269 - HTTP\_METHOD\_POST
270 - HTTP\_METHOD\_PATCH
271 - HTTP\_METHOD\_DELETE
272 - HTTP\_METHOD\_OPTIONS
273
274 ### Returns
275 Nothing
276
277 ---
278
279 # kore\_curl\_http\_set\_header {#setheader}
280 ### Synopsis
281 ```
282 void kore_curl_http_set_header(struct kore_curl *client, const char *header. const char *value);
283 ```
284 ### Description
285 Add an HTTP header to a configured HTTP client request.
286
287 If value is NULL or an empty string the header is removed.
288
289 | Parameter | Description |
290 | -- | -- |
291 | client | A kore\_curl data structure. |
292 | header | The HTTP header name. |
293 | value | The HTTP header value. |
294
295 ### Returns
296 Nothing
297
298 ---
299
300 # kore\_curl\_http\_get\_header {#getheader}
301 ### Synopsis
302 ```
303 int kore_curl_http_get_header(struct kore_curl *client, const char *header. const char **out);
304 ```
305 ### Description
306 Obtain an HTTP header from the response (if [kore\_curl\_success()](#success) was 1).
307
308 | Parameter | Description |
309 | -- | -- |
310 | client | A kore\_curl data structure. |
311 | header | The HTTP header name. |
312 | out | A pointer which will receive the pointer to the HTTP header value. |
313
314 ### Returns
315
316 Returns KORE\_RESULT\_OK if the header was found, or KORE\_RESULT\_ERROR if not.
317
318 ---