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"
 
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT) || defined(DOXYGEN)
#  include "net/sock.h"
#  include "net/sock/async/event.h"
#  include "net/sock/util.h"
#  include "net/sock/udp.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;
 
#if IS_USED(MODULE_UNICOAP_SOCK_SUPPORT) || defined(DOXYGEN)
static inline sock_udp_ep_t* unicoap_endpoint_get_udp(unicoap_endpoint_t* endpoint)
{
    return &endpoint->udp_ep;
}

static inline sock_udp_ep_t* unicoap_endpoint_get_dtls(unicoap_endpoint_t* endpoint)
{
    return &endpoint->dtls_ep;
}
 
#  ifndef DOXYGEN
static inline struct _sock_tl_ep* _unicoap_endpoint_get_tl(unicoap_endpoint_t* endpoint)
{
    return &endpoint->_tl_ep;
}
#  endif /* !defined(DOXYGEN) */
#endif /* IS_USED(MODULE_UNICOAP_SOCK_SUPPORT) || defined(DOXYGEN) */
 
/* MARK: - Conversions and Tools */
 
/* TODO: Client: URI */

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(sock_dtls_t* socket, sock_udp_t* base_socket,
                                      sock_udp_ep_t* 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(sock_dtls_t* 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;


 
#ifdef __cplusplus
}
#endif