1.. _coap_client_interface:
2
3CoAP client
4###########
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13The CoAP client library allows application to send CoAP requests and parse CoAP responses.
14The library can be enabled with :kconfig:option:`CONFIG_COAP_CLIENT` Kconfig option.
15The application is notified about the response via a callback that is provided to the API
16in the request. The CoAP client handles the communication over sockets.
17As the CoAP client doesn't create socket it is using, the application is responsible for creating
18the socket. Plain UDP or DTLS sockets are supported.
19
20Sample Usage
21************
22
23The following is an example of a CoAP client initialization and request sending:
24
25.. code-block:: c
26
27    static struct coap_client;
28    struct coap_client_request req = { 0 };
29
30    coap_client_init(&client, NULL);
31
32    req.method = COAP_METHOD_GET;
33    req.confirmable = true;
34    req.path = "test";
35    req.fmt = COAP_CONTENT_FORMAT_TEXT_PLAIN;
36    req.cb = response_cb;
37    req.payload = NULL;
38    req.len = 0;
39
40    /* Sock is a file descriptor referencing a socket, address is the sockaddr struct for the
41     * destination address of the request or NULL if the socket is already connected.
42     */
43    ret = coap_client_req(&client, sock, &address, &req, -1);
44
45Before any requests can be sent, the CoAP client needs to be initialized.
46After initialization, the application can send a CoAP request and wait for the response.
47Currently only one request can be sent for a single CoAP client at a time. There can be multiple
48CoAP clients.
49
50The callback provided in the callback will be called in following cases:
51
52- There is a response for the request
53- The request failed for some reason
54
55The callback contains a flag ``last_block``, which indicates if there is more data to come in the
56response and means that the current response is part of a blockwise transfer. When the
57``last_block`` is set to true, the response is finished and the client is ready for the next request
58after returning from the callback.
59
60If the server responds to the request, the library provides the response to the
61application through the response callback registered in the request structure.
62As the response can be a blockwise transfer and the client calls the callback once per each
63block, the application should be to process all of the blocks to be able to process the response.
64
65The following is an example of a very simple response handling function:
66
67.. code-block:: c
68
69    void response_cb(int16_t code, size_t offset, const uint8_t *payload, size_t len,
70                     bool last_block, void *user_data)
71    {
72        if (code >= 0) {
73	        LOG_INF("CoAP response from server %d", code);
74                if (last_block) {
75                        LOG_INF("Last packet received");
76                }
77        } else {
78                LOG_ERR("Error in sending request %d", code);
79        }
80    }
81
82CoAP options may also be added to the request by the application. The following is an example of
83the application adding a Block2 option to the initial request, to suggest a maximum block size to
84the server for a resource that it expects to be large enough to require a blockwise transfer (see
85RFC7959 Figure 3: Block-Wise GET with Early Negotiation).
86
87.. code-block:: c
88
89    static struct coap_client;
90    struct coap_client_request req = { 0 };
91
92    /* static, since options must remain valid throughout the whole execution of the request */
93    static struct coap_client_option block2_option;
94
95    coap_client_init(&client, NULL);
96    block2_option = coap_client_option_initial_block2();
97
98    req.method = COAP_METHOD_GET;
99    req.confirmable = true;
100    req.path = "test";
101    req.fmt = COAP_CONTENT_FORMAT_TEXT_PLAIN;
102    req.cb = response_cb;
103    req.options = &block2_option;
104    req.num_options = 1;
105    req.payload = NULL;
106    req.len = 0;
107
108    ret = coap_client_req(&client, sock, &address, &req, -1);
109
110API Reference
111*************
112
113.. doxygengroup:: coap_client
114