kore-doc

The kore documentation found under https://docs.kore.io/
Commits | Files | Refs | README | git clone https://git.kore.io/kore-doc.git

commit 3a3eb5153c07ada8f0c2fe53a864a852f5ee8bf4
parent 00f5ad0865935651512c1fced67dc11ba8ed764d
Author: Joris Vink <joris@coders.se>
Date:   Mon, 13 May 2019 23:12:06 +0200

missing curl api

Diffstat:
api/curl.md | 98+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 98 insertions(+), 0 deletions(-)

diff --git a/api/curl.md b/api/curl.md @@ -19,11 +19,21 @@ Kore must be built with CURL=1 in order to use this API. * [kore\_curl\_logerror](#logerror) * [kore\_curl\_response\_as\_bytes](#responsebytes) * [kore\_curl\_response\_as\_string](#responsestring) +* [kore\_curl\_http\_setup](#httpsetup) +* [kore\_curl\_http\_set\_header](#setheader) +* [kore\_curl\_http\_get\_header](#getheader) ## 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. +## The CURL handle + +Once a kore\_curl context has been initialized with kore\_curl\_init() you +may access the **handle** member to configure libcurl yourself if you +would like modify certain libcurl options yourself. See [settings](#settings) +for an overview of which libcurl options are set by the API itself. + --- # kore\_curl\_init {#init} @@ -40,6 +50,21 @@ function can be safely used. | client | A kore\_curl data structure. | | url | The URL to be associated with this context. | +### Settings {#settings} + +By default this function will set the following libcurl options: +(some of these are **required** by the Kore curl API to function, it is +advised you do not override these). + +- CURLOPT\_NOSIGNAL is set to 1. +- CURLOPT\_URL is set to the URL passed. +- CURLOPT\_USERAGENT is set to "kore/version". +- CURLOPT\_PRIVATE is set to the kore\_client data structure. +- CURLOPT\_WRITEFUNCTION is set to the kore\_curl\_tobuf function. +- CURLOPT\_ERRORBUFFER is set to point to the internal error buffer. +- CURLOPT\_TIMEOUT is set to the configuration option value curl\_timeout. +- CURLOPT\_WRITEDATA is set to the response kore buffer of the data structure. + ### Returns Nothing @@ -192,3 +217,76 @@ You must not free the returned pointer. A pointer to the response as a C string. --- + +# kore\_curl\_http\_setup {#httpsetup} +### Synopsis +``` +void kore_curl_http_setup(struct kore_curl *client, int method, const void *data, size_t len); +``` +### Description +Setup an HTTP client request. You must have called kore\_curl\_init() first. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | +| method | The HTTP method to be used, see [below](#httpmethod) | +| data | Pointer to the HTTP body to be sent (may be NULL). | +| len | The length of the HTTP body data (may be 0). | + +### HTTP methods {#httpmethod} + +Supported HTTP methods are: + +- HTTP\_METHOD\_GET +- HTTP\_METHOD\_PUT +- HTTP\_METHOD\_HEAD +- HTTP\_METHOD\_POST +- HTTP\_METHOD\_PATCH +- HTTP\_METHOD\_DELETE +- HTTP\_METHOD\_OPTIONS + +### Returns +Nothing + +--- + +# kore\_curl\_http\_set\_header {#setheader} +### Synopsis +``` +void kore_curl_http_set_header(struct kore_curl *client, const char *header. const char *value); +``` +### Description +Add an HTTP header to a configured HTTP client request. + +If value is NULL or an empty string the header is removed. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | +| header | The HTTP header name. | +| value | The HTTP header value. | + +### Returns +Nothing + +--- + +# kore\_curl\_http\_get\_header {#getheader} +### Synopsis +``` +int kore_curl_http_get_header(struct kore_curl *client, const char *header. const char **out); +``` +### Description +Obtain an HTTP header from the response (if kore\_curl\_success() was 1). + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | +| header | The HTTP header name. | +| out | A pointer which will receive the pointer to the HTTP header value. | + +### Returns + +Returns KORE\_RESULT\_OK if the header was found, or KORE\_RESULT\_ERROR if not. + +---