transport.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2024-2026 Carl Seifert
 * SPDX-FileCopyrightText: 2024-2026 TU Dresden
 * SPDX-License-Identifier: LGPL-2.1-only
 */
 
#pragma once
 
#include <stdbool.h>
#include <stdint.h>
#include "iolist.h"
 
#include "timex.h"
#include "uri_parser.h"
#include "modules.h"
 
#include "net/sock.h"
#include "net/sock/udp.h"
 
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT) || defined(DOXYGEN)
#  include "net/sock/async/event.h"
#  include "net/sock/util.h"
#  include "net/sock/tcp.h"
#endif
 
#if IS_USED(MODULE_UNICOAP_DRIVER_DTLS) || defined(DOXYGEN)
#  include "net/sock/dtls.h"
#endif
 
#if IS_USED(MODULE_UNICOAP_DRIVER_SLIPMUX) || defined(DOXYGEN)
#  include "slipdev.h"
#endif
 
/* MARK: unicoap_driver_extension_point */
 
#include "net/unicoap/message.h"
#include "net/unicoap/options.h"


 
#ifdef __cplusplus
extern "C" {
#endif
 
/* MARK: - CoAP URI schemes */
#define UNICOAP_SCHEME                        "coap"

#define UNICOAP_SCHEME_UDP                    "coap"

#define UNICOAP_SCHEME_DTLS                   "coaps"

#define UNICOAP_SCHEME_TCP                    "coap+tcp"

#define UNICOAP_SCHEME_TLS                    "coaps+tcp"

#define UNICOAP_SCHEME_WEBSOCKET              "coap+ws"

#define UNICOAP_SCHEME_WEBSOCKET_TLS          "coaps+ws"

#define UNICOAP_SCHEME_BLE_GATT               "coap"

#define UNICOAP_SCHEME_SLIPMUX                "coap+uart"

#define UNICOAP_DOMAIN_BLE                    ".ble.arpa"
 
/* MARK: unicoap_driver_extension_point */
 
/* MARK: - Endpoints */
#define UNICOAP_PROTO_UNSPECIFIED             (0)

#define UNICOAP_PROTO_FLAG_RELIABLE_TRANSPORT (1)

typedef enum {
    UNICOAP_PROTO_UDP = 1 << 1,

    UNICOAP_PROTO_DTLS = 2 << 1,

    UNICOAP_PROTO_SLIPMUX = 3 << 1,
 
    /* MARK: unicoap_driver_extension_point */
} __attribute__((__packed__)) unicoap_proto_t;

static inline bool unicoap_transport_is_reliable(unicoap_proto_t proto)
{
    return proto & UNICOAP_PROTO_FLAG_RELIABLE_TRANSPORT;
}

static inline bool unicoap_transport_uses_sock_tl_ep(unicoap_proto_t proto)
{
    switch (proto) {
    case UNICOAP_PROTO_UDP:
    case UNICOAP_PROTO_DTLS:
        return true;
    case UNICOAP_PROTO_SLIPMUX:
        return false;
    /* If a new transport driver does not use RIOT's socket API,
     * such as CoAP over GATT, return false here. */
    /* MARK: unicoap_driver_extension_point */
    default:
        return false;
    }
}

typedef struct {
    unicoap_proto_t proto;
 
    union {
        /* union members are guaranteed to start at offset zero */
 
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT) || defined(DOXYGEN)
        struct _sock_tl_ep _tl_ep;
 
        /* _tl_ep acts as a view on both udp_ep and dtls_ep. */

        sock_udp_ep_t udp_ep;

        sock_udp_ep_t dtls_ep;
#endif /* IS_USED(MODULE_UNICOAP_SOCK_SUPPORT) || defined(DOXYGEN) */
#if IS_USED(MODULE_UNICOAP_DRIVER_SLIPMUX) || defined(DOXYGEN)
        slipdev_t *slipmux_ep;
#endif /* IS_USED(MODULE_UNICOAP_DRIVER_SLIPMUX) || defined(DOXYGEN) */
        /* MARK: unicoap_driver_extension_point */
    };
} unicoap_endpoint_t;

static inline sock_udp_ep_t* unicoap_endpoint_get_udp(unicoap_endpoint_t* endpoint)
{
    (void)endpoint;
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT)
    return &endpoint->udp_ep;
#else
    return NULL;
#endif
}

static inline sock_udp_ep_t* unicoap_endpoint_get_dtls(unicoap_endpoint_t* endpoint)
{
    (void)endpoint;
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT)
    return &endpoint->dtls_ep;
#else
    return NULL;
#endif
}
 
#ifndef DOXYGEN
static inline struct _sock_tl_ep* _unicoap_endpoint_get_tl(unicoap_endpoint_t* endpoint)
{
    (void)endpoint;
#  if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT)
    return &endpoint->_tl_ep;
#  else
    return NULL;
#  endif
}
#endif /* !defined(DOXYGEN) */

static inline ipv6_addr_t* unicoap_endpoint_get_ipv6_addr(unicoap_endpoint_t* endpoint) {
    (void)endpoint;
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT)
    if (unicoap_transport_uses_sock_tl_ep(endpoint->proto) &&
        (_unicoap_endpoint_get_tl(endpoint)->family == AF_INET6 ||
         _unicoap_endpoint_get_tl(endpoint)->family == AF_UNSPEC)) {
        return (ipv6_addr_t*)_unicoap_endpoint_get_tl(endpoint)->addr.ipv6;
    }
    else {
        return NULL;
    }
#else
    return NULL;
#endif
    /* Other drivers may also use IPv6 addresses but not sock_tl... */
    /* MARK: unicoap_driver_extension_point */
}

static inline ipv4_addr_t* unicoap_endpoint_get_ipv4_addr(unicoap_endpoint_t* endpoint) {
    (void)endpoint;
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT)
    if (unicoap_transport_uses_sock_tl_ep(endpoint->proto) &&
        (_unicoap_endpoint_get_tl(endpoint)->family == AF_INET ||
         _unicoap_endpoint_get_tl(endpoint)->family == AF_UNSPEC)) {
        return (ipv4_addr_t*)_unicoap_endpoint_get_tl(endpoint)->addr.ipv4;
    }
    else {
        return NULL;
    }
#else
    return NULL;
#endif
    /* Other drivers may also use IPv4 addresses but not sock_tl... */
    /* MARK: unicoap_driver_extension_point */
}

static inline int* unicoap_endpoint_get_address_family(unicoap_endpoint_t* endpoint) {
    (void)endpoint;
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT)
    if (unicoap_transport_uses_sock_tl_ep(endpoint->proto)) {
        return &_unicoap_endpoint_get_tl(endpoint)->family;
    } else {
        return NULL;
    }
#else
    return NULL;
#endif
    /* Other drivers may also use 16-bit ports but not sock_tl... */
    /* MARK: unicoap_driver_extension_point */
}

static inline uint16_t* unicoap_endpoint_get_port(unicoap_endpoint_t* endpoint) {
    (void)endpoint;
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT)
    if (unicoap_transport_uses_sock_tl_ep(endpoint->proto)) {
        return &_unicoap_endpoint_get_tl(endpoint)->port;
    } else {
        return NULL;
    }
#else
    return NULL;
#endif
    /* Other drivers may also use 16-bit ports but not sock_tl... */
    /* MARK: unicoap_driver_extension_point */
}

static inline uint16_t* unicoap_endpoint_get_netif_id(unicoap_endpoint_t* endpoint) {
    (void)endpoint;
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT)
    if (unicoap_transport_uses_sock_tl_ep(endpoint->proto)) {
        return &_unicoap_endpoint_get_tl(endpoint)->netif;
    } else {
        return NULL;
    }
#else
    return NULL;
#endif
    /* Other drivers may also use 16-bit ports but not sock_tl... */
    /* MARK: unicoap_driver_extension_point */
}

 
/* MARK: - Request destinations */

typedef enum {
    UNICOAP_DESTINATION_ENDPOINT = 0,

    UNICOAP_DESTINATION_HOST = 1,

    UNICOAP_DESTINATION_URI = 2,
} __attribute__((__packed__)) unicoap_destination_type_t;

typedef struct {
    union {
        unicoap_endpoint_t* endpoint;

        const char* uri;

        const char* host;
    } remote;
 
    /* Note that the string length is placed here rather than being in a union with uri and one
     * one with host inside the remote union above. This way, the string length would be considered
     * a separate bitfield; but the goal is to utilise the trailing 2 bytes (at least). */

    uint16_t _string_length : 10;
 
#if !defined(DOXYGEN)
    /* Placeholder for wider type field below and future flags. */
    uint8_t _rfu : 3;
#endif

    unicoap_destination_type_t type : 3;
} unicoap_destination_t;

static inline unicoap_destination_t unicoap_destination_endpoint(unicoap_endpoint_t* endpoint)
{
    return (unicoap_destination_t){ .type = UNICOAP_DESTINATION_ENDPOINT,
                                    .remote.endpoint = endpoint };
}
 
#if !defined(DOXYGEN)
#  define _UNICOAP_DESTINATION_STRING_LENGTH_MAX ((1 << 10) - 1)
#endif

static inline unicoap_destination_t unicoap_destination_host(const char* host, size_t length)
{
    assert(length < _UNICOAP_DESTINATION_STRING_LENGTH_MAX);
    return (unicoap_destination_t){ .type = UNICOAP_DESTINATION_HOST,
                                    .remote.host = host,
                                    ._string_length = (uint16_t)length };
}

static inline unicoap_destination_t unicoap_destination_host_string(const char* host)
{
    return (unicoap_destination_t){ .type = UNICOAP_DESTINATION_HOST,
                                    .remote.host = host,
                                    ._string_length = strlen(host) };
}

static inline unicoap_destination_t unicoap_destination_uri(const char* uri, size_t length)
{
    assert(length < _UNICOAP_DESTINATION_STRING_LENGTH_MAX);
    return (unicoap_destination_t){ .type = UNICOAP_DESTINATION_URI,
                                    .remote.uri = uri,
                                    ._string_length = (uint16_t)length };
}

static inline unicoap_destination_t unicoap_destination_uri_string(const char* uri)
{
    return (unicoap_destination_t){ .type = UNICOAP_DESTINATION_URI,
                                    .remote.uri = uri,
                                    ._string_length = strlen(uri) };
}

 
/* MARK: - Conversions and Tools */

int unicoap_proto_from_scheme_and_host(const char* scheme, size_t scheme_length,
                                       const char* host, size_t length);

static inline int unicoap_transport_proto_from_scheme_and_host_string(
    const char* scheme, const char* host)
{
    return unicoap_proto_from_scheme_and_host(scheme, strlen(scheme), host, strlen(host));
}

const char* unicoap_scheme_from_proto(unicoap_proto_t proto);

const char* unicoap_string_from_proto(unicoap_proto_t proto);

bool unicoap_endpoint_is_equal(const unicoap_endpoint_t* source,
                               const unicoap_endpoint_t* destination);

bool unicoap_endpoint_is_multicast(const unicoap_endpoint_t* endpoint);

#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT) || defined(DOXYGEN)
void unicoap_print_sock_tl_ep(const struct _sock_tl_ep* ep);
#else
static inline void unicoap_print_sock_tl_ep(const void* ep)
{
    (void)ep;
    assert(false);
}
#endif
void unicoap_print_endpoint(const unicoap_endpoint_t* endpoint);

/* MARK: - Sockets */
#if IS_USED(MODULE_UNICOAP_DRIVER_UDP) || defined(DOXYGEN)
sock_udp_t* unicoap_transport_udp_get_socket(void);
#else
static inline
void* unicoap_transport_udp_get_socket(void)
{
    return NULL;
}
#endif
 
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT) || defined(DOXYGEN)
/* sock_udp_t requires an implementation which is not present if someone uses unicoap
 * without a driver, i.e., just message APIs. In this case, unicoap_sock_support is not imported. */

#  if IS_USED(MODULE_UNICOAP_DRIVER_UDP) || defined(DOXYGEN)
int unicoap_transport_udp_add_socket(sock_udp_t* socket, sock_udp_ep_t* local);
#  else
static inline
int unicoap_transport_udp_add_socket(sock_udp_t* socket, sock_udp_ep_t* local)
{
    (void)socket;
    (void)local;
    return 0;
}
#  endif

#  if IS_USED(MODULE_UNICOAP_DRIVER_UDP) || defined(DOXYGEN)
int unicoap_transport_udp_remove_socket(sock_udp_t* socket);
#  else
static inline
int unicoap_transport_udp_remove_socket(sock_udp_t* socket)
{
    (void)socket;
    return 0;
}
#  endif
#endif /* IS_USED(MODULE_UNICOAP_SOCK_SUPPORT) || defined(DOXYGEN) */

/* MARK: - Sockets */
#if IS_USED(MODULE_UNICOAP_DRIVER_DTLS) || defined(DOXYGEN)
sock_dtls_t* unicoap_transport_dtls_get_socket(void);
#else
static inline
void* unicoap_transport_dtls_get_socket(void)
{
    return NULL;
}
#endif
 
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT) || defined(DOXYGEN)
/* sock_udp_t requires an implementation which is not present if someone uses unicoap
 * without a driver, i.e., just message APIs. In this case, unicoap_sock_support is not imported. */

#  if IS_USED(MODULE_UNICOAP_DRIVER_DTLS) || defined(DOXYGEN)
int unicoap_transport_dtls_add_socket(sock_dtls_t* socket, sock_udp_t* base_socket,
                                      sock_udp_ep_t* local);
#  else
static inline
int unicoap_transport_dtls_add_socket(void* socket, void* base_socket, void* local)
{
    (void) socket;
    (void) base_socket;
    (void) local;
    return 0;
}
#  endif

#  if IS_USED(MODULE_UNICOAP_DRIVER_DTLS) || defined(DOXYGEN)
int unicoap_transport_dtls_remove_socket(sock_dtls_t* socket);
#  else
static inline
int unicoap_transport_dtls_remove_socket(void* socket)
{
    (void) socket;
    return 0;
}
#  endif
#endif /* IS_USED(MODULE_UNICOAP_SOCK_SUPPORT) || defined(DOXYGEN) */
 
/* MARK: - Utils */
typedef struct {
    const unicoap_endpoint_t* remote;

    const unicoap_endpoint_t* local;

    const unicoap_message_properties_t* properties;
} unicoap_aux_t;



/* MARK: - Manually parsing a CoAP URI */
int unicoap_uri_populate(uri_parser_result_t* parsed, unicoap_endpoint_t* endpoint,
                         unicoap_options_t* options);
 
#ifdef __cplusplus
}
#endif