zephyr/doc/connectivity/networking/api/coap_client.rst

.. _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);
        }
    }

CoAP options may also be added to the request by the application. The following is an example of
the application adding a Block2 option to the initial request, to suggest a maximum block size to
the server for a resource that it expects to be large enough to require a blockwise transfer (see
RFC7959 Figure 3: Block-Wise GET with Early Negotiation).

.. code-block:: c

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

    /* static, since options must remain valid throughout the whole execution of the request */
    static struct coap_client_option block2_option;

    coap_client_init(&client, NULL);
    block2_option = coap_client_option_initial_block2();

    req.method = COAP_METHOD_GET;
    req.confirmable = true;
    req.path = "test";
    req.fmt = COAP_CONTENT_FORMAT_TEXT_PLAIN;
    req.cb = response_cb;
    req.options = &block2_option;
    req.num_options = 1;
    req.payload = NULL;
    req.len = 0;

    ret = coap_client_req(&client, sock, &address, &req, -1);

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

.. doxygengroup:: coap_client