<commit_before>/*
 * Copyright (C) 2017 <NAME>
 *
 * 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.
 */

/**
 * @defgroup    net_emcute MQTT-SN Client (emCute)
 * @ingroup     net
 * @brief       emCute, the MQTT-SN implementation for RIOT
 *
 * # About
 * emCute is the implementation of the OASIS MQTT-SN protocol for RIOT. It is
 * designed with a focus on small memory footprint and usability.
 *
 *
 * # Design Decisions and Restrictions
 * * emCute is designed to run on top of UDP only, making use of
 * @ref net_sock_udp. The design is not intended to be used with any other
 * transport.
 *
 * The implementation is based on a 2-thread model: emCute needs one thread of
 * its own, in which receiving of packets and sending of ping messages are
 * handled. All 'user space functions' have to run from (a) different (i.e.
 * user) thread(s). emCute uses thread flags to synchronize between threads.
 *
 * Further know restrictions are:
 * - ASCII topic names only (no support for UTF8 names, yet)
 * - topic length is restricted to fit in a single length byte (248 byte max)
 * - no support for wildcards in topic names. This feature requires more
 *   elaborate internal memory management, supposedly at the cost of quite
 *   increased ROM and RAM usage
 * - no retransmit when receiving a REJ_CONG (reject, reason congestion). when
 *   getting a REJ_CONG (reject, reason congestion), the spec tells us to resend
 *   the original message after T_WAIT (default: >5min). This is not supported,
 *   as this would require to block to calling thread (or keep state) for long
 *   periods of time and is (in Hauke's opinion) not feasible for constrained
 *   nodes.
 *
 *
 * # Error Handling
 * This implementation tries minimize parameter checks to a minimum, checking as
 * many parameters as feasible using assertions. For the sake of run-time
 * stability and usability, typical overflow checks are always done during run-
 * time and explicit error values returned in case of errors.
 *
 *
 * # Implementation state
 * In the current state, emCute supports:
 * - connecting to a gateway
 * - disconnecting from gateway
 * - registering a last will topic and message during connection setup
 * - registering topic names with the gateway (obtaining topic IDs)
 * - subscribing to topics
 * - unsubscribing from topics
 * - updating will topic
 * - updating will message
 * - sending out periodic PINGREQ messages
 * - handling re-transmits
 *
 * The following features are however still missing (but planned):
 * @todo        Gateway discovery (so far there is no support for handling
 *              ADVERTISE, GWINFO, and SEARCHGW). Open question to answer here:
 *              how to put / how to encode the IPv(4/6) address AND the port of
 *              a gateway in the GwAdd field of the GWINFO message
 * @todo        QOS level 2
 * @todo        put the node to sleep (send DISCONNECT with duration field set)
 * @todo        handle DISCONNECT messages initiated by the broker/gateway
 * @todo        support for pre-defined and short topic IDs
 * @todo        handle (previously) active subscriptions on reconnect/disconnect
 * @todo        handle re-connect/disconnect from unresponsive gateway (in case
 *              a number of ping requests are unanswered)
 * @todo        react only to incoming ping requests that are actually send by
 *              the gateway we are connected to
 *
 * @{
 * @file
 * @brief       emCute MQTT-SN interface definition
 *
 * @author      <NAME> <<EMAIL>>
 */

#ifndef NET_EMCUTE_H
#define NET_EMCUTE_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#include "net/sock/udp.h"

#ifdef __cplusplus
extern "C" {
#endif

#ifndef EMCUTE_DEFAULT_PORT
/**
 * @brief   Default UDP port to listen on (also used as SRC port)
 */
#define EMCUTE_DEFAULT_PORT     (1883U)
#endif

#ifndef EMCUTE_BUFSIZE
/**
 * @brief   Buffer size used for emCute's transmit and receive buffers
 *
 * The overall buffer size used by emCute is this value time two (Rx + Tx).
 */
#define EMCUTE_BUFSIZE          (512U)
#endif

#ifndef EMCUTE_ID_MAXLEN
/**
 * @brief   Maximum client ID length
 *
 * @note    **Must** be less than (256 - 6) AND less than
 *          (@ref EMCUTE_BUFSIZE - 6).
 */
#define EMCUTE_ID_MAXLEN        (196U)
#endif

#ifndef EMCUTE_TOPIC_MAXLEN
/**
 * @brief   Maximum topic length
 *
 * @note    **Must** be less than (256 - 6) AND less than
 *          (@ref EMCUTE_BUFSIZE - 6).
 */
#define EMCUTE_TOPIC_MAXLEN     (196U)
#endif

#ifndef EMCUTE_KEEPALIVE
/**<commit_msg>net/emcute: added doc for maximum buffer size<commit_after>/*
 * Copyright (C) 2017 <NAME>
 *
 * 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.
 */

/**
 * @defgroup    net_emcute MQTT-SN Client (emCute)
 * @ingroup     net
 * @brief       emCute, the MQTT-SN implementation for RIOT
 *
 * # About
 * emCute is the implementation of the OASIS MQTT-SN protocol for RIOT. It is
 * designed with a focus on small memory footprint and usability.
 *
 *
 * # Design Decisions and Restrictions
 * * emCute is designed to run on top of UDP only, making use of
 * @ref net_sock_udp. The design is not intended to be used with any other
 * transport.
 *
 * The implementation is based on a 2-thread model: emCute needs one thread of
 * its own, in which receiving of packets and sending of ping messages are
 * handled. All 'user space functions' have to run from (a) different (i.e.
 * user) thread(s). emCute uses thread flags to synchronize between threads.
 *
 * Further know restrictions are:
 * - ASCII topic names only (no support for UTF8 names, yet)
 * - topic length is restricted to fit in a single length byte (248 byte max)
 * - no support for wildcards in topic names. This feature requires more
 *   elaborate internal memory management, supposedly at the cost of quite
 *   increased ROM and RAM usage
 * - no retransmit when receiving a REJ_CONG (reject, reason congestion). when
 *   getting a REJ_CONG (reject, reason congestion), the spec tells us to resend
 *   the original message after T_WAIT (default: >5min). This is not supported,
 *   as this would require to block to calling thread (or keep state) for long
 *   periods of time and is (in Hauke's opinion) not feasible for constrained
 *   nodes.
 *
 *
 * # Error Handling
 * This implementation tries minimize parameter checks to a minimum, checking as
 * many parameters as feasible using assertions. For the sake of run-time
 * stability and usability, typical overflow checks are always done during run-
 * time and explicit error values returned in case of errors.
 *
 *
 * # Implementation state
 * In the current state, emCute supports:
 * - connecting to a gateway
 * - disconnecting from gateway
 * - registering a last will topic and message during connection setup
 * - registering topic names with the gateway (obtaining topic IDs)
 * - subscribing to topics
 * - unsubscribing from topics
 * - updating will topic
 * - updating will message
 * - sending out periodic PINGREQ messages
 * - handling re-transmits
 *
 * The following features are however still missing (but planned):
 * @todo        Gateway discovery (so far there is no support for handling
 *              ADVERTISE, GWINFO, and SEARCHGW). Open question to answer here:
 *              how to put / how to encode the IPv(4/6) address AND the port of
 *              a gateway in the GwAdd field of the GWINFO message
 * @todo        QOS level 2
 * @todo        put the node to sleep (send DISCONNECT with duration field set)
 * @todo        handle DISCONNECT messages initiated by the broker/gateway
 * @todo        support for pre-defined and short topic IDs
 * @todo        handle (previously) active subscriptions on reconnect/disconnect
 * @todo        handle re-connect/disconnect from unresponsive gateway (in case
 *              a number of ping requests are unanswered)
 * @todo        react only to incoming ping requests that are actually send by
 *              the gateway we are connected to
 *
 * @{
 * @file
 * @brief       emCute MQTT-SN interface definition
 *
 * @author      <NAME> <<EMAIL>>
 */

#ifndef NET_EMCUTE_H
#define NET_EMCUTE_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#include "net/sock/udp.h"

#ifdef __cplusplus
extern "C" {
#endif

#ifndef EMCUTE_DEFAULT_PORT
/**
 * @brief   Default UDP port to listen on (also used as SRC port)
 */
#define EMCUTE_DEFAULT_PORT     (1883U)
#endif

#ifndef EMCUTE_BUFSIZE
/**
 * @brief   Buffer size used for emCute's transmit and receive buffers
 *
 * @note    The buffer size MUST be less than 32768 on 16-bit and 8-bit
 *          platforms to prevent buffer overflows.
 *
 * The overall buffer size used by emCute is this value time two (Rx + Tx).
 */
#define EMCUTE_BUFSIZE          (512U)
#endif

#ifndef EMCUTE_ID_MAXLEN
/**
 * @brief   Maximum client ID length
 *
 * @note    **Must** be less than (256 - 6) AND less than
 *          (@ref EMCUTE_BUFSIZE - 6).
 */
#define EMCUTE_ID_MAXLEN        (196U)
#endif

#ifndef EMCUTE_TOPIC_MAXLEN
/**
 * @brief   Maximum topic length
 *
 * @note    **Must** be less than (256 - 6) AND less than
 *          (@ref EMCUTE_BUFSIZE - 6).
 */
#define EMCUTE_TOPIC_MAXLEN     (196U)
#endif

#ifndef EMCUTE_KEEPALIVE
/**
{'fraction_non_alphanumeric': 0.07428872497365648, 'fraction_numerical': 0.008851422550052687, 'mean_word_length': 3.103329009943796, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6781594', 'n_tokens_mistral': 2847, 'n_tokens_neox': 2700, 'n_words': 1244}