CoAP client

Overview 

The CoAP client library allows application to send CoAP requests and parse CoAP responses. The library can be enabled with 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:

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:

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 

group coap_client

CoAP client API.

Defines

MAX_COAP_MSG_LEN

Typedefs

typedef void (*coap_client_response_cb_t)(int16_t result_code, size_t offset, const uint8_t *payload, size_t len, bool last_block, void *user_data)

Callback for CoAP request.

This callback is called for responses to CoAP client requests. It is used to indicate errors, response codes from server or to deliver payload. Blockwise transfers cause this callback to be called sequentially with increasing payload offset and only partial content in buffer pointed by payload parameter.

Param result_code:: Result code of the response. Negative if there was a failure in send. coap_response_code for positive.
Param offset:: Payload offset from the beginning of a blockwise transfer.
Param payload:: Buffer containing the payload from the response. NULL for empty payload.
Param len:: Size of the payload.
Param last_block:: Indicates the last block of the response.
Param user_data:: User provided context.

Functions

int coap_client_init(struct coap_client *client, const char *info)

Initialize the CoAP client.

Parameters:

client – [in] Client instance.
info – [in] Name for the receiving thread of the client. Setting this NULL will result as default name of “coap_client”.

Returns:

int Zero on success, otherwise a negative error code.

int coap_client_req(struct coap_client *client, int sock, const struct sockaddr *addr, struct coap_client_request *req, struct coap_transmission_parameters *params)

Send CoAP request.

Operation is handled asynchronously using a background thread. If the socket isn’t connected to a destination address, user must provide a destination address, otherwise the address should be set as NULL. Once the callback is called with last block set as true, socket can be closed or used for another query.

Parameters:

client – Client instance.
sock – Open socket file descriptor.
addr – the destination address of the request, NULL if socket is already connected.
req – CoAP request structure
params – Pointer to transmission parameters structure or NULL to use default values.

Returns:

zero when operation started successfully or negative error code otherwise.

struct coap_client_request

#include <coap_client.h>

Representation of a CoAP client request.

Public Members

enum coap_method method: Method of the request.

bool confirmable: CoAP Confirmable/Non-confirmable message.

const char *path: Path of the requested resource.

enum coap_content_format fmt: Content format to be used.

uint8_t *payload: User allocated buffer for send request.

size_t len: Length of the payload.

coap_client_response_cb_t cb: Callback when response received.

struct coap_client_option *options: Extra options to be added to request.

uint8_t num_options: Number of extra options.

void *user_data: User provided context.

struct coap_client_option: #include <coap_client.h>

Representation of extra options for the CoAP client request.

CoAP client

Overview

Sample Usage

API Reference

Overview 

Sample Usage 

API Reference 