patrick/zephyr
1
0
Fork 0
Code Issues Pull requests Actions 7 Packages Projects Releases Wiki Activity

net: mqtt-sn: doc: Fix Doxygen documentation

Browse source 
- Add missing Doxygen comments.
- Fix typo in Doxygen group name.

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This commit is contained in:
Benjamin Cabé 2023-07-18 08:38:55 +02:00 committed by Carles Cufí
parent f2735b6109
commit b76aa7cfaf
1 changed files with 98 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

106
include/zephyr/net/mqtt_sn.h
View file

@ -6,7 +6,7 @@
/** @file mqtt_sn.h
*
* @defgroup mqtt_sn_socket MQTT Client library
* @defgroup mqtt_sn_socket MQTT-SN Client library
* @ingroup networking
* @{
* @brief MQTT-SN Client Implementation
@ -50,11 +50,28 @@ enum mqtt_sn_qos {
* MQTT-SN topic types.
*/
enum mqtt_sn_topic_type {
/**
* Normal topic.
* It allows usage of any valid UTF-8 string as a topic name.
*/
MQTT_SN_TOPIC_TYPE_NORMAL,
/**
* Pre-defined topic.
* It allows usage of a two-byte identifier representing a topic name for
* which the corresponding topic name is known in advance by both the client
* and the gateway/server.
*/
MQTT_SN_TOPIC_TYPE_PREDEF,
/**
* Short topic.
* It allows usage of a two-byte string as a topic name.
*/
MQTT_SN_TOPIC_TYPE_SHORT
};
/**
* MQTT-SN return codes.
*/
enum mqtt_sn_return_code {
MQTT_SN_CODE_ACCEPTED = 0x00, /**< Accepted */
MQTT_SN_CODE_REJECTED_CONGESTION = 0x01, /**< Rejected: congestion */
@ -105,9 +122,13 @@ enum mqtt_sn_evt_type {
* Event metadata.
*/
union mqtt_sn_evt_param {
/** Structure holding publish event details */
struct {
/** The payload data associated with the event */
struct mqtt_sn_data data;
/** The type of topic for the event */
enum mqtt_sn_topic_type topic_type;
/** The identifier for the topic of the event */
uint16_t topic_id;
} publish;
};
@ -116,7 +137,9 @@ union mqtt_sn_evt_param {
* MQTT-SN event structure to be handled by the event callback.
*/
struct mqtt_sn_evt {
/** Event type */
enum mqtt_sn_evt_type type;
/** Event parameters */
union mqtt_sn_evt_param param;
};
@ -212,49 +235,93 @@ int mqtt_sn_transport_udp_init(struct mqtt_sn_transport_udp *udp, struct sockadd
* Structure describing an MQTT-SN client.
*/
struct mqtt_sn_client {
struct mqtt_sn_data client_id; /**< 1-23 character unique client ID */
/** 1-23 character unique client ID */
struct mqtt_sn_data client_id;
struct mqtt_sn_data will_topic; /**< Must be initialized before connecting with will=true */
struct mqtt_sn_data will_msg; /**< Must be initialized before connecting with will=true */
/** Topic for Will message.
* Must be initialized before connecting with will=true
*/
struct mqtt_sn_data will_topic;
/** Will message.
* Must be initialized before connecting with will=true
*/
struct mqtt_sn_data will_msg;
/** Quality of Service for the Will message */
enum mqtt_sn_qos will_qos;
/** Flag indicating if the will message should be retained by the broker */
bool will_retain;
/** Underlying transport to be used by the client */
struct mqtt_sn_transport *transport;
/** Buffer for outgoing data */
struct net_buf_simple tx;
/** Buffer for incoming data */
struct net_buf_simple rx;
/** Event callback */
mqtt_sn_evt_cb_t evt_cb;
/** Message ID for the next message to be sent */
uint16_t next_msg_id;
/** List of pending publish messages */
sys_slist_t publish;
/** List of registered topics */
sys_slist_t topic;
/** Current state of the MQTT-SN client */
int state;
/** Timestamp of the last ping request */
int64_t last_ping;
/** Number of retries for failed ping attempts */
uint8_t ping_retries;
/** Delayable work structure for processing MQTT-SN events */
struct k_work_delayable process_work;
};
/**
* @brief Initialize a client.
*
* @param client The MQTT-SN client to initialize.
* @param client_id The ID to be used by the client.
* @param transport The transport to be used by the client.
* @param evt_cb The event callback function for the client.
* @param tx Pointer to the transmit buffer.
* @param txsz Size of the transmit buffer.
* @param rx Pointer to the receive buffer.
* @param rxsz Size of the receive buffer.
*
* @return 0 or a negative error code (errno.h) indicating reason of failure.
*/
int mqtt_sn_client_init(struct mqtt_sn_client *client, const struct mqtt_sn_data *client_id,
struct mqtt_sn_transport *transport, mqtt_sn_evt_cb_t evt_cb, void *tx,
size_t txsz, void *rx, size_t rxsz);
/**
* @brief Deinitialize the client
* @brief Deinitialize the client.
*
* This removes all topics and publishes, and also deinits the transport.
* This removes all topics and publishes, and also de-inits the transport.
*
* @param client The MQTT-SN client to deinitialize.
*/
void mqtt_sn_client_deinit(struct mqtt_sn_client *client);
/**
* @brief Connect the client.
*
* @param client The MQTT-SN client to connect.
* @param will Flag indicating if a Will message should be sent.
* @param clean_session Flag indicating if a clean session should be started.
*
* @return 0 or a negative error code (errno.h) indicating reason of failure.
*/
int mqtt_sn_connect(struct mqtt_sn_client *client, bool will, bool clean_session);
@ -262,20 +329,29 @@ int mqtt_sn_connect(struct mqtt_sn_client *client, bool will, bool clean_session
/**
* @brief Disconnect the client.
*
* @param client The MQTT-SN client to disconnect.
*
* @return 0 or a negative error code (errno.h) indicating reason of failure.
*/
int mqtt_sn_disconnect(struct mqtt_sn_client *client);
/**
* @brief Set the client into sleep state for the given duration (seconds).
* @brief Set the client into sleep state.
*
* @return 0 or a negative error code (errno.h) indicating reason of failure.
* @param client The MQTT-SN client to be put to sleep.
* @param duration Sleep duration (in seconds).
*
* @return 0 on success, negative errno code on failure.
*/
int mqtt_sn_sleep(struct mqtt_sn_client *client, uint16_t duration);
/**
* @brief Subscribe to a given topic.
*
* @param client The MQTT-SN client that should subscribe.
* @param qos The desired quality of service for the subscription.
* @param topic_name The name of the topic to subscribe to.
*
* @return 0 or a negative error code (errno.h) indicating reason of failure.
*/
int mqtt_sn_subscribe(struct mqtt_sn_client *client, enum mqtt_sn_qos qos,
@ -283,6 +359,12 @@ int mqtt_sn_subscribe(struct mqtt_sn_client *client, enum mqtt_sn_qos qos,
/**
* @brief Unsubscribe from a topic.
*
* @param client The MQTT-SN client that should unsubscribe.
* @param qos The quality of service used when subscribing.
* @param topic_name The name of the topic to unsubscribe from.
*
* @return 0 or a negative error code (errno.h) indicating reason of failure.
*/
int mqtt_sn_unsubscribe(struct mqtt_sn_client *client, enum mqtt_sn_qos qos,
struct mqtt_sn_data *topic_name);
@ -292,6 +374,12 @@ int mqtt_sn_unsubscribe(struct mqtt_sn_client *client, enum mqtt_sn_qos qos,
*
* If the topic is not yet registered with the gateway, the library takes care of it.
*
* @param client The MQTT-SN client that should publish.
* @param qos The desired quality of service for the publish.
* @param topic_name The name of the topic to publish to.
* @param retain Flag indicating if the message should be retained by the broker.
* @param data The data to be published.
*
* @return 0 or a negative error code (errno.h) indicating reason of failure.
*/
int mqtt_sn_publish(struct mqtt_sn_client *client, enum mqtt_sn_qos qos,
@ -303,6 +391,8 @@ int mqtt_sn_publish(struct mqtt_sn_client *client, enum mqtt_sn_qos qos,
* Call this function periodically, or if you have good reason to believe there is any data.
* If the client's transport struct contains a poll-function, this function is non-blocking.
*
* @param client The MQTT-SN client to check for incoming data.
*
* @return 0 or a negative error code (errno.h) indicating reason of failure.
*/
int mqtt_sn_input(struct mqtt_sn_client *client);