| .. _http_interface: |
| |
| HTTP client |
| ########### |
| |
| .. contents:: |
| :local: |
| :depth: 2 |
| |
| Overview |
| ******** |
| |
| The HTTP client library allows you to send HTTP requests and |
| parse HTTP responses. The library communicates over the sockets |
| API but it does not create sockets on its own. |
| |
| The application must be responsible for creating a socket and passing it to the library. |
| Therefore, depending on the application's needs, the library can communicate over |
| either a plain TCP socket (HTTP) or a TLS socket (HTTPS). |
| |
| Sample Usage |
| ************ |
| |
| The API of the HTTP client library has a single function. |
| |
| The following is an example of a request structure created correctly: |
| |
| .. code-block:: c |
| |
| struct http_request req = { 0 }; |
| static uint8_t recv_buf[512]; |
| |
| req.method = HTTP_GET; |
| req.url = "/"; |
| req.host = "localhost"; |
| req.protocol = "HTTP/1.1"; |
| req.response = response_cb; |
| req.recv_buf = recv_buf; |
| req.recv_buf_len = sizeof(recv_buf); |
| |
| /* sock is a file descriptor referencing a socket that has been connected |
| * to the HTTP server. |
| */ |
| ret = http_client_req(sock, &req, 5000, NULL); |
| |
| If the server responds to the request, the library provides the response to the |
| application through the response callback registered in the request structure. |
| As the library can provide the response in chunks, the application must be able |
| to process these. |
| |
| Together with the structure containing the response data, the callback function |
| also provides information about whether the library expects to receive more data. |
| |
| The following is an example of a very simple response handling function: |
| |
| .. code-block:: c |
| |
| static void response_cb(struct http_response *rsp, |
| enum http_final_call final_data, |
| void *user_data) |
| { |
| if (final_data == HTTP_DATA_MORE) { |
| LOG_INF("Partial data received (%zd bytes)", rsp->data_len); |
| } else if (final_data == HTTP_DATA_FINAL) { |
| LOG_INF("All the data received (%zd bytes)", rsp->data_len); |
| } |
| |
| LOG_INF("Response status %s", rsp->http_status); |
| } |
| |
| See :ref:`HTTP client sample application <sockets-http-client-sample>` for |
| more information about the library usage. |
| |
| API Reference |
| ************* |
| |
| .. doxygengroup:: http_client |