diff --git a/include/net/mqtt.h b/include/net/mqtt.h
index b05d34f37bc..d7d55e63671 100644
--- a/include/net/mqtt.h
+++ b/include/net/mqtt.h
@@ -17,7 +17,7 @@
*/
/**
- * @brief mqtt_app MQTT application type
+ * MQTT application type
*/
enum mqtt_app {
/** Publisher and Subscriber application */
@@ -31,9 +31,9 @@ enum mqtt_app {
};
/**
- * @brief struct mqtt_ctx MQTT context structure
- * @details
- * Context structure for the MQTT high-level API with support for QoS.
+ * MQTT context structure
+ *
+ * @details Context structure for the MQTT high-level API with support for QoS.
*
* This API is designed for asynchronous operation, so callbacks are
* executed when some events must be addressed outside the MQTT routines.
@@ -74,84 +74,66 @@ struct mqtt_ctx {
/** Callback executed when a #MQTT_APP_PUBLISHER application receives
* a MQTT PUBxxxx msg.
+ * If type is MQTT_PUBACK, MQTT_PUBCOMP or MQTT_PUBREC, this callback
+ * must return 0 if pkt_id matches the packet id of a previously
+ * received MQTT_PUBxxx message. If this callback returns 0, the caller
+ * will continue.
+ * Any other value will stop the QoS handshake and the caller will
+ * return -EINVAL. The application must discard all the messages
+ * already processed.
*
* Note: this callback must be not NULL
*
- * @param [in] ctx MQTT context
- * @param [in] pkt_id Packet Identifier for the input MQTT msg
- * @param [in] type Packet type
- * @return If this callback returns 0, the caller will
- * continue.
- *
- * @return If type is MQTT_PUBACK, MQTT_PUBCOMP or
- * MQTT_PUBREC, this callback must return 0 if
- * pkt_id matches the packet id of a previously
- * received MQTT_PUBxxx message.
- *
- * @return Note: the application must discard all the
- * messages already processed
- *
- * @return Any other value will stop the QoS handshake
- * and the caller will return -EINVAL
+ * @param [in] ctx MQTT context
+ * @param [in] pkt_id Packet Identifier for the input MQTT msg
+ * @param [in] type Packet type
*/
int (*publish_tx)(struct mqtt_ctx *ctx, uint16_t pkt_id,
enum mqtt_packet type);
/** Callback executed when a MQTT_APP_SUBSCRIBER,
- * MQTT_APP_PUBLISHER_SUBSCRIBER or MQTT_APP_SERVER application receive
- * a MQTT PUBxxxx msg.
+ * MQTT_APP_PUBLISHER_SUBSCRIBER or MQTT_APP_SERVER applications receive
+ * a MQTT PUBxxxx msg. If this callback returns 0, the caller will
+ * continue. If type is MQTT_PUBREL this callback must return 0 if
+ * pkt_id matches the packet id of a previously received MQTT_PUBxxx
+ * message. Any other value will stop the QoS handshake and the caller
+ * will return -EINVAL
*
* Note: this callback must be not NULL
*
- * @param [in] ctx MQTT context
- * @param [in] msg Publish message, this parameter is only used
- * when the type is MQTT_PUBLISH
- * @param [in] pkt_id Packet Identifier for the input msg
- * @param [in] type Packet type
- * @return If this callback returns 0, the caller will
- * continue.
- *
- * @return If type is MQTT_PUBREL this callback must return
- * 0 if pkt_id matches the packet id of a
- * previously received MQTT_PUBxxx message.
- *
- * @return Note: the application must discard all the
- * messages already processed
- *
- * @return Any other value will stop the QoS handshake
- * and the caller will return -EINVAL
+ * @param [in] ctx MQTT context
+ * @param [in] msg Publish message, this parameter is only used
+ * when the type is MQTT_PUBLISH
+ * @param [in] pkt_id Packet Identifier for the input msg
+ * @param [in] type Packet type
*/
int (*publish_rx)(struct mqtt_ctx *ctx, struct mqtt_publish_msg *msg,
uint16_t pkt_id, enum mqtt_packet type);
/** Callback executed when a MQTT_APP_SUBSCRIBER or
* MQTT_APP_PUBLISHER_SUBSCRIBER receives the MQTT SUBACK message
+ * If this callback returns 0, the caller will continue. Any other
+ * value will make the caller return -EINVAL.
*
* Note: this callback must be not NULL
*
- * @param [in] ctx MQTT context
- * @param [in] pkt_id Packet Identifier for the MQTT SUBACK msg
- * @param [in] items Number of elements in the qos array
- * @param [in] qos Array of QoS values
- * @return If this callback returns 0, the caller will
- * continue
- * @return Any other value will make the caller return
- * -EINVAL
+ * @param [in] ctx MQTT context
+ * @param [in] pkt_id Packet Identifier for the MQTT SUBACK msg
+ * @param [in] items Number of elements in the qos array
+ * @param [in] qos Array of QoS values
*/
int (*subscribe)(struct mqtt_ctx *ctx, uint16_t pkt_id,
uint8_t items, enum mqtt_qos qos[]);
/** Callback executed when a MQTT_APP_SUBSCRIBER or
* MQTT_APP_PUBLISHER_SUBSCRIBER receives the MQTT UNSUBACK message
+ * If this callback returns 0, the caller will continue. Any other value
+ * will make the caller return -EINVAL
*
* Note: this callback must be not NULL
*
* @param [in] ctx MQTT context
* @param [in] pkt_id Packet Identifier for the MQTT SUBACK msg
- * @return If this callback returns 0, the caller will
- * continue
- * @return Any other value will make the caller return
- * -EINVAL
*/
int (*unsubscribe)(struct mqtt_ctx *ctx, uint16_t pkt_id);
@@ -182,219 +164,253 @@ struct mqtt_ctx {
};
/**
- * @brief mqtt_init Initializes the MQTT context structure
- * @param ctx MQTT context structure
- * @param app_type See enum mqtt_app
- * @return 0, always.
+ * Initializes the MQTT context structure
+ *
+ * @param ctx MQTT context structure
+ * @param app_type See enum mqtt_app
+ * @retval 0, always.
*/
int mqtt_init(struct mqtt_ctx *ctx, enum mqtt_app app_type);
/**
- * @brief mqtt_tx_connect Sends the MQTT CONNECT message
- * @param [in] ctx MQTT context structure
- * @param [in] msg MQTT CONNECT msg
- * @return 0 on success
- * @return -EIO on network error
- * @return -ENOMEM if no data/tx buffer is available
- * @return -EINVAL if invalid data was passed to this
- * routine
+ * Sends the MQTT CONNECT message
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] msg MQTT CONNECT msg
+ *
+ * @retval 0 on success
+ * @retval -EIO
+ * @retval -ENOMEM
+ * @retval -EINVAL
*/
int mqtt_tx_connect(struct mqtt_ctx *ctx, struct mqtt_connect_msg *msg);
/**
- * @brief mqtt_tx_disconnect Send the MQTT DISCONNECT message
- * @param [in] ctx MQTT context structure
- * @return 0 on success
- * @return -EIO on network error
- * @return -ENOMEM if no data/tx buffer is available
- * @return -EINVAL if invalid data was passed to this
- * routine
+ * Send the MQTT DISCONNECT message
+ *
+ * @param [in] ctx MQTT context structure
+ *
+ * @retval 0 on success
+ * @retval -EIO
+ * @retval -ENOMEM
+ * @retval -EINVAL
*/
int mqtt_tx_disconnect(struct mqtt_ctx *ctx);
/**
- * @brief mqtt_tx_puback Sends the MQTT PUBACK message with the given
- * packet id
- * @param [in] ctx MQTT context structure
- * @param [in] id MQTT Packet Identifier
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed to
- * this routine
- * @return -ENOMEM if a tx buffer is not available
- * @return -EIO on network error
+ * Sends the MQTT PUBACK message with the given packet id
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] id MQTT Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
+ * @retval -EIO
*/
int mqtt_tx_puback(struct mqtt_ctx *ctx, uint16_t id);
/**
- * @brief mqtt_tx_pubcomp Sends the MQTT PUBCOMP message with the given
- * packet id
- * @param [in] ctx MQTT context structure
- * @param [in] id MQTT Packet Identifier
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed to
- * this routine
- * @return -ENOMEM if a tx buffer is not available
- * @return -EIO on network error
+ * Sends the MQTT PUBCOMP message with the given packet id
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] id MQTT Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
+ * @retval -EIO
*/
int mqtt_tx_pubcomp(struct mqtt_ctx *ctx, uint16_t id);
/**
- * @brief mqtt_tx_pubrec Sends the MQTT PUBREC message with the given
- * packet id
- * @param [in] ctx MQTT context structure
- * @param [in] id MQTT Packet Identifier
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed to
- * this routine
- * @return -ENOMEM if a tx buffer is not available
- * @return -EIO on network error
+ * Sends the MQTT PUBREC message with the given packet id
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] id MQTT Packet Identifier
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
+ * @retval -EIO
*/
int mqtt_tx_pubrec(struct mqtt_ctx *ctx, uint16_t id);
/**
- * @brief mqtt_tx_pubrel Sends the MQTT PUBREL message with the given
- * packet id
- * @param [in] ctx MQTT context structure
- * @param [in] id MQTT Packet Identifier
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed to
- * this routine
- * @return -ENOMEM if a tx buffer is not available
- * @return -EIO on network error
+ * Sends the MQTT PUBREL message with the given packet id
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] id MQTT Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
+ * @retval -EIO
*/
int mqtt_tx_pubrel(struct mqtt_ctx *ctx, uint16_t id);
/**
- * @brief mqtt_tx_publish Sends the MQTT PUBLISH message
- * @param [in] ctx MQTT context structure
- * @param [in] msg MQTT PUBLISH msg
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed to
- * this routine
- * @return -ENOMEM if a tx buffer is not available
- * @return -EIO on network error
+ * Sends the MQTT PUBLISH message
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] msg MQTT PUBLISH msg
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
+ * @retval -EIO
*/
int mqtt_tx_publish(struct mqtt_ctx *ctx, struct mqtt_publish_msg *msg);
/**
- * @brief mqtt_tx_pingreq Sends the MQTT PINGREQ message
- * @param [in] ctx MQTT context structure
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed to
- * this routine
- * @return -ENOMEM if a tx buffer is not available
- * @return -EIO on network error
+ * Sends the MQTT PINGREQ message
+ *
+ * @param [in] ctx MQTT context structure
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
+ * @retval -EIO
*/
int mqtt_tx_pingreq(struct mqtt_ctx *ctx);
/**
- * @brief mqtt_tx_subscribe Sends the MQTT SUBSCRIBE message
- * @param [in] ctx MQTT context structure
- * @param [in] pkt_id Packet identifier for the MQTT SUBSCRIBE msg
- * @param [in] items Number of elements in 'topics' and 'qos' arrays
- * @param [in] topics Array of 'items' elements containing C strings.
- * For example: {"sensors", "lights", "doors"}
- * @param [in] qos Array of 'items' elements containing MQTT QoS
- * values: MQTT_QoS0, MQTT_QoS1, MQTT_QoS2. For
- * example for the 'topics' array above the
- * following QoS may be used:
- * {MQTT_QoS0, MQTT_QoS2, MQTT_QoS1}, indicating
- * that the subscription to 'lights' must be done
- * with MQTT_QoS2
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed to
- * this routine
- * @return -ENOMEM if a tx buffer is not available
- * @return -EIO on network error
+ * Sends the MQTT SUBSCRIBE message
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] pkt_id Packet identifier for the MQTT SUBSCRIBE msg
+ * @param [in] items Number of elements in 'topics' and 'qos' arrays
+ * @param [in] topics Array of 'items' elements containing C strings.
+ * For example: {"sensors", "lights", "doors"}
+ * @param [in] qos Array of 'items' elements containing MQTT QoS values:
+ * MQTT_QoS0, MQTT_QoS1, MQTT_QoS2. For example for the 'topics'
+ * array above the following QoS may be used: {MQTT_QoS0,
+ * MQTT_QoS2, MQTT_QoS1}, indicating that the subscription to
+ * 'lights' must be done with MQTT_QoS2
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
+ * @retval -EIO
*/
int mqtt_tx_subscribe(struct mqtt_ctx *ctx, uint16_t pkt_id, uint8_t items,
const char *topics[], const enum mqtt_qos qos[]);
/**
- * @brief mqtt_tx_unsubscribe Sends the MQTT UNSUBSCRIBE message
- * @param [in] ctx MQTT context structure
- * @param [in] pkt_id Packet identifier for the MQTT UNSUBSCRIBE msg
- * @param [in] items Number of elements in the 'topics' array
- * @param [in] topics Array of 'items' elements containing C strings
- * @return
+ * Sends the MQTT UNSUBSCRIBE message
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] pkt_id Packet identifier for the MQTT UNSUBSCRIBE msg
+ * @param [in] items Number of elements in the 'topics' array
+ * @param [in] topics Array of 'items' elements containing C strings
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
+ * @retval -EIO
*/
int mqtt_tx_unsubscribe(struct mqtt_ctx *ctx, uint16_t pkt_id, uint8_t items,
const char *topics[]);
+
+/**
+ * Parses and validates the MQTT CONNACK msg
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] rx Data buffer
+ * @param [in] clean_session MQTT clean session parameter
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ */
int mqtt_rx_connack(struct mqtt_ctx *ctx, struct net_buf *rx,
int clean_session);
/**
- * @brief mqtt_rx_puback Parses and validates the MQTT PUBACK message
- * @param [in] ctx MQTT context structure
- * @param [in] rx Data buffer
- * @return 0 on success
- * @return -EINVAL on error
+ * Parses and validates the MQTT PUBACK message
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] rx Data buffer
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_rx_puback(struct mqtt_ctx *ctx, struct net_buf *rx);
/**
- * @brief mqtt_rx_pubcomp Parses and validates the MQTT PUBCOMP message
- * @param [in] ctx MQTT context structure
- * @param [in] rx Data buffer
- * @return 0 on success
- * @return -EINVAL on error
+ * Parses and validates the MQTT PUBCOMP message
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] rx Data buffer
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_rx_pubcomp(struct mqtt_ctx *ctx, struct net_buf *rx);
/**
- * @brief mqtt_rx_pubrec Parses and validates the MQTT PUBREC message
- * @param [in] ctx MQTT context structure
- * @param [in] rx Data buffer
- * @return 0 on success
- * @return -EINVAL on error
+ * Parses and validates the MQTT PUBREC message
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] rx Data buffer
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_rx_pubrec(struct mqtt_ctx *ctx, struct net_buf *rx);
/**
- * @brief mqtt_rx_pubrel Parses and validates the MQTT PUBREL message
- * @details rx is an RX buffer from the IP stack
- * @param [in] ctx MQTT context structure
- * @param [in] rx Data buffer
- * @return 0 on success
- * @return -EINVAL on error
+ * Parses and validates the MQTT PUBREL message
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] rx Data buffer
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_rx_pubrel(struct mqtt_ctx *ctx, struct net_buf *rx);
/**
- * @brief mqtt_rx_pingresp Parses the MQTT PINGRESP message
- * @param [in] ctx MQTT context structure
- * @param [in] rx Data buffer
- * @return 0 on success
- * @return -EINVAL on error
+ * Parses the MQTT PINGRESP message
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] rx Data buffer
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_rx_pingresp(struct mqtt_ctx *ctx, struct net_buf *rx);
/**
- * @brief mqtt_rx_suback Parses the MQTT SUBACK message
- * @param [in] ctx MQTT context structure
- * @param [in] rx Data buffer
- * @return 0 on success
- * @return -EINVAL on error
+ * Parses the MQTT SUBACK message
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] rx Data buffer
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_rx_suback(struct mqtt_ctx *ctx, struct net_buf *rx);
/**
- * @brief mqtt_rx_unsuback Parses the MQTT UNSUBACK message
- * @param [in] ctx MQTT context structure
- * @param [in] rx Data buffer
- * @return 0 on success
- * @return -EINVAL on error
+ * Parses the MQTT UNSUBACK message
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] rx Data buffer
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_rx_unsuback(struct mqtt_ctx *ctx, struct net_buf *rx);
/**
- * @brief mqtt_rx_publish Parses the MQTT PUBLISH message
- * @param [in] ctx MQTT context structure
- * @param [in] rx Data buffer
- * @return 0 on success
- * @return -EINVAL on error
- * @return -ENOMEM if no data buffer is available
+ * Parses the MQTT PUBLISH message
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] rx Data buffer
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
*/
int mqtt_rx_publish(struct mqtt_ctx *ctx, struct net_buf *rx);
diff --git a/subsys/net/lib/mqtt/mqtt.c b/subsys/net/lib/mqtt/mqtt.c
index 9b57c8cf410..a6500bc9edf 100644
--- a/subsys/net/lib/mqtt/mqtt.c
+++ b/subsys/net/lib/mqtt/mqtt.c
@@ -113,16 +113,16 @@ exit_disconnect:
}
/**
- * @brief mqtt_tx_pub_msgs Writes the MQTT PUBxxx msg indicated by pkt_type
- * with identifier 'id'
- * @param [in] ctx MQTT context
- * @param [in] id MQTT packet identifier
- * @param [in] pkt_type MQTT packet type
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed to
- * this routine
- * @return -ENOMEM if a tx buffer is not available
- * @return -EIO on network error
+ * Writes the MQTT PUBxxx msg indicated by pkt_type with identifier 'id'
+ *
+ * @param [in] ctx MQTT context
+ * @param [in] id MQTT packet identifier
+ * @param [in] pkt_type MQTT packet type
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM if a tx buffer is not available
+ * @retval -EIO on network error
*/
static
int mqtt_tx_pub_msgs(struct mqtt_ctx *ctx, uint16_t id,
@@ -421,16 +421,19 @@ exit_connect:
}
/**
- * @brief mqtt_rx_pub_msgs Parses and validates the MQTT PUBxxxx message
- * contained in the rx buffer. It validates against
- * message structure and Packet Identifier.
- * @details For the MQTT PUBREC and PUBREL messages, this
- * function writes the corresponding MQTT PUB msg.
- * @param ctx MQTT context
- * @param rx RX buffer
- * @param type MQTT Packet type
- * @return 0 on success
- * @return -EINVAL on error
+ * Parses and validates the MQTT PUBxxxx message contained in the rx buffer.
+ *
+ *
+ * @details It validates against message structure and Packet Identifier.
+ * For the MQTT PUBREC and PUBREL messages, this function writes the
+ * corresponding MQTT PUB msg.
+ *
+ * @param ctx MQTT context
+ * @param rx RX buffer
+ * @param type MQTT Packet type
+ *
+ * @retval 0 on success
+ * @retval -EINVAL on error
*/
static
int mqtt_rx_pub_msgs(struct mqtt_ctx *ctx, struct net_buf *rx,
@@ -626,14 +629,15 @@ int mqtt_rx_publish(struct mqtt_ctx *ctx, struct net_buf *rx)
}
/**
- * @brief mqtt_linearize_buffer Linearize an IP fragmented buffer
- * @param [in] ctx MQTT context structure
- * @param [in] rx RX IP stack buffer
- * @param [in] min_size Min message size allowed. This allows us
- * to exit if the rx buffer is shorter
- * than the expected msg size
- * @return Data buffer
- * @return NULL on error
+ * Linearizes an IP fragmented buffer
+ *
+ * @param [in] ctx MQTT context structure
+ * @param [in] rx RX IP stack buffer
+ * @param [in] min_size Min message size allowed. This allows us to exit if the
+ * rx buffer is shorter than the expected msg size
+ *
+ * @retval Data buffer
+ * @retval NULL on error
*/
static
struct net_buf *mqtt_linearize_buffer(struct mqtt_ctx *ctx, struct net_buf *rx,
@@ -673,18 +677,19 @@ exit_error:
}
/**
- * @brief mqtt_publisher_parser Calls the appropriate rx routine for the MQTT
- * message contained in rx
- * @details On error, this routine will execute the
- * 'ctx->malformed' callback (if defined)
- * @param ctx MQTT context
- * @param rx RX buffer
- * @return 0 on success
- * @return -EINVAL if an unknown message is received
- * @return -ENOMEM if no data buffer is available
- * @return mqtt_rx_connack, mqtt_rx_puback, mqtt_rx_pubrec,
- * mqtt_rx_pubcomp, and mqtt_rx_pingresp
- * return codes
+ * Calls the appropriate rx routine for the MQTT message contained in rx
+ *
+ * @details On error, this routine will execute the 'ctx->malformed' callback
+ * (if defined)
+ *
+ * @param ctx MQTT context
+ * @param rx RX buffer
+ *
+ * @retval 0 on success
+ * @retval -EINVAL if an unknown message is received
+ * @retval -ENOMEM if no data buffer is available
+ * @retval mqtt_rx_connack, mqtt_rx_puback, mqtt_rx_pubrec, mqtt_rx_pubcomp
+ * and mqtt_rx_pingresp return codes
*/
static
int mqtt_publisher_parser(struct mqtt_ctx *ctx, struct net_buf *rx)
@@ -738,18 +743,19 @@ exit_parser:
/**
- * @brief mqtt_subscriber_parser Calls the appropriate rx routine for the MQTT
- * message contained in rx
- * @details On error, this routine will execute the
- * 'ctx->malformed' callback (if defined)
- * @param ctx MQTT context
- * @param rx RX buffer
- * @return 0 on success
- * @return -EINVAL if an unknown message is received
- * @return -ENOMEM if no data buffer is available
- * @return mqtt_rx_publish, mqtt_rx_pubrel, mqtt_rx_pubrel,
- * mqtt_rx_suback
- * return codes
+ * Calls the appropriate rx routine for the MQTT message contained in rx
+ *
+ * @details On error, this routine will execute the 'ctx->malformed' callback
+ * (if defined)
+ *
+ * @param ctx MQTT context
+ * @param rx RX buffer
+ *
+ * @retval 0 on success
+ * @retval -EINVAL if an unknown message is received
+ * @retval -ENOMEM if no data buffer is available
+ * @retval mqtt_rx_publish, mqtt_rx_pubrel, mqtt_rx_pubrel and mqtt_rx_suback
+ * return codes
*/
static
int mqtt_subscriber_parser(struct mqtt_ctx *ctx, struct net_buf *rx)
diff --git a/subsys/net/lib/mqtt/mqtt_pkt.c b/subsys/net/lib/mqtt/mqtt_pkt.c
index cd3c2b13adc..a04ee8f70ab 100644
--- a/subsys/net/lib/mqtt/mqtt_pkt.c
+++ b/subsys/net/lib/mqtt/mqtt_pkt.c
@@ -50,21 +50,22 @@
QoS_SIZE)
/**
- * @brief mqtt_strlen Enhanced strlen function
- * @details This function is introduced to allow developers to
- * pass null strings to functions that compute the length
- * of strings.
- * strlen returns random values for null arguments, so
- * mqtt_strlen(NULL) is quite useful when optional strings
- * are allowed by mqtt-related functions. For example:
- * username in the MQTT CONNECT message is an optional
- * parameter, so connect(..., username = NULL, ...) will
- * work fine without passing an additional parameter like:
- * connect(.., is_username_present, username, ...) or
- * connect(.., username, username_len, ...).
- * @param str C-string or NULL
- * @return 0 for NULL
- * @return strlen otherwise
+ * Enhanced strlen function
+ *
+ * @details This function is introduced to allow developers to pass null strings
+ * to functions that compute the length of strings. strlen returns random values
+ * for null arguments, so mqtt_strlen(NULL) is quite useful when optional
+ * strings are allowed by mqtt-related functions. For example: username in the
+ * MQTT CONNECT message is an optional parameter, so
+ * connect(..., username = NULL, ...) will work fine without passing an
+ * additional parameter like:
+ * connect(.., is_username_present, username, ...) or
+ * connect(.., username, username_len, ...).
+ *
+ * @param str C-string or NULL
+ *
+ * @retval 0 for NULL
+ * @retval strlen otherwise
*/
static inline
uint16_t mqtt_strlen(const char *str)
@@ -77,14 +78,13 @@ uint16_t mqtt_strlen(const char *str)
}
/**
- * @brief compute_rlen_size Computes the amount of bytes needed to
- * codify the value stored in len
- * @details See MQTT 2.2.3, Table 2.4
- * @param [out] size Amount of bytes required to codify the value
- * stored in len
- * @param [in] len Value to be codified
- * @return 0 on success
- * @return -EINVAL is len is out of range
+ * Computes the amount of bytes needed to codify the value stored in len.
+ *
+ * @param [out] size Amount of bytes required to codify the value stored in len
+ * @param [in] len Value to be codified
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
static
int compute_rlen_size(uint16_t *size, uint32_t len)
@@ -105,11 +105,12 @@ int compute_rlen_size(uint16_t *size, uint32_t len)
}
/**
- * @brief rlen_encode Remaining Length encoding algorithm
- * @details See MQTT 2.2.3 Remaining Length
- * @param [out] buf Buffer where the encoded value will be stored
- * @param [in] len Value to encode
- * @return 0 always
+ * Remaining Length encoding algorithm. See MQTT 2.2.3 Remaining Length
+ *
+ * @param [out] buf Buffer where the encoded value will be stored
+ * @param [in] len Value to encode
+ *
+ * @retval 0 always
*/
static int rlen_encode(uint8_t *buf, int len)
{
@@ -133,15 +134,15 @@ static int rlen_encode(uint8_t *buf, int len)
}
/**
- * @brief rlen_decode Remaining Length decoding algorithm
- * @details See MQTT 2.2.3 Remaining Length
- * @param [out] rlen Remaining Length (decoded)
- * @param [out] rlen_size Number of bytes required to codify rlen's value
- * @param [in] buf Buffer where the codified Remaining Length
- * is codified
- * @param [in] size Buffer size
- * @return 0 on success
- * @return -ENOMEM if size < 4
+ * Remaining Length decoding algorithm. See MQTT 2.2.3 Remaining Length
+ *
+ * @param [out] rlen Remaining Length (decoded)
+ * @param [out] rlen_size Number of bytes required to codify rlen's value
+ * @param [in] buf Buffer where the codified Remaining Length is codified
+ * @param [in] size Buffer size
+ *
+ * @retval 0 on success
+ * @retval -ENOMEM if size < 4
*/
static int rlen_decode(uint16_t *rlen, uint16_t *rlen_size,
uint8_t *buf, uint16_t size)
@@ -184,23 +185,22 @@ int mqtt_pack_connack(uint8_t *buf, uint16_t *length, uint16_t size,
}
/**
- * @brief pack_pkt_id Packs a message that only contains the
- * Packet Identifier as payload.
- * @details Many MQTT messages only codify the packet type,
- * reserved flags and the Packet Identifier as payload,
- * so this function is used by those MQTT messages.
+ * Packs a message that only contains the Packet Identifier as payload.
*
- * The total size of this message is always 4 bytes,
- * with a payload of only 2 bytes to codify the
- * identifier.
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] type MQTT Control Packet type
+ * @details Many MQTT messages only codify the packet type, reserved flags and
+ * the Packet Identifier as payload, so this function is used by those MQTT
+ * messages. The total size of this message is always 4 bytes, with a payload
+ * of only 2 bytes to codify the identifier.
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer's size
+ * @param [in] type MQTT Control Packet type
* @param [in] reserved Control Packet Reserved Flags. See MQTT 2.2.2 Flags
- * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
- * @return 0 on success
- * @return -ENOMEM if size < 4
+ * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -ENOMEM if size < 4
*/
static
int pack_pkt_id(uint8_t *buf, uint16_t *length, uint16_t size,
@@ -415,15 +415,15 @@ int mqtt_pack_connect(uint8_t *buf, uint16_t *length, uint16_t size,
}
/**
- * @brief recover_value_len Recovers the length and sets val to point to
- * the beginning of the value
- * @param [in] buf Buffer where the length and value are stored
- * @param [in] length Buffer's length
- * @param [out] val Pointer to the beginning of the value
- * @param [out] val_len Recovered value's length
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
+ * Recovers the length and sets val to point to the beginning of the value
+ *
+ * @param [in] buf Buffer where the length and value are stored
+ * @param [in] length Buffer's length
+ * @param [out] val Pointer to the beginning of the value
+ * @param [out] val_len Recovered value's length
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
static
int recover_value_len(uint8_t *buf, uint16_t length, uint8_t **val,
@@ -568,17 +568,18 @@ int mqtt_unpack_connect(uint8_t *buf, uint16_t length,
}
/**
- * @brief subscribe_size Computes the packet size for the SUBSCRIBE
- * and UNSUBSCRIBE messages without considering
- * the packet type field size (1 byte)
- * @param rlen_size Remaining length size
- * @param payload_size SUBSCRIBE or UNSUBSCRIBE payload size
- * @param items Number of topics
- * @param topics Array of C-strings containing the topics
- * to subscribe to
- * @param with_qos 0 for UNSUBSCRIBE, != 0 for SUBSCRIBE
- * @return 0 on success
- * @return -EINVAL on error
+ * Computes the packet size for the SUBSCRIBE and UNSUBSCRIBE messages
+ *
+ * This routine does not consider the packet type field size (1 byte)
+ *
+ * @param rlen_size Remaining length size
+ * @param payload_size SUBSCRIBE or UNSUBSCRIBE payload size
+ * @param items Number of topics
+ * @param topics Array of C-strings containing the topics to subscribe to
+ * @param with_qos 0 for UNSUBSCRIBE, != 0 for SUBSCRIBE
+ *
+ * @retval 0 on success
+ * @retval -EINVAL on error
*/
static
int subscribe_size(uint16_t *rlen_size, uint16_t *payload_size, uint8_t items,
@@ -607,19 +608,18 @@ int subscribe_size(uint16_t *rlen_size, uint16_t *payload_size, uint8_t items,
}
/**
- * @brief mqtt_pack_subscribe_unsubscribe
- * @details Packs the SUBSCRIBE and UNSUBSCRIBE messages
- * @param buf Buffer where the message will be stored
- * @param pkt_id Packet Identifier
- * @param items Number of topics
- * @param topics Array of C-strings containing the topics
- * to subscribe to
- * @param qos Array of QoS' values, qos[i] is the QoS of topic[i]
- * @param type MQTT_SUBSCRIBE or MQTT_UNSUBSCRIBE
- * @return 0 on success
- * @return -EINVAL if invalid parameters were passed as arguments
- * @return -ENOMEM if buf has no enough space to store the
- * resultant message
+ * Packs the SUBSCRIBE and UNSUBSCRIBE messages
+ *
+ * @param buf Buffer where the message will be stored
+ * @param pkt_id Packet Identifier
+ * @param items Number of topics
+ * @param topics Array of C-strings containing the topics to subscribe to
+ * @param qos Array of QoS' values, qos[i] is the QoS of topic[i]
+ * @param type MQTT_SUBSCRIBE or MQTT_UNSUBSCRIBE
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
*/
static int mqtt_pack_subscribe_unsubscribe(uint8_t *buf, uint16_t *length,
uint16_t size, uint16_t pkt_id,
@@ -969,19 +969,20 @@ int mqtt_unpack_connack(uint8_t *buf, uint16_t length, uint8_t *session,
}
/**
- * @brief pack_zerolen Packs a zero length message
- * @details This function packs MQTT messages with no
- * payload. No validations are made about the
- * input arguments, besides 'size' that must be
- * at least 2 bytes
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] pkt_type MQTT Control Packet Type. See MQTT 2.2.1
- * @param [in] reserved Reserved bits. See MQTT 2.2
- * @return 0 on success
- * @return -ENOMEM if buf has no enough reserved space
- * to store the resultant message
+ * Packs a zero length message
+ *
+ * @details This function packs MQTT messages with no payload. No validations
+ * are made about the input arguments, besides 'size' that must be at least
+ * 2 bytes
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ * @param [in] pkt_type MQTT Control Packet Type. See MQTT 2.2.1
+ * @param [in] reserved Reserved bits. See MQTT 2.2
+ *
+ * @retval 0 on success
+ * @retval -ENOMEM
*/
static
int pack_zerolen(uint8_t *buf, uint16_t *length, uint16_t size,
@@ -1014,16 +1015,16 @@ int mqtt_pack_disconnect(uint8_t *buf, uint16_t *length, uint16_t size)
}
/**
- * @brief unpack_pktid Unpacks a MQTT message with a Packet Id
- * as payload
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param [out] type MQTT Control Packet type
- * @param [out] reserved Reserved flags
- * @param [out] pkt_id Packet Identifier
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
+ * Unpacks a MQTT message with a Packet Id as payload
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param [out] type MQTT Control Packet type
+ * @param [out] reserved Reserved flags
+ * @param [out] pkt_id Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
static
int unpack_pktid(uint8_t *buf, uint16_t length, enum mqtt_packet *type,
@@ -1045,26 +1046,22 @@ int unpack_pktid(uint8_t *buf, uint16_t length, enum mqtt_packet *type,
}
/**
- * @brief unpack_pktid_validate Unpacks and validates a MQTT message
- * containing a Packet Identifier
- * @details The message codified in buf must contain a
- * 1) packet type, 2) reserved flags and
- * 3) packet identifier.
- * The user must provide the expected packet type
- * and expected reserved flags.
- * See MQTT 2.2.2 Flags.
- * If the message contains different values for
- * type and reserved flags than the ones passed as
- * arguments, the function will return -EINVAL
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param [out] pkt_id Packet Identifier
- * @param [in] expected_type Expected MQTT Control Packet type
- * @param [in] expected_reserv Expected Reserved Flags
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine or if
- * any test failed
+ * Unpacks and validates a MQTT message containing a Packet Identifier
+ *
+ * @details The message codified in buf must contain a 1) packet type,
+ * 2) reserved flags and 3) packet identifier. The user must provide the
+ * expected packet type and expected reserved flags. See MQTT 2.2.2 Flags.
+ * If the message contains different values for type and reserved flags
+ * than the ones passed as arguments, the function will return -EINVAL
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param [out] pkt_id Packet Identifier
+ * @param [in] expected_type Expected MQTT Control Packet type
+ * @param [in] expected_reserv Expected Reserved Flags
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
static
int unpack_pktid_validate(uint8_t *buf, uint16_t length, uint16_t *pkt_id,
@@ -1117,14 +1114,15 @@ int mqtt_unpack_unsuback(uint8_t *buf, uint16_t length, uint16_t *pkt_id)
}
/**
- * @brief unpack_zerolen Unpacks a zero-length MQTT message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param [out] pkt_type MQTT Control Packet type
- * @param [out] reserved Reserved flags
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
+ * Unpacks a zero-length MQTT message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param [out] pkt_type MQTT Control Packet type
+ * @param [out] reserved Reserved flags
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
static
int unpack_zerolen(uint8_t *buf, uint16_t length, enum mqtt_packet *pkt_type,
@@ -1145,14 +1143,15 @@ int unpack_zerolen(uint8_t *buf, uint16_t length, enum mqtt_packet *pkt_type,
}
/**
- * @brief unpack_zerolen_validate Unpacks and validates a zero-len MQTT message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param expected_type Expected MQTT Control Packet type
- * @param expected_reserved Expected Reserved Flags
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
+ * Unpacks and validates a zero-len MQTT message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param expected_type Expected MQTT Control Packet type
+ * @param expected_reserved Expected Reserved Flags
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
static
int unpack_zerolen_validate(uint8_t *buf, uint16_t length,
diff --git a/subsys/net/lib/mqtt/mqtt_pkt.h b/subsys/net/lib/mqtt/mqtt_pkt.h
index db9721a3274..87db2bab137 100644
--- a/subsys/net/lib/mqtt/mqtt_pkt.h
+++ b/subsys/net/lib/mqtt/mqtt_pkt.h
@@ -10,8 +10,8 @@
* @brief MQTT v3.1.1 packet library, see:
* http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
*
- * This file is part of the Zephyr Project
- * http://www.zephyrproject.org
+ * This file is part of the Zephyr Project
+ * http://www.zephyrproject.org
*/
#ifndef _MQTT_PKT_H_
@@ -25,368 +25,383 @@
#define MQTT_PACKET_TYPE(first_byte) (((first_byte) & 0xF0) >> 4)
/**
- * @brief mqtt_pack_connack Packs the MQTT CONNACK message
- * @details See MQTT 3.2 CONNACK - Acknowledge connection
- * request
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] session_present Session Present parameter (0 for clean session)
- * @param [in] ret_code Connect return code. See MQTT 3.2.2.3
- * @return 0 on success
- * @return -ENOMEM if size < 4
+ * Packs the MQTT CONNACK message. See MQTT 3.2 CONNACK - Acknowledge
+ * connection request
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ * @param [in] session_present Session Present parameter (0 for clean session)
+ * @param [in] ret_code Connect return code. See MQTT 3.2.2.3
+ *
+ * @retval 0 on success
+ * @retval -ENOMEM if size < 4
*/
int mqtt_pack_connack(uint8_t *buf, uint16_t *length, uint16_t size,
uint8_t session_present, uint8_t ret_code);
/**
- * @brief mqtt_pack_puback Packs the MQTT PUBACK message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet
- * Identifier
- * @return 0 on success
- * @return -ENOMEM if size < 4
+ * Packs the MQTT PUBACK message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -ENOMEM if size < 4
*/
int mqtt_pack_puback(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id);
/**
- * @brief mqtt_pack_pubrec Packs the MQTT PUBREC message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet
- * Identifier
- * @return 0 on success
- * @return -ENOMEM if size < 4
+ * Packs the MQTT PUBREC message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -ENOMEM if size < 4
*/
int mqtt_pack_pubrec(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id);
/**
- * @brief mqtt_pack_puback Packs the MQTT PUBREL message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet
- * Identifier
- * @return 0 on success
- * @return -ENOMEM if size < 4
+ * Packs the MQTT PUBREL message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -ENOMEM if size < 4
*/
int mqtt_pack_pubrel(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id);
/**
- * @brief mqtt_pack_pubcomp Packs the MQTT PUBCOMP message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet
- * Identifier
- * @return 0 on success
- * @return -ENOMEM if size < 4
+ * Packs the MQTT PUBCOMP message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -ENOMEM if size < 4
*/
int mqtt_pack_pubcomp(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id);
/**
- * @brief mqtt_pack_suback Packs the MQTT SUBACK message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1
- * @param [in] elements Number of elements in the granted_qos array
- * @param [in] granted_qos Array where the QoS values are stored
- * See MQTT 3.9 SUBACK, 3.9.3 Payload
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
- * @return -ENOMEM if buf does not have enough reserved
- * space to store the resultant message
+ * Packs the MQTT SUBACK message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1
+ * @param [in] elements Number of elements in the granted_qos array
+ * @param [in] granted_qos Array where the QoS values are stored
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
*/
int mqtt_pack_suback(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id, uint8_t elements,
enum mqtt_qos granted_qos[]);
/**
- * @brief mqtt_pack_connect Packs the MQTT CONNECT message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] msg MQTT CONNECT msg
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
- * @return -ENOMEM if buf does not have enough reserved
- * space to store the resultant message
+ * Packs the MQTT CONNECT message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ * @param [in] msg MQTT CONNECT msg
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
*/
int mqtt_pack_connect(uint8_t *buf, uint16_t *length, uint16_t size,
struct mqtt_connect_msg *msg);
/**
- * @brief mqtt_unpack_connect Unpacks the MQTT CONNECT message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length MQTT CONNECT message's length
- * @param [out] msg MQTT CONNECT parameters
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
+ * Unpacks the MQTT CONNECT message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length MQTT CONNECT message's length
+ * @param [out] msg MQTT CONNECT parameters
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_connect(uint8_t *buf, uint16_t length,
struct mqtt_connect_msg *msg);
/**
- * @brief mqtt_pack_subscribe Packs the MQTT SUBSCRIBE message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1
- * @param [in] items Number of elements in topics
- * @param [in] topics Array of topics.
- * For example: {"sensors", "lights", "doors"}
- * @param [in] qos Array of QoS values per topic. For example:
- {MQTT_QoS1, MQTT_QoS2, MQTT_QoS0}
- NOTE: qos and topics must have the same
- cardinality (# of items)
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
- * @return -ENOMEM if buf does not have enough reserved
- * space to store the resultant message
+ * Packs the MQTT SUBSCRIBE message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ * @param [in] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1
+ * @param [in] items Number of elements in topics
+ * @param [in] topics Array of topics.
+ * For example: {"sensors", "lights", "doors"}
+ * @param [in] qos Array of QoS values per topic.
+ * For example: {MQTT_QoS1, MQTT_QoS2, MQTT_QoS0}
+ * NOTE: qos and topics must have the same cardinality
+ * (# of items)
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
*/
int mqtt_pack_subscribe(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id, uint8_t items, const char *topics[],
const enum mqtt_qos qos[]);
/**
- * @brief mqtt_pack_unsubscribe Packs the MQTT UNSUBSCRIBE message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1
- * @param [in] items Number of elements in topics
- * @param [in] topics Array of topics.
- * For example: {"sensors", "lights", "doors"}
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
- * @return -ENOMEM if buf does not have enough reserved
- * space to store the resultant message
+ * Packs the MQTT UNSUBSCRIBE message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ * @param [in] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1
+ * @param [in] items Number of elements in topics
+ * @param [in] topics Array of topics.
+ * For example: {"sensors", "lights", "doors"}
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
*/
int mqtt_pack_unsubscribe(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id, uint8_t items, const char *topics[]);
/**
- * @brief mqtt_unpack_subscribe Unpacks the MQTT SUBSCRIBE message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param [out] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1
- * @param [out] items Number of recovered topics
- * @param [in] elements Max number of topics to recover from buf
- * @param [out] topics Array of topics. Each element in this array
- * points to the beginning of a topic in buf
- * @param [out] topic_len Array of topics' length. Each element in this
- * array contains the length of the
- * @param [out] qos Array of QoS,
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
+ * Unpacks the MQTT SUBSCRIBE message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param [out] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1
+ * @param [out] items Number of recovered topics
+ * @param [in] elements Max number of topics to recover from buf
+ * @param [out] topics Array of topics. Each element in this array points to
+ * the beginning of a topic in buf
+ * @param [out] topic_len Array containing the length of each topic in topics
+ * @param [out] qos Array of QoS values
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_subscribe(uint8_t *buf, uint16_t length, uint16_t *pkt_id,
uint8_t *items, uint8_t elements, char *topics[],
uint16_t topic_len[], enum mqtt_qos qos[]);
/**
- * @brief mqtt_unpack_suback Unpacks the MQTT SUBACK message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param [out] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1
- * @param [out] items Number of recovered topics
- * @param [in] elements Max number of topics to recover from buf
- * @param [out] granted_qos Granted QoS values per topic. See MQTT 3.9
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
+ * Unpacks the MQTT SUBACK message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param [out] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1
+ * @param [out] items Number of recovered topics
+ * @param [in] elements Max number of topics to recover from buf
+ * @param [out] granted_qos Granted QoS values per topic. See MQTT 3.9
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_suback(uint8_t *buf, uint16_t length, uint16_t *pkt_id,
uint8_t *items, uint8_t elements,
enum mqtt_qos granted_qos[]);
/**
- * @brief mqtt_pack_publish Packs the MQTT PUBLISH message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] msg MQTT PUBLISH message
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
- * @return -ENOMEM if buf does not have enough reserved
- * space to store the resultant message
+ * Packs the MQTT PUBLISH message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ * @param [in] msg MQTT PUBLISH message
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
+ * @retval -ENOMEM
*/
int mqtt_pack_publish(uint8_t *buf, uint16_t *length, uint16_t size,
struct mqtt_publish_msg *msg);
/**
- * @brief mqtt_unpack_publish Unpacks the MQTT PUBLISH message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param [out] msg MQTT PUBLISH message
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
+ * Unpacks the MQTT PUBLISH message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param [out] msg MQTT PUBLISH message
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_publish(uint8_t *buf, uint16_t length,
struct mqtt_publish_msg *msg);
/**
- * @brief mqtt_unpack_connack Unpacks the MQTT CONNACK message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param [out] session Session Present. See MQTT 3.2.2.2
- * @param [out] connect_rc CONNECT return code. See MQTT 3.2.2.3
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
+ * Unpacks the MQTT CONNACK message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param [out] session Session Present. See MQTT 3.2.2.2
+ * @param [out] connect_rc CONNECT return code. See MQTT 3.2.2.3
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_connack(uint8_t *buf, uint16_t length, uint8_t *session,
uint8_t *connect_rc);
/**
- * @brief mqtt_pack_pingreq Packs the MQTT PINGREQ message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @return 0 on success
- * @return -ENOMEM if buf does not have enough reserved
- * space to store the resultant message
+ * Packs the MQTT PINGREQ message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ *
+ * @retval 0 on success
+ * @retval -ENOMEM
*/
int mqtt_pack_pingreq(uint8_t *buf, uint16_t *length, uint16_t size);
/**
- * @brief mqtt_pack_pingresp Packs the MQTT PINGRESP message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @return 0 on success
- * @return -ENOMEM if buf does not have enough reserved
- * space to store the resultant message
+ * Packs the MQTT PINGRESP message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ *
+ * @retval 0 on success
+ * @retval -ENOMEM
*/
int mqtt_pack_pingresp(uint8_t *buf, uint16_t *length, uint16_t size);
/**
- * @brief mqtt_pack_disconnect Packs the MQTT DISCONNECT message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @return 0 on success
- * @return -ENOMEM if buf does not have enough reserved
- * space to store the resultant message
+ * Packs the MQTT DISCONNECT message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ *
+ * @retval 0 on success
+ * @retval -ENOMEM
*/
int mqtt_pack_disconnect(uint8_t *buf, uint16_t *length, uint16_t size);
/**
- * @brief mqtt_pack_unsuback Packs the MQTT UNSUBACK message
- * @param [out] buf Buffer where the resultant message is stored
- * @param [out] length Number of bytes required to codify the message
- * @param [in] size Buffer's size
- * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet
- * Identifier
- * @return 0 on success
- * @return -ENOMEM if size < 4
+ * Packs the MQTT UNSUBACK message
+ *
+ * @param [out] buf Buffer where the resultant message is stored
+ * @param [out] length Number of bytes required to codify the message
+ * @param [in] size Buffer size
+ * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -ENOMEM if size < 4
*/
int mqtt_pack_unsuback(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id);
/**
- * @brief mqtt_unpack_puback Unpacks the MQTT PUBACK message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param [out] pkt_id Packet Identifier
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine or if
- * buf does not contain the desired msg
+ * Unpacks the MQTT PUBACK message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param [out] pkt_id Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_puback(uint8_t *buf, uint16_t length, uint16_t *pkt_id);
/**
- * @brief mqtt_unpack_pubrec Unpacks the MQTT PUBREC message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param [out] pkt_id Packet Identifier
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine or if
- * buf does not contain the desired msg
+ * Unpacks the MQTT PUBREC message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param [out] pkt_id Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_pubrec(uint8_t *buf, uint16_t length, uint16_t *pkt_id);
/**
- * @brief mqtt_unpack_pubrel Unpacks the MQTT PUBREL message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param [out] pkt_id Packet Identifier
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine or if
- * buf does not contain the desired msg
+ * Unpacks the MQTT PUBREL message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param [out] pkt_id Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_pubrel(uint8_t *buf, uint16_t length, uint16_t *pkt_id);
/**
- * @brief mqtt_unpack_pubcomp Unpacks the MQTT PUBCOMP message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param [out] pkt_id Packet Identifier
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine or if
- * buf does not contain the desired msg
+ * Unpacks the MQTT PUBCOMP message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param [out] pkt_id Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_pubcomp(uint8_t *buf, uint16_t length, uint16_t *pkt_id);
/**
- * @brief mqtt_unpack_unsuback Unpacks the MQTT UNSUBACK message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @param [out] pkt_id Packet Identifier
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine or if
- * buf does not contain the desired msg
+ * Unpacks the MQTT UNSUBACK message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ * @param [out] pkt_id Packet Identifier
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_unsuback(uint8_t *buf, uint16_t length, uint16_t *pkt_id);
/**
- * @brief mqtt_unpack_pingreq Unpacks the MQTT PINGREQ message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
+ * Unpacks the MQTT PINGREQ message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_pingreq(uint8_t *buf, uint16_t length);
/**
- * @brief mqtt_unpack_pingresp Unpacks the MQTT PINGRESP message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
+ * Unpacks the MQTT PINGRESP message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_pingresp(uint8_t *buf, uint16_t length);
/**
- * @brief mqtt_unpack_disconnect Unpacks the MQTT DISCONNECT message
- * @param [in] buf Buffer where the message is stored
- * @param [in] length Message's length
- * @return 0 on success
- * @return -EINVAL if an invalid parameter was passed
- * as an argument to this routine
+ * Unpacks the MQTT DISCONNECT message
+ *
+ * @param [in] buf Buffer where the message is stored
+ * @param [in] length Message's length
+ *
+ * @retval 0 on success
+ * @retval -EINVAL
*/
int mqtt_unpack_disconnect(uint8_t *buf, uint16_t length);