kore-doc

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

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