message.h

Go to the documentation of this file.

/*
 * Copyright (C) 2024-2025 Carl Seifert
 * Copyright (C) 2024-2025 TU Dresden
 *
 * This file is subject to the terms and conditions of the GNU Lesser General
 * Public License v2.1. See the file LICENSE in the top level directory for
 * more details.
 */
 
#pragma once
 
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include <string.h>
 
#include "iolist.h"
 
#include "net/unicoap/constants.h"
#include "net/unicoap/options.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* MARK: - CoAP message */
typedef enum {
    UNICOAP_PAYLOAD_CONTIGUOUS = 0,
 
    UNICOAP_PAYLOAD_NONCONTIGUOUS = 1
} unicoap_payload_representation_t;
 
typedef struct {
    unicoap_options_t* options;
 
    union {
        struct {
            uint8_t* payload;
 
            size_t payload_size;
        };
 
        iolist_t* payload_chunks;
    };
 
    union {
        uint8_t code;
 
        /* Note:
         * Method, status, and signal are guaranteed to have the same size as uint8_t,
         * see static_asserts in definitions.h
         */
 
        unicoap_method_t method;
 
        unicoap_status_t status;
 
        unicoap_signal_t signal;
    };
 
    unicoap_payload_representation_t payload_representation : 1;
} unicoap_message_t;
 
static inline uint8_t* unicoap_message_payload_get(unicoap_message_t* message)
{
    assert(message->payload_representation == UNICOAP_PAYLOAD_CONTIGUOUS);
    return message->payload;
}
 
static inline void unicoap_message_payload_set(unicoap_message_t* message, uint8_t* payload,
                                               size_t size)
{
    message->payload_representation = UNICOAP_PAYLOAD_CONTIGUOUS;
    message->payload = payload;
    message->payload_size = size;
}
 
static inline iolist_t* unicoap_message_payload_get_chunks(unicoap_message_t* message)
{
    assert(message->payload_representation == UNICOAP_PAYLOAD_NONCONTIGUOUS);
    return message->payload_chunks;
}
 
static inline void unicoap_message_payload_set_chunks(unicoap_message_t* message, iolist_t* chunks)
{
    message->payload_representation = UNICOAP_PAYLOAD_NONCONTIGUOUS;
    message->payload_chunks = chunks;
}
 
void unicoap_message_payload_append_chunk(unicoap_message_t* message, iolist_t* chunk);
 
static inline size_t unicoap_message_payload_get_size(const unicoap_message_t* message)
{
    return message->payload_representation == UNICOAP_PAYLOAD_NONCONTIGUOUS ?
               iolist_size(message->payload_chunks) :
               message->payload_size;
}
 
bool unicoap_message_payload_is_empty(const unicoap_message_t* message);
 
ssize_t unicoap_message_payload_copy(const unicoap_message_t* message, uint8_t* buffer,
                                     size_t capacity);
 
ssize_t unicoap_message_payload_make_contiguous(unicoap_message_t* message, uint8_t* buffer,
                                                size_t capacity);
 
typedef struct {
    uint8_t* token;
 
    uint8_t token_length : UNICOAP_TOKEN_LENGTH_FIXED_WIDTH;
 
    bool is_registration : 1;
 
    bool is_notification : 1;
 
    struct {
        unicoap_rfc7252_message_type_t type : UNICOAP_RFC7252_MESSAGE_TYPE_FIXED_WIDTH;
 
        uint16_t id;
    } rfc7252;
 
} unicoap_message_properties_t;
 
const char* unicoap_string_from_rfc7252_type(unicoap_rfc7252_message_type_t type);
 
static inline uint8_t* unicoap_message_options_data(const unicoap_message_t* message)
{
    return message->options ? message->options->entries->data : NULL;
}
 
static inline size_t unicoap_message_options_size(const unicoap_message_t* message)
{
    return message->options ? message->options->storage_size : 0;
}
/* MARK: - CoAP code */
static inline uint8_t unicoap_code_class(uint8_t code)
{
    return code >> 5;
}
 
static inline uint8_t unicoap_code_detail(uint8_t code)
{
    return code & 0x1f;
}
 
int unicoap_print_code(uint8_t code, char* string);
 
const char* unicoap_string_from_code(uint8_t code);
 
const char* unicoap_string_from_code_class(uint8_t code);
/* MARK: - Message initializers */
static inline void unicoap_message_init_empty(unicoap_message_t* message, uint8_t code)
{
    message->code = code;
    message->options = NULL;
    message->payload = NULL;
    message->payload_size = 0;
}
 
static inline unicoap_message_t unicoap_message_alloc_empty(uint8_t code)
{
    return (unicoap_message_t){ .code = code };
}
 
static inline void unicoap_message_init(unicoap_message_t* message, uint8_t code, uint8_t* payload,
                                        size_t payload_size)
{
    message->code = code;
    message->options = NULL;
    message->payload = payload;
    message->payload_size = payload_size;
}
 
static inline unicoap_message_t unicoap_message_alloc(uint8_t code, uint8_t* payload,
                                                      size_t payload_size)
{
    return (unicoap_message_t){ .code = code, .payload = payload, .payload_size = payload_size };
}
 
static inline void unicoap_message_init_string(unicoap_message_t* message, uint8_t code,
                                               const char* payload)
{
    message->code = code;
    message->options = NULL;
    message->payload = (uint8_t*)payload;
    message->payload_size = payload ? strlen(payload) : 0;
}
 
static inline unicoap_message_t unicoap_message_alloc_string(uint8_t code, const char* payload)
{
    return (unicoap_message_t){ .code = code,
                                .payload = (uint8_t*)payload,
                                .payload_size = payload ? strlen(payload) : 0 };
}
 
static inline void unicoap_message_init_with_options(unicoap_message_t* message, uint8_t code,
                                                     uint8_t* payload, size_t payload_size,
                                                     unicoap_options_t* options)
{
    message->code = code;
    message->options = options;
    message->payload = payload;
    message->payload_size = payload_size;
}
 
static inline unicoap_message_t unicoap_message_alloc_with_options(uint8_t code, uint8_t* payload,
                                                                   size_t payload_size,
                                                                   unicoap_options_t* options)
{
    return (unicoap_message_t){
        .code = code, .options = options, .payload = payload, .payload_size = payload_size
    };
}
 
static inline
void unicoap_message_init_string_with_options(unicoap_message_t* message, uint8_t code,
                                              const char* payload,
                                              unicoap_options_t* options)
{
    unicoap_message_init_with_options(message, code, (uint8_t*)payload,
                                      payload ? strlen(payload) : 0, options);
}
 
static inline
unicoap_message_t unicoap_message_alloc_string_with_options(uint8_t code,
                                                            const char* payload,
                                                            unicoap_options_t* options)
{
    return (unicoap_message_t){ .code = code,
                                .options = options,
                                .payload = (uint8_t*)payload,
                                .payload_size = payload ? strlen(payload) : 0 };
}
/* MARK: - Signaling messages */
static inline bool unicoap_message_is_signal(uint8_t code)
{
    return unicoap_code_class(code) == UNICOAP_CODE_CLASS_SIGNAL;
}
 
static inline unicoap_signal_t unicoap_message_get_signal(const unicoap_message_t* message)
{
    return message->signal;
}
 
static inline void unicoap_message_set_signal(unicoap_message_t* message, unicoap_signal_t signal)
{
    message->signal = signal;
}
 
const char* unicoap_string_from_signal(unicoap_signal_t signal);
/* MARK: - Request messages */
static inline bool unicoap_message_is_request(uint8_t code)
{
    return unicoap_code_class(code) == UNICOAP_CODE_CLASS_REQUEST;
}
 
static inline unicoap_method_t unicoap_request_get_method(const unicoap_message_t* request)
{
    return request->method;
}
 
static inline void unicoap_request_set_method(unicoap_message_t* request, unicoap_method_t method)
{
    request->method = method;
}
 
const char* unicoap_string_from_method(unicoap_method_t method);
 
static inline void unicoap_request_init_empty(unicoap_message_t* request, unicoap_method_t method)
{
    unicoap_message_init_empty(request, (uint8_t)method);
}
 
static inline unicoap_message_t unicoap_request_alloc_empty(unicoap_method_t method)
{
    return unicoap_message_alloc_empty((uint8_t)method);
}
 
static inline void unicoap_request_init(unicoap_message_t* request, unicoap_method_t method,
                                        uint8_t* payload, size_t payload_size)
{
    unicoap_message_init(request, (uint8_t)method, payload, payload_size);
}
 
static inline unicoap_message_t unicoap_request_alloc(unicoap_method_t method, uint8_t* payload,
                                                      size_t payload_size)
{
    return unicoap_message_alloc((uint8_t)method, payload, payload_size);
}
 
static inline void unicoap_request_init_string(unicoap_message_t* request, unicoap_method_t method,
                                               const char* payload)
{
    unicoap_message_init_string(request, (uint8_t)method, payload);
}
 
static inline unicoap_message_t unicoap_request_alloc_string(unicoap_method_t method,
                                                             const char* payload)
{
    return unicoap_message_alloc_string((uint8_t)method, payload);
}
 
static inline void unicoap_request_init_with_options(unicoap_message_t* request,
                                                     unicoap_method_t method,
                                                     uint8_t* payload, size_t payload_size,
                                                     unicoap_options_t* options)
{
    unicoap_message_init_with_options(request, (uint8_t)method, payload, payload_size, options);
}
 
static inline unicoap_message_t unicoap_request_alloc_with_options(unicoap_method_t method,
                                                                   uint8_t* payload,
                                                                   size_t payload_size,
                                                                   unicoap_options_t* options)
{
    return unicoap_message_alloc_with_options((uint8_t)method, payload, payload_size, options);
}
 
static inline void unicoap_request_init_string_with_options(unicoap_message_t* request,
                                                            unicoap_method_t method,
                                                            const char* payload,
                                                            unicoap_options_t* options)
{
    unicoap_message_init_string_with_options(request, (uint8_t)method, payload, options);
}
 
static inline
unicoap_message_t unicoap_request_alloc_string_with_options(unicoap_method_t method,
                                                            const char* payload,
                                                            unicoap_options_t* options)
{
    return unicoap_message_alloc_string_with_options((uint8_t)method, payload, options);
}
/* MARK: - Response messages */
bool unicoap_message_is_response(uint8_t code);
 
static inline unicoap_status_t unicoap_response_get_status(const unicoap_message_t* response)
{
    return response->status;
}
 
static inline void unicoap_response_set_status(unicoap_message_t* response, unicoap_status_t status)
{
    response->status = status;
}
 
const char* unicoap_string_from_status(unicoap_status_t status);
 
static inline void unicoap_response_init_empty(unicoap_message_t* response, unicoap_status_t status)
{
    unicoap_message_init_empty(response, (uint8_t)status);
}
 
static inline unicoap_message_t unicoap_response_alloc_empty(unicoap_status_t status)
{
    return unicoap_message_alloc_empty((uint8_t)status);
}
 
static inline void unicoap_response_init(unicoap_message_t* response, unicoap_status_t status,
                                         uint8_t* payload, size_t payload_size)
{
    unicoap_message_init(response, (uint8_t)status, payload, payload_size);
}
 
static inline unicoap_message_t unicoap_response_alloc(unicoap_status_t status, uint8_t* payload,
                                                       size_t payload_size)
{
    return unicoap_message_alloc((uint8_t)status, payload, payload_size);
}
 
static inline void unicoap_response_init_string(unicoap_message_t* response,
                                                unicoap_status_t status, const char* payload)
{
    unicoap_message_init_string(response, (uint8_t)status, payload);
}
 
static inline unicoap_message_t unicoap_response_alloc_string(unicoap_status_t status,
                                                              const char* payload)
{
    return unicoap_message_alloc_string((uint8_t)status, payload);
}
 
static inline void unicoap_response_init_with_options(unicoap_message_t* response,
                                                      unicoap_status_t status,
                                                      uint8_t* payload,
                                                      size_t payload_size,
                                                      unicoap_options_t* options)
{
    unicoap_message_init_with_options(response, (uint8_t)status, payload, payload_size, options);
}
 
static inline unicoap_message_t unicoap_response_alloc_with_options(unicoap_status_t status,
                                                                    uint8_t* payload,
                                                                    size_t payload_size,
                                                                    unicoap_options_t* options)
{
    return unicoap_message_alloc_with_options((uint8_t)status, payload, payload_size, options);
}
 
static inline void unicoap_response_init_string_with_options(unicoap_message_t* response,
                                                             unicoap_status_t status,
                                                             const char* payload,
                                                             unicoap_options_t* options)
{
    unicoap_message_init_string_with_options(response, (uint8_t)status, payload, options);
}
 
static inline
unicoap_message_t unicoap_response_alloc_string_with_options(unicoap_status_t status,
                                                             const char* payload,
                                                             unicoap_options_t* options)
{
    return unicoap_message_alloc_string_with_options((uint8_t)status, payload, options);
}
/* MARK: - Parsing and Serialization ------------------------------------------------------- */
/* MARK: - Parsing */
typedef ssize_t (*unicoap_parser_t)(const uint8_t* pdu, size_t size, unicoap_message_t* message,
                                    unicoap_message_properties_t* properties);
 
typedef struct {
    unicoap_message_t message;
 
    unicoap_options_t options;
 
    unicoap_message_properties_t properties;
} unicoap_parser_result_t;
 
ssize_t unicoap_pdu_parse_options_and_payload(uint8_t* cursor, const uint8_t* end,
                                              unicoap_message_t* message);
/* MARK: - Serializing */
ssize_t unicoap_pdu_build_options_and_payload(uint8_t* cursor, size_t remaining_capacity,
                                              const unicoap_message_t* message);
 
#define UNICOAP_PDU_IOLIST_COUNT (4)
 
int unicoap_pdu_buildv_options_and_payload(uint8_t* header, size_t header_size,
                                           const unicoap_message_t* message,
                                           iolist_t iolists[UNICOAP_PDU_IOLIST_COUNT]);
ssize_t unicoap_pdu_parse_rfc7252(uint8_t* pdu, size_t size, unicoap_message_t* message,
                                  unicoap_message_properties_t* properties);
 
static inline ssize_t unicoap_pdu_parse_rfc7252_result(uint8_t* pdu, size_t size,
                                                       unicoap_parser_result_t* parsed)
{
    parsed->message.options = &parsed->options;
    return unicoap_pdu_parse_rfc7252(pdu, size, &parsed->message, &parsed->properties);
}
ssize_t unicoap_pdu_build_header_rfc7252(uint8_t* header, size_t capacity,
                                         const unicoap_message_t* message,
                                         const unicoap_message_properties_t* properties);
 
static inline ssize_t unicoap_pdu_build_rfc7252(uint8_t* pdu, size_t capacity,
                                                const unicoap_message_t* message,
                                                const unicoap_message_properties_t* properties)
{
    ssize_t res = 0;
 
    if ((res = unicoap_pdu_build_header_rfc7252(pdu, capacity, message, properties)) < 0) {
        return res;
    }
    return unicoap_pdu_build_options_and_payload(pdu + res, capacity - res, message) + res;
}
 
/* MARK: unicoap_driver_extension_point */
 
static inline ssize_t unicoap_pdu_buildv_rfc7252(uint8_t* header, size_t header_capacity,
                                                 const unicoap_message_t* message,
                                                 const unicoap_message_properties_t* properties,
                                                 iolist_t iolists[UNICOAP_PDU_IOLIST_COUNT])
{
    ssize_t res = 0;
 
    if ((res =
         unicoap_pdu_build_header_rfc7252(header, header_capacity, message, properties)) < 0) {
        return res;
    }
    return unicoap_pdu_buildv_options_and_payload(header, res, message, iolists);
}
 
/* MARK: unicoap_driver_extension_point */
 
#ifdef __cplusplus
}
#endif