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

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.

Parameter Description
client A kore_curl data structure.
url The URL to be associated with this context.

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.

Parameter Description
client A kore_curl data structure.

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.

Parameter Description
client A kore_curl data structure.
req The HTTP request to be bound to the task.

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.

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

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

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

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

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_strerror

Synopsis

const char *kore_curl_strerror(struct kore_task *client)

Description

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

Parameter Description
client A kore_curl data structure.

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.

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

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.


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.

Parameter Description
client A kore_curl data structure.
method The HTTP method to be used, see below
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

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.

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

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.


results matching ""

    No results matching ""