server.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 "xfa.h"
#include "ztimer.h"
#include "event.h"
 
#include "net/unicoap/constants.h"
#include "net/unicoap/message.h"
#include "net/unicoap/transport.h"
#include "net/unicoap/util_macros.h"

 
#ifdef __cplusplus
extern "C" {
#endif

 
/* MARK: - Specifying and inspecting resource paths */
typedef struct {
    const char** _components;
} unicoap_pathspec_t;
 
/* Ensure components array is not stored in-place as this will make the resource struct variable
 * in length, screwing XFA resource definitions where resources are assumed to be equal in size. */
static_assert(sizeof(unicoap_pathspec_t) == sizeof(char*),
              "unicoap_pathspec_t is of unexpected size. Please file a bug report.");

 
#define UNICOAP_PATH(...) \
     ((unicoap_pathspec_t) { ._components = (const char*[]) { __VA_ARGS__, \
        _UNICOAP_TRY_CHECK_PATH_COMPONENTS(__VA_ARGS__) ? NULL : NULL } })

#define UNICOAP_PATH_ROOT \
    ((unicoap_pathspec_t) { ._components = NULL })

#define UNICOAP_PATH_RESOURCE_DISCOVERY UNICOAP_PATH(".well-known", "core")

static inline bool unicoap_path_is_root(const unicoap_pathspec_t* path) {
    assert(path);
    return path->_components == NULL;
}

size_t unicoap_path_component_count(const unicoap_pathspec_t* path);

bool unicoap_path_is_equal(const unicoap_pathspec_t* lhs, const unicoap_pathspec_t* rhs);

bool unicoap_path_matches_options(const unicoap_pathspec_t* path,
                                  const unicoap_options_t* options, bool match_subtree);

bool unicoap_path_matches_string(const unicoap_pathspec_t* path,
                                 const char* string, size_t string_length, bool match_subtree);

ssize_t unicoap_path_stringify(const unicoap_pathspec_t* path, char* buffer, size_t capacity);

void unicoap_print_path(const unicoap_pathspec_t* path);
 
#ifndef DOXYGEN
/* Forward declaration */
struct unicoap_resource;
#endif

typedef struct unicoap_resource unicoap_resource_t;
 
/* MARK: - Reacting to CoAP requests */
typedef struct {
    const unicoap_resource_t* resource;

    void* _packet;
} unicoap_request_context_t;

typedef int (*unicoap_request_handler_t)(unicoap_message_t* request, const unicoap_aux_t* aux,
                                         unicoap_request_context_t* ctx, void* arg);

bool unicoap_response_is_optional(unicoap_options_t* options, unicoap_status_t status);

#define UNICOAP_IGNORING_REQUEST (-2042)

int unicoap_send_response(unicoap_message_t* response, unicoap_request_context_t* context);

unicoap_status_t unicoap_response_status_from_errno(int _errno);
 
/* MARK: - Registering CoAP resources */
typedef enum {
    UNICOAP_RESOURCE_FLAG_RELIABLE = 0x0001,

    UNICOAP_RESOURCE_FLAG_MATCH_SUBTREE = 0x4000,
 
    /* TODO: Advanced features */
} unicoap_resource_flags_t;

void unicoap_print_resource_flags(unicoap_resource_flags_t flags);

typedef uint8_t unicoap_proto_set_t;

void unicoap_print_protocols(unicoap_proto_set_t protocols);

typedef uint8_t unicoap_method_set_t;

void unicoap_print_methods(unicoap_method_set_t methods);

struct unicoap_resource {
    const unicoap_pathspec_t path;

    unicoap_request_handler_t handler;

    void* handler_arg;

    unicoap_resource_flags_t flags;

    unicoap_method_set_t methods;

    unicoap_proto_set_t protocols;
};

void unicoap_print_resource(const unicoap_resource_t* resource);
 
/* MARK: - Resource discovery */
ssize_t unicoap_resource_core_link_format_build(char* buffer, size_t capacity,
                                                unicoap_proto_t proto);

typedef struct {
    unicoap_content_format_t content_format;

    size_t link_pos;

    bool uninitialized : 1;
} unicoap_link_encoder_ctx_t;

typedef ssize_t (*unicoap_link_encoder_t)(const unicoap_resource_t* resource, char* buffer,
                                          size_t capacity, unicoap_link_encoder_ctx_t* context);

ssize_t unicoap_resource_encode_link(const unicoap_resource_t* resource, char* buffer,
                                     size_t capacity, unicoap_link_encoder_ctx_t* context);
 
/* MARK: - Matching requests and resources */
typedef struct unicoap_listener unicoap_listener_t;

typedef int (*unicoap_request_matcher_t)(const unicoap_listener_t* listener,
                                         const unicoap_resource_t** resource,
                                         const unicoap_message_t* request,
                                         const unicoap_endpoint_t* endpoint);
struct unicoap_listener {
    const unicoap_resource_t* resources;

    size_t resource_count;

    unicoap_request_matcher_t request_matcher;

    unicoap_link_encoder_t link_encoder;

    unicoap_listener_t* next;

    unicoap_proto_set_t protocols;
};

void unicoap_listener_register(unicoap_listener_t* listener);

int unicoap_listener_deregister(unicoap_listener_t* listener);

static inline bool unicoap_resource_match_path_string(const unicoap_resource_t* resource,
                                                      const char* path, size_t length) {
    return unicoap_path_matches_string(&resource->path, path, length,
                                     (resource->flags & UNICOAP_RESOURCE_FLAG_MATCH_SUBTREE) != 0);
}

static inline bool unicoap_resource_match_path_options(const unicoap_resource_t* resource,
                                                       const unicoap_options_t* options) {
    return unicoap_path_matches_options(&resource->path, options,
                                      (resource->flags & UNICOAP_RESOURCE_FLAG_MATCH_SUBTREE) != 0);
}

 
/* MARK: - Matching methods and protocols */
#define UNICOAP_METHOD_FLAG(method)        (1 << (method))

#define UNICOAP_METHODS(first_method, ...) UNICOAP_BITFIELD(first_method, __VA_ARGS__)

#define UNICOAP_METHODS_ALL                (0xff)

static inline bool unicoap_resource_match_method(unicoap_method_set_t methods, unicoap_method_t method)
{
    return (methods & UNICOAP_METHOD_FLAG(method)) != 0;
}

#define UNICOAP_PROTOCOL_FLAG(proto)        (1 << (proto))

#define UNICOAP_PROTOCOLS(first_proto, ...) UNICOAP_BITFIELD(first_proto, __VA_ARGS__)

#define UNICOAP_PROTOCOLS_ALLOW_ALL         (0)

#define UNICOAP_PROTOCOLS_ALLOW_NONE        (1)

static inline bool unicoap_match_proto(unicoap_proto_set_t protocols, unicoap_proto_t proto)
{
    return protocols  == UNICOAP_PROTOCOLS_ALLOW_ALL ||
        (protocols & UNICOAP_PROTOCOL_FLAG(proto)) != 0;
}


/* MARK: - Declaring a CoAP resource at compile time */
#if IS_USED(MODULE_UNICOAP_SERVER_RESOURCE_DECLARATIONS) || defined(DOXYGEN)
#  define UNICOAP_RESOURCE(name) \
      XFA_CONST(unicoap_resource_t, unicoap_resources_xfa, 0) CONCAT(unicoap_resource_, name) =
#else
#  define UNICOAP_RESOURCE(name)                                                                   \
      static_assert(false,                                                                         \
                    "The unicoap_server_resource_declarations module is missing, resource cannot be registered"); \
      unicoap_resource_t CONCAT(unicoap_resource_, name) =
#endif
 
#ifndef DOXYGEN
extern uint8_t unicoap_receiver_buffer[CONFIG_UNICOAP_PDU_SIZE_MAX];
#endif
 
#ifdef __cplusplus
}
#endif