commit 00f5ad0865935651512c1fced67dc11ba8ed764d
parent 6996a8195093f7b1979adda2d28f3921eb8d9b04
Author: Joris Vink <joris@coders.se>
Date: Mon, 13 May 2019 22:43:13 +0200
add initial curl page
Diffstat:
| SUMMARY.md | | | 1 | + |
| api/curl.md | | | 194 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
2 files changed, 195 insertions(+), 0 deletions(-)
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -13,6 +13,7 @@
* [API](api/README.md)
* [Hooks](api/hooks.md)
* [Buffers](api/buffers.md)
+ * [Curl](api/curl.md)
* [HTTP](api/http.md)
* [Pools](api/pools.md)
* [Memory](api/memory.md)
diff --git a/api/curl.md b/api/curl.md
@@ -0,0 +1,194 @@
+# Asynchronous libcurl support
+
+Kore allows you to schedule CURL easy handles onto its internal event loop
+allowing you to make asynchronous requests for anything libcurl supports.
+
+On top of that this API provides higher level interface for making HTTP
+client requests a bit easier.
+
+Kore must be built with CURL=1 in order to use this API.
+
+## Index
+
+* [kore\_curl\_init](#init)
+* [kore\_curl\_clean](#cleanup)
+* [kore\_curl\_bind\_request](#bindrequest)
+* [kore\_curl\_bind\_callback](#bindcallback)
+* [kore\_curl\_run](#run)
+* [kore\_curl\_success](#success)
+* [kore\_curl\_logerror](#logerror)
+* [kore\_curl\_response\_as\_bytes](#responsebytes)
+* [kore\_curl\_response\_as\_string](#responsestring)
+
+## Examples
+
+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.
+
+---
+
+# kore\_curl\_init {#init}
+### Synopsis
+```
+void kore_curl_init(struct kore_curl *client, const char *url);
+```
+### Description
+Initializes a **kore\_curl** context. This must be called before any other
+function can be safely used.
+
+| Parameter | Description |
+| -- | -- |
+| client | A kore\_curl data structure. |
+| url | The URL to be associated with this context. |
+
+### Returns
+Nothing
+
+---
+# kore\_curl\_cleanup {#cleanup}
+### Synopsis
+```
+void kore_curl_cleanup(struct kore_curl *client);
+```
+### Description
+Cleanup the **kore\_curl** context and release all resources. This must be
+called when you no longer need the context.
+
+| Parameter | Description |
+| -- | -- |
+| client | A kore\_curl data structure. |
+
+### Returns
+Nothing
+
+---
+# kore\_curl\_bind\_request {#bindrequest}
+### Synopsis
+```
+void kore_curl_bind_request(struct kore_curl *client, struct http_request *req);
+```
+### Description
+Bind an HTTP request to a kore\_curl request. Binding means that the HTTP
+request will be woken up by Kore once the curl request has a result.
+
+Using this in combination with the HTTP state machine allows you to build
+request handlers in a completely asynchronous fashion.
+
+| Parameter | Description |
+| -- | -- |
+| client | A kore\_curl data structure. |
+| req | The HTTP request to be bound to the task. |
+
+### Returns
+Nothing
+
+---
+# kore\_curl\_bind\_callback {#bindcallback}
+### Synopsis
+```
+void kore_curl_bind_callback(struct kore_curl *client,
+ void (*cb)(struct kore_curl *, void *), void *arg)
+```
+### Description
+Bind a callback to a curl request. Much like the HTTP binding this will cause
+Kore to call this callback once a curl request has a result.
+
+You may **not** bind both a callback and an HTTP request.
+
+| Parameter | Description |
+| -- | -- |
+| client | A kore\_curl data structure. |
+| cb | The callback to call. |
+| arg | User-supplied pointer that is passed to the callback. |
+
+### Returns
+Nothing
+
+---
+# kore\_curl\_run {#run}
+### Synopsis
+```
+void kore_curl_run(struct kore_curl *client)
+```
+### Description
+Schedules the kore\_curl context onto the event loop. After calling this
+Kore will wake-up the bound HTTP request or call the bound callback once
+there is a result.
+
+| Parameter | Description |
+| -- | -- |
+| client | A kore\_curl data structure. |
+
+### Returns
+Nothing
+
+---
+# kore\_curl\_success {#success}
+### Synopsis
+```
+int kore_curl_success(struct kore_curl *client)
+```
+### Description
+Check if a curl request was successfull (checks if the curl handle is CURLE\_OK).
+
+| Parameter | Description |
+| -- | -- |
+| client | A kore\_curl data structure. |
+
+### Returns
+Returns 1 if the curl handle its result value was CURLE\_OK or 0 otherwise.
+
+---
+# kore\_curl\_logerror {#logerror}
+### Synopsis
+```
+void kore_curl_logerror(struct kore_task *client)
+```
+### Description
+Log a notice with the error that the curl handle has returned.
+
+| Parameter | Description |
+| -- | -- |
+| client | A kore\_curl data structure. |
+
+### Returns
+Nothing
+
+---
+
+# kore\_curl\_response\_as\_bytes {#responsebytes}
+### Synopsis
+```
+void kore_curl_response_as_bytes(struct kore_curl *client, const u_int8_t **body, size_t *len)
+```
+### Description
+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.
+
+| Parameter | Description |
+| -- | -- |
+| client | A kore\_curl data structure. |
+| body | Pointer which will be pointed to the response bytes. |
+| len | Pointer to a size\_t that will contain the length of the response. |
+
+### Returns
+Nothing
+
+---
+
+# kore\_curl\_response\_as\_string {#responsestring}
+### Synopsis
+```
+char *kore_curl_response_as_string(struct kore_curl *client);
+```
+### Description
+Obtain the response from a curl request as a pointer to a C string.
+
+You must not free the returned pointer.
+
+| Parameter | Description |
+| -- | -- |
+| client | A kore\_curl data structure. |
+
+### Returns
+A pointer to the response as a C string.
+
+---
