.. _coap_client_interface:

CoAP client
###########

.. contents::
    :local:
    :depth: 2

Overview
********

The CoAP client library allows application to send CoAP requests and parse CoAP responses.
The library can be enabled with :kconfig:option:`CONFIG_COAP_CLIENT` Kconfig option.
The application is notified about the response via a callback that is provided to the API
in the request. The CoAP client handles the communication over sockets.
As the CoAP client doesn't create socket it is using, the application is responsible for creating
the socket. Plain UDP or DTLS sockets are supported.

Sample Usage
************

The following is an example of a CoAP client initialization and request sending:

.. code-block:: c

    static struct coap_client;
    struct coap_client_request req = { 0 };

    coap_client_init(&client, NULL);

    req.method = COAP_METHOD_GET;
    req.confirmable = true;
    req.path = "test";
    req.fmt = COAP_CONTENT_FORMAT_TEXT_PLAIN;
    req.cb = response_cb;
    req.payload = NULL;
    req.len = 0;

    /* Sock is a file descriptor referencing a socket, address is the sockaddr struct for the
     * destination address of the request or NULL if the socket is already connected.
     */
    ret = coap_client_req(&client, sock, &address, &req, -1);

Before any requests can be sent, the CoAP client needs to be initialized.
After initialization, the application can send a CoAP request and wait for the response.
Currently only one request can be sent for a single CoAP client at a time. There can be multiple
CoAP clients.

The callback provided in the callback will be called in following cases:

- There is a response for the request
- The request failed for some reason

The callback contains a flag `last_block`, which indicates if there is more data to come in the
response and means that the current response is part of a blockwise transfer. When the `last_block`
is set to true, the response is finished and the client is ready for the next request after
returning from the callback.

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 response can be a blockwise transfer and the client calls the callback once per each
block, the application should be to process all of the blocks to be able to process the response.

The following is an example of a very simple response handling function:

.. code-block:: c

    void response_cb(int16_t code, size_t offset, const uint8_t *payload, size_t len,
                     bool last_block, void *user_data)
    {
        if (code >= 0) {
	        LOG_INF("CoAP response from server %d", code);
                if (last_block) {
                        LOG_INF("Last packet received");
                }
        } else {
                LOG_ERR("Error in sending request %d", code);
        }
    }

API Reference
*************

.. doxygengroup:: coap_client