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
• kore_curl_clean
• kore_curl_bind_request
• kore_curl_bind_callback
• kore_curl_run
• kore_curl_success
• kore_curl_logerror
• kore_curl_strerror
• kore_curl_response_as_bytes
• kore_curl_response_as_string
• kore_curl_http_setup
• kore_curl_http_set_header
• kore_curl_http_get_header

Examples

See the included example in the Kore source tree for an implementation of this API.

The data structure

The kore_curl data structure contains the CURL easy handle, some information about HTTP call results and book-keeping information.

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 for an overview of which libcurl options are set by the API itself.

HTTP request status

You may be interested in the status code for an HTTP client request. This is found under the http.status member of the data structure once a call was made.

kore_curl_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.

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

kore_curl_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.

Returns

Nothing

kore_curl_bind_request

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.

Returns

Nothing

kore_curl_bind_callback

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.

Returns

Nothing

kore_curl_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.

Returns

Nothing

kore_curl_success

Synopsis

int kore_curl_success(struct kore_curl *client)

Description

Check if a curl request was successful (checks if the curl handle is CURLE_OK).

Returns

Returns 1 if the curl handle its result value was CURLE_OK or 0 otherwise.

kore_curl_logerror

Synopsis

void kore_curl_logerror(struct kore_task *client)

Description

Log a notice with the error that the curl handle has returned.

Returns

Nothing

kore_curl_strerror

Synopsis

const char *kore_curl_strerror(struct kore_task *client)

Description

Returns a pointer to a human readable error string set by libcurl.

Returns

A pointer to a human readable error string.

kore_curl_response_as_bytes

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.

Returns

Nothing

kore_curl_response_as_string

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.

Returns

A pointer to the response as a C string.

kore_curl_http_setup

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.

HTTP methods

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

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.

Returns

Nothing

kore_curl_http_get_header

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).

Returns

Returns KORE_RESULT_OK if the header was found, or KORE_RESULT_ERROR if not.