michaelh/zephyr
1
0
Fork 0
Code Releases Activity

net/mqtt: Fix inline doc for MQTT

Browse source 
Fix inline documentation for the MQTT API.

Jira: ZEP-1669

Change-Id: I90702eae236a9189b58e0f2fb2a6c5a3eeaf959c
Signed-off-by: Flavio Santes <flavio.santes@intel.com>
This commit is contained in:
Flavio Santes 2017-02-08 15:02:58 -06:00 • committed by Jukka Rissanen
commit bed71d0a02
4 changed files with 659 additions and 623 deletions
Download patch file Download diff file Expand all files Collapse all files

390
include/net/mqtt.h
View file

@ -17,7 +17,7 @@
*/ */
/** /**
* @brief mqtt_app MQTT application type * MQTT application type
*/ */
enum mqtt_app { enum mqtt_app {
/** Publisher and Subscriber application */ /** Publisher and Subscriber application */
@ -31,9 +31,9 @@ enum mqtt_app {
}; };
/** /**
* @brief struct mqtt_ctx MQTT context structure * MQTT context structure
* @details *
* Context structure for the MQTT high-level API with support for QoS. * @details Context structure for the MQTT high-level API with support for QoS.
* *
* This API is designed for asynchronous operation, so callbacks are * This API is designed for asynchronous operation, so callbacks are
* executed when some events must be addressed outside the MQTT routines. * 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 /** Callback executed when a #MQTT_APP_PUBLISHER application receives
* a MQTT PUBxxxx msg. * 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.
* *
* <b>Note: this callback must be not NULL</b> * <b>Note: this callback must be not NULL</b>
* *
* @param [in] ctx MQTT context * @param [in] ctx MQTT context
* @param [in] pkt_id Packet Identifier for the input MQTT msg * @param [in] pkt_id Packet Identifier for the input MQTT msg
* @param [in] type Packet type * @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 <b>Note: the application must discard all the
* messages already processed</b>
*
* @return Any other value will stop the QoS handshake
* and the caller will return -EINVAL
*/ */
int (*publish_tx)(struct mqtt_ctx *ctx, uint16_t pkt_id, int (*publish_tx)(struct mqtt_ctx *ctx, uint16_t pkt_id,
enum mqtt_packet type); enum mqtt_packet type);
/** Callback executed when a MQTT_APP_SUBSCRIBER, /** Callback executed when a MQTT_APP_SUBSCRIBER,
* MQTT_APP_PUBLISHER_SUBSCRIBER or MQTT_APP_SERVER application receive * MQTT_APP_PUBLISHER_SUBSCRIBER or MQTT_APP_SERVER applications receive
* a MQTT PUBxxxx msg. * 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
* *
* <b>Note: this callback must be not NULL</b> * <b>Note: this callback must be not NULL</b>
* *
* @param [in] ctx MQTT context * @param [in] ctx MQTT context
* @param [in] msg Publish message, this parameter is only used * @param [in] msg Publish message, this parameter is only used
* when the type is MQTT_PUBLISH * when the type is MQTT_PUBLISH
* @param [in] pkt_id Packet Identifier for the input msg * @param [in] pkt_id Packet Identifier for the input msg
* @param [in] type Packet type * @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 <b>Note: the application must discard all the
* messages already processed</b>
*
* @return Any other value will stop the QoS handshake
* and the caller will return -EINVAL
*/ */
int (*publish_rx)(struct mqtt_ctx *ctx, struct mqtt_publish_msg *msg, int (*publish_rx)(struct mqtt_ctx *ctx, struct mqtt_publish_msg *msg,
uint16_t pkt_id, enum mqtt_packet type); uint16_t pkt_id, enum mqtt_packet type);
/** Callback executed when a MQTT_APP_SUBSCRIBER or /** Callback executed when a MQTT_APP_SUBSCRIBER or
* MQTT_APP_PUBLISHER_SUBSCRIBER receives the MQTT SUBACK message * 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.
* *
* <b>Note: this callback must be not NULL</b> * <b>Note: this callback must be not NULL</b>
* *
* @param [in] ctx MQTT context * @param [in] ctx MQTT context
* @param [in] pkt_id Packet Identifier for the MQTT SUBACK msg * @param [in] pkt_id Packet Identifier for the MQTT SUBACK msg
* @param [in] items Number of elements in the qos array * @param [in] items Number of elements in the qos array
* @param [in] qos Array of QoS values * @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
*/ */
int (*subscribe)(struct mqtt_ctx *ctx, uint16_t pkt_id, int (*subscribe)(struct mqtt_ctx *ctx, uint16_t pkt_id,
uint8_t items, enum mqtt_qos qos[]); uint8_t items, enum mqtt_qos qos[]);
/** Callback executed when a MQTT_APP_SUBSCRIBER or /** Callback executed when a MQTT_APP_SUBSCRIBER or
* MQTT_APP_PUBLISHER_SUBSCRIBER receives the MQTT UNSUBACK message * 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
* *
* <b>Note: this callback must be not NULL</b> * <b>Note: this callback must be not NULL</b>
* *
* @param [in] ctx MQTT context * @param [in] ctx MQTT context
* @param [in] pkt_id Packet Identifier for the MQTT SUBACK msg * @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); 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 * Initializes the MQTT context structure
* @param ctx MQTT context structure *
* @param app_type See enum mqtt_app * @param ctx MQTT context structure
* @return 0, always. * @param app_type See enum mqtt_app
* @retval 0, always.
*/ */
int mqtt_init(struct mqtt_ctx *ctx, enum mqtt_app app_type); int mqtt_init(struct mqtt_ctx *ctx, enum mqtt_app app_type);
/** /**
* @brief mqtt_tx_connect Sends the MQTT CONNECT message * Sends the MQTT CONNECT message
* @param [in] ctx MQTT context structure *
* @param [in] msg MQTT CONNECT msg * @param [in] ctx MQTT context structure
* @return 0 on success * @param [in] msg MQTT CONNECT msg
* @return -EIO on network error *
* @return -ENOMEM if no data/tx buffer is available * @retval 0 on success
* @return -EINVAL if invalid data was passed to this * @retval -EIO
* routine * @retval -ENOMEM
* @retval -EINVAL
*/ */
int mqtt_tx_connect(struct mqtt_ctx *ctx, struct mqtt_connect_msg *msg); int mqtt_tx_connect(struct mqtt_ctx *ctx, struct mqtt_connect_msg *msg);
/** /**
* @brief mqtt_tx_disconnect Send the MQTT DISCONNECT message * Send the MQTT DISCONNECT message
* @param [in] ctx MQTT context structure *
* @return 0 on success * @param [in] ctx MQTT context structure
* @return -EIO on network error *
* @return -ENOMEM if no data/tx buffer is available * @retval 0 on success
* @return -EINVAL if invalid data was passed to this * @retval -EIO
* routine * @retval -ENOMEM
* @retval -EINVAL
*/ */
int mqtt_tx_disconnect(struct mqtt_ctx *ctx); int mqtt_tx_disconnect(struct mqtt_ctx *ctx);
/** /**
* @brief mqtt_tx_puback Sends the MQTT PUBACK message with the given * Sends the MQTT PUBACK message with the given packet id
* packet id *
* @param [in] ctx MQTT context structure * @param [in] ctx MQTT context structure
* @param [in] id MQTT Packet Identifier * @param [in] id MQTT Packet Identifier
* @return 0 on success *
* @return -EINVAL if an invalid parameter was passed to * @retval 0 on success
* this routine * @retval -EINVAL
* @return -ENOMEM if a tx buffer is not available * @retval -ENOMEM
* @return -EIO on network error * @retval -EIO
*/ */
int mqtt_tx_puback(struct mqtt_ctx *ctx, uint16_t id); int mqtt_tx_puback(struct mqtt_ctx *ctx, uint16_t id);
/** /**
* @brief mqtt_tx_pubcomp Sends the MQTT PUBCOMP message with the given * Sends the MQTT PUBCOMP message with the given packet id
* packet id *
* @param [in] ctx MQTT context structure * @param [in] ctx MQTT context structure
* @param [in] id MQTT Packet Identifier * @param [in] id MQTT Packet Identifier
* @return 0 on success *
* @return -EINVAL if an invalid parameter was passed to * @retval 0 on success
* this routine * @retval -EINVAL
* @return -ENOMEM if a tx buffer is not available * @retval -ENOMEM
* @return -EIO on network error * @retval -EIO
*/ */
int mqtt_tx_pubcomp(struct mqtt_ctx *ctx, uint16_t id); int mqtt_tx_pubcomp(struct mqtt_ctx *ctx, uint16_t id);
/** /**
* @brief mqtt_tx_pubrec Sends the MQTT PUBREC message with the given * Sends the MQTT PUBREC message with the given packet id
* packet id *
* @param [in] ctx MQTT context structure * @param [in] ctx MQTT context structure
* @param [in] id MQTT Packet Identifier * @param [in] id MQTT Packet Identifier
* @return 0 on success * @retval 0 on success
* @return -EINVAL if an invalid parameter was passed to * @retval -EINVAL
* this routine * @retval -ENOMEM
* @return -ENOMEM if a tx buffer is not available * @retval -EIO
* @return -EIO on network error
*/ */
int mqtt_tx_pubrec(struct mqtt_ctx *ctx, uint16_t id); int mqtt_tx_pubrec(struct mqtt_ctx *ctx, uint16_t id);
/** /**
* @brief mqtt_tx_pubrel Sends the MQTT PUBREL message with the given * Sends the MQTT PUBREL message with the given packet id
* packet id *
* @param [in] ctx MQTT context structure * @param [in] ctx MQTT context structure
* @param [in] id MQTT Packet Identifier * @param [in] id MQTT Packet Identifier
* @return 0 on success *
* @return -EINVAL if an invalid parameter was passed to * @retval 0 on success
* this routine * @retval -EINVAL
* @return -ENOMEM if a tx buffer is not available * @retval -ENOMEM
* @return -EIO on network error * @retval -EIO
*/ */
int mqtt_tx_pubrel(struct mqtt_ctx *ctx, uint16_t id); int mqtt_tx_pubrel(struct mqtt_ctx *ctx, uint16_t id);
/** /**
* @brief mqtt_tx_publish Sends the MQTT PUBLISH message * Sends the MQTT PUBLISH message
* @param [in] ctx MQTT context structure *
* @param [in] msg MQTT PUBLISH msg * @param [in] ctx MQTT context structure
* @return 0 on success * @param [in] msg MQTT PUBLISH msg
* @return -EINVAL if an invalid parameter was passed to *
* this routine * @retval 0 on success
* @return -ENOMEM if a tx buffer is not available * @retval -EINVAL
* @return -EIO on network error * @retval -ENOMEM
* @retval -EIO
*/ */
int mqtt_tx_publish(struct mqtt_ctx *ctx, struct mqtt_publish_msg *msg); int mqtt_tx_publish(struct mqtt_ctx *ctx, struct mqtt_publish_msg *msg);
/** /**
* @brief mqtt_tx_pingreq Sends the MQTT PINGREQ message * Sends the MQTT PINGREQ message
* @param [in] ctx MQTT context structure *
* @return 0 on success * @param [in] ctx MQTT context structure
* @return -EINVAL if an invalid parameter was passed to *
* this routine * @retval 0 on success
* @return -ENOMEM if a tx buffer is not available * @retval -EINVAL
* @return -EIO on network error * @retval -ENOMEM
* @retval -EIO
*/ */
int mqtt_tx_pingreq(struct mqtt_ctx *ctx); int mqtt_tx_pingreq(struct mqtt_ctx *ctx);
/** /**
* @brief mqtt_tx_subscribe Sends the MQTT SUBSCRIBE message * Sends the MQTT SUBSCRIBE message
* @param [in] ctx MQTT context structure *
* @param [in] pkt_id Packet identifier for the MQTT SUBSCRIBE msg * @param [in] ctx MQTT context structure
* @param [in] items Number of elements in 'topics' and 'qos' arrays * @param [in] pkt_id Packet identifier for the MQTT SUBSCRIBE msg
* @param [in] topics Array of 'items' elements containing C strings. * @param [in] items Number of elements in 'topics' and 'qos' arrays
* For example: {"sensors", "lights", "doors"} * @param [in] topics Array of 'items' elements containing C strings.
* @param [in] qos Array of 'items' elements containing MQTT QoS * For example: {"sensors", "lights", "doors"}
* values: MQTT_QoS0, MQTT_QoS1, MQTT_QoS2. For * @param [in] qos Array of 'items' elements containing MQTT QoS values:
* example for the 'topics' array above the * MQTT_QoS0, MQTT_QoS1, MQTT_QoS2. For example for the 'topics'
* following QoS may be used: * array above the following QoS may be used: {MQTT_QoS0,
* {MQTT_QoS0, MQTT_QoS2, MQTT_QoS1}, indicating * MQTT_QoS2, MQTT_QoS1}, indicating that the subscription to
* that the subscription to 'lights' must be done * 'lights' must be done with MQTT_QoS2
* with MQTT_QoS2 *
* @return 0 on success * @retval 0 on success
* @return -EINVAL if an invalid parameter was passed to * @retval -EINVAL
* this routine * @retval -ENOMEM
* @return -ENOMEM if a tx buffer is not available * @retval -EIO
* @return -EIO on network error
*/ */
int mqtt_tx_subscribe(struct mqtt_ctx *ctx, uint16_t pkt_id, uint8_t items, int mqtt_tx_subscribe(struct mqtt_ctx *ctx, uint16_t pkt_id, uint8_t items,
const char *topics[], const enum mqtt_qos qos[]); const char *topics[], const enum mqtt_qos qos[]);
/** /**
* @brief mqtt_tx_unsubscribe Sends the MQTT UNSUBSCRIBE message * Sends the MQTT UNSUBSCRIBE message
* @param [in] ctx MQTT context structure *
* @param [in] pkt_id Packet identifier for the MQTT UNSUBSCRIBE msg * @param [in] ctx MQTT context structure
* @param [in] items Number of elements in the 'topics' array * @param [in] pkt_id Packet identifier for the MQTT UNSUBSCRIBE msg
* @param [in] topics Array of 'items' elements containing C strings * @param [in] items Number of elements in the 'topics' array
* @return * @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, int mqtt_tx_unsubscribe(struct mqtt_ctx *ctx, uint16_t pkt_id, uint8_t items,
const char *topics[]); 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 mqtt_rx_connack(struct mqtt_ctx *ctx, struct net_buf *rx,
int clean_session); int clean_session);
/** /**
* @brief mqtt_rx_puback Parses and validates the MQTT PUBACK message * Parses and validates the MQTT PUBACK message
* @param [in] ctx MQTT context structure *
* @param [in] rx Data buffer * @param [in] ctx MQTT context structure
* @return 0 on success * @param [in] rx Data buffer
* @return -EINVAL on error *
* @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_rx_puback(struct mqtt_ctx *ctx, struct net_buf *rx); int mqtt_rx_puback(struct mqtt_ctx *ctx, struct net_buf *rx);
/** /**
* @brief mqtt_rx_pubcomp Parses and validates the MQTT PUBCOMP message * Parses and validates the MQTT PUBCOMP message
* @param [in] ctx MQTT context structure *
* @param [in] rx Data buffer * @param [in] ctx MQTT context structure
* @return 0 on success * @param [in] rx Data buffer
* @return -EINVAL on error *
* @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_rx_pubcomp(struct mqtt_ctx *ctx, struct net_buf *rx); int mqtt_rx_pubcomp(struct mqtt_ctx *ctx, struct net_buf *rx);
/** /**
* @brief mqtt_rx_pubrec Parses and validates the MQTT PUBREC message * Parses and validates the MQTT PUBREC message
* @param [in] ctx MQTT context structure *
* @param [in] rx Data buffer * @param [in] ctx MQTT context structure
* @return 0 on success * @param [in] rx Data buffer
* @return -EINVAL on error *
* @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_rx_pubrec(struct mqtt_ctx *ctx, struct net_buf *rx); int mqtt_rx_pubrec(struct mqtt_ctx *ctx, struct net_buf *rx);
/** /**
* @brief mqtt_rx_pubrel Parses and validates the MQTT PUBREL message * 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] ctx MQTT context structure
* @param [in] rx Data buffer * @param [in] rx Data buffer
* @return 0 on success *
* @return -EINVAL on error * @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_rx_pubrel(struct mqtt_ctx *ctx, struct net_buf *rx); int mqtt_rx_pubrel(struct mqtt_ctx *ctx, struct net_buf *rx);
/** /**
* @brief mqtt_rx_pingresp Parses the MQTT PINGRESP message * Parses the MQTT PINGRESP message
* @param [in] ctx MQTT context structure *
* @param [in] rx Data buffer * @param [in] ctx MQTT context structure
* @return 0 on success * @param [in] rx Data buffer
* @return -EINVAL on error *
* @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_rx_pingresp(struct mqtt_ctx *ctx, struct net_buf *rx); int mqtt_rx_pingresp(struct mqtt_ctx *ctx, struct net_buf *rx);
/** /**
* @brief mqtt_rx_suback Parses the MQTT SUBACK message * Parses the MQTT SUBACK message
* @param [in] ctx MQTT context structure *
* @param [in] rx Data buffer * @param [in] ctx MQTT context structure
* @return 0 on success * @param [in] rx Data buffer
* @return -EINVAL on error *
* @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_rx_suback(struct mqtt_ctx *ctx, struct net_buf *rx); int mqtt_rx_suback(struct mqtt_ctx *ctx, struct net_buf *rx);
/** /**
* @brief mqtt_rx_unsuback Parses the MQTT UNSUBACK message * Parses the MQTT UNSUBACK message
* @param [in] ctx MQTT context structure *
* @param [in] rx Data buffer * @param [in] ctx MQTT context structure
* @return 0 on success * @param [in] rx Data buffer
* @return -EINVAL on error *
* @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_rx_unsuback(struct mqtt_ctx *ctx, struct net_buf *rx); int mqtt_rx_unsuback(struct mqtt_ctx *ctx, struct net_buf *rx);
/** /**
* @brief mqtt_rx_publish Parses the MQTT PUBLISH message * Parses the MQTT PUBLISH message
* @param [in] ctx MQTT context structure *
* @param [in] rx Data buffer * @param [in] ctx MQTT context structure
* @return 0 on success * @param [in] rx Data buffer
* @return -EINVAL on error *
* @return -ENOMEM if no data buffer is available * @retval 0 on success
* @retval -EINVAL
* @retval -ENOMEM
*/ */
int mqtt_rx_publish(struct mqtt_ctx *ctx, struct net_buf *rx); int mqtt_rx_publish(struct mqtt_ctx *ctx, struct net_buf *rx);

110
subsys/net/lib/mqtt/mqtt.c
View file

@ -113,16 +113,16 @@ exit_disconnect:
} }
/** /**
* @brief mqtt_tx_pub_msgs Writes the MQTT PUBxxx msg indicated by pkt_type * Writes the MQTT PUBxxx msg indicated by pkt_type with identifier 'id'
* with identifier 'id' *
* @param [in] ctx MQTT context * @param [in] ctx MQTT context
* @param [in] id MQTT packet identifier * @param [in] id MQTT packet identifier
* @param [in] pkt_type MQTT packet type * @param [in] pkt_type MQTT packet type
* @return 0 on success *
* @return -EINVAL if an invalid parameter was passed to * @retval 0 on success
* this routine * @retval -EINVAL
* @return -ENOMEM if a tx buffer is not available * @retval -ENOMEM if a tx buffer is not available
* @return -EIO on network error * @retval -EIO on network error
*/ */
static static
int mqtt_tx_pub_msgs(struct mqtt_ctx *ctx, uint16_t id, 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 * Parses and validates the MQTT PUBxxxx message contained in the rx buffer.
* contained in the rx buffer. It validates against *
* message structure and Packet Identifier. *
* @details For the MQTT PUBREC and PUBREL messages, this * @details It validates against message structure and Packet Identifier.
* function writes the corresponding MQTT PUB msg. * For the MQTT PUBREC and PUBREL messages, this function writes the
* @param ctx MQTT context * corresponding MQTT PUB msg.
* @param rx RX buffer *
* @param type MQTT Packet type * @param ctx MQTT context
* @return 0 on success * @param rx RX buffer
* @return -EINVAL on error * @param type MQTT Packet type
*
* @retval 0 on success
* @retval -EINVAL on error
*/ */
static static
int mqtt_rx_pub_msgs(struct mqtt_ctx *ctx, struct net_buf *rx, 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 * Linearizes an IP fragmented buffer
* @param [in] ctx MQTT context structure *
* @param [in] rx RX IP stack buffer * @param [in] ctx MQTT context structure
* @param [in] min_size Min message size allowed. This allows us * @param [in] rx RX IP stack buffer
* to exit if the rx buffer is shorter * @param [in] min_size Min message size allowed. This allows us to exit if the
* than the expected msg size * rx buffer is shorter than the expected msg size
* @return Data buffer *
* @return NULL on error * @retval Data buffer
* @retval NULL on error
*/ */
static static
struct net_buf *mqtt_linearize_buffer(struct mqtt_ctx *ctx, struct net_buf *rx, 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 * Calls the appropriate rx routine for the MQTT message contained in rx
* message contained in rx *
* @details On error, this routine will execute the * @details On error, this routine will execute the 'ctx->malformed' callback
* 'ctx->malformed' callback (if defined) * (if defined)
* @param ctx MQTT context *
* @param rx RX buffer * @param ctx MQTT context
* @return 0 on success * @param rx RX buffer
* @return -EINVAL if an unknown message is received *
* @return -ENOMEM if no data buffer is available * @retval 0 on success
* @return mqtt_rx_connack, mqtt_rx_puback, mqtt_rx_pubrec, * @retval -EINVAL if an unknown message is received
* mqtt_rx_pubcomp, and mqtt_rx_pingresp * @retval -ENOMEM if no data buffer is available
* return codes * @retval mqtt_rx_connack, mqtt_rx_puback, mqtt_rx_pubrec, mqtt_rx_pubcomp
* and mqtt_rx_pingresp return codes
*/ */
static static
int mqtt_publisher_parser(struct mqtt_ctx *ctx, struct net_buf *rx) 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 * Calls the appropriate rx routine for the MQTT message contained in rx
* message contained in rx *
* @details On error, this routine will execute the * @details On error, this routine will execute the 'ctx->malformed' callback
* 'ctx->malformed' callback (if defined) * (if defined)
* @param ctx MQTT context *
* @param rx RX buffer * @param ctx MQTT context
* @return 0 on success * @param rx RX buffer
* @return -EINVAL if an unknown message is received *
* @return -ENOMEM if no data buffer is available * @retval 0 on success
* @return mqtt_rx_publish, mqtt_rx_pubrel, mqtt_rx_pubrel, * @retval -EINVAL if an unknown message is received
* mqtt_rx_suback * @retval -ENOMEM if no data buffer is available
* return codes * @retval mqtt_rx_publish, mqtt_rx_pubrel, mqtt_rx_pubrel and mqtt_rx_suback
* return codes
*/ */
static static
int mqtt_subscriber_parser(struct mqtt_ctx *ctx, struct net_buf *rx) int mqtt_subscriber_parser(struct mqtt_ctx *ctx, struct net_buf *rx)

287
subsys/net/lib/mqtt/mqtt_pkt.c
View file

@ -50,21 +50,22 @@
QoS_SIZE) QoS_SIZE)
/** /**
* @brief mqtt_strlen Enhanced strlen function * Enhanced strlen function
* @details This function is introduced to allow developers to *
* pass null strings to functions that compute the length * @details This function is introduced to allow developers to pass null strings
* of strings. * to functions that compute the length of strings. strlen returns random values
* strlen returns random values for null arguments, so * for null arguments, so mqtt_strlen(NULL) is quite useful when optional
* mqtt_strlen(NULL) is quite useful when optional strings * strings are allowed by mqtt-related functions. For example: username in the
* are allowed by mqtt-related functions. For example: * MQTT CONNECT message is an optional parameter, so
* username in the MQTT CONNECT message is an optional * connect(..., username = NULL, ...) will work fine without passing an
* parameter, so connect(..., username = NULL, ...) will * additional parameter like:
* work fine without passing an additional parameter like: * connect(.., is_username_present, username, ...) or
* connect(.., is_username_present, username, ...) or * connect(.., username, username_len, ...).
* connect(.., username, username_len, ...). *
* @param str C-string or NULL * @param str C-string or NULL
* @return 0 for NULL *
* @return strlen otherwise * @retval 0 for NULL
* @retval strlen otherwise
*/ */
static inline static inline
uint16_t mqtt_strlen(const char *str) 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 * Computes the amount of bytes needed to codify the value stored in len.
* 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 [out] size Amount of bytes required to codify the value * @param [in] len Value to be codified
* stored in len *
* @param [in] len Value to be codified * @retval 0 on success
* @return 0 on success * @retval -EINVAL
* @return -EINVAL is len is out of range
*/ */
static static
int compute_rlen_size(uint16_t *size, uint32_t len) 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 * Remaining Length encoding algorithm. See MQTT 2.2.3 Remaining Length
* @details See MQTT 2.2.3 Remaining Length *
* @param [out] buf Buffer where the encoded value will be stored * @param [out] buf Buffer where the encoded value will be stored
* @param [in] len Value to encode * @param [in] len Value to encode
* @return 0 always *
* @retval 0 always
*/ */
static int rlen_encode(uint8_t *buf, int len) 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 * Remaining Length decoding algorithm. See MQTT 2.2.3 Remaining Length
* @details See MQTT 2.2.3 Remaining Length *
* @param [out] rlen Remaining Length (decoded) * @param [out] rlen Remaining Length (decoded)
* @param [out] rlen_size Number of bytes required to codify rlen's value * @param [out] rlen_size Number of bytes required to codify rlen's value
* @param [in] buf Buffer where the codified Remaining Length * @param [in] buf Buffer where the codified Remaining Length is codified
* is codified * @param [in] size Buffer size
* @param [in] size Buffer size *
* @return 0 on success * @retval 0 on success
* @return -ENOMEM if size < 4 * @retval -ENOMEM if size < 4
*/ */
static int rlen_decode(uint16_t *rlen, uint16_t *rlen_size, static int rlen_decode(uint16_t *rlen, uint16_t *rlen_size,
uint8_t *buf, uint16_t 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 * Packs a message that only contains the Packet Identifier as payload.
* 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.
* *
* The total size of this message is always 4 bytes, * @details Many MQTT messages only codify the packet type, reserved flags and
* with a payload of only 2 bytes to codify the * the Packet Identifier as payload, so this function is used by those MQTT
* identifier. * messages. The total size of this message is always 4 bytes, with a payload
* @param [out] buf Buffer where the resultant message is stored * of only 2 bytes to codify the identifier.
* @param [out] length Number of bytes required to codify the message *
* @param [in] size Buffer's size * @param [out] buf Buffer where the resultant message is stored
* @param [in] type MQTT Control Packet type * @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] reserved Control Packet Reserved Flags. See MQTT 2.2.2 Flags
* @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
* @return 0 on success *
* @return -ENOMEM if size < 4 * @retval 0 on success
* @retval -ENOMEM if size < 4
*/ */
static static
int pack_pkt_id(uint8_t *buf, uint16_t *length, uint16_t size, 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 * Recovers the length and sets val to point to the beginning of the value
* the beginning of the value *
* @param [in] buf Buffer where the length and value are stored * @param [in] buf Buffer where the length and value are stored
* @param [in] length Buffer's length * @param [in] length Buffer's length
* @param [out] val Pointer to the beginning of the value * @param [out] val Pointer to the beginning of the value
* @param [out] val_len Recovered value's length * @param [out] val_len Recovered value's length
* @return 0 on success *
* @return -EINVAL if an invalid parameter was passed * @retval 0 on success
* as an argument to this routine * @retval -EINVAL
*/ */
static static
int recover_value_len(uint8_t *buf, uint16_t length, uint8_t **val, 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 * Computes the packet size for the SUBSCRIBE and UNSUBSCRIBE messages
* and UNSUBSCRIBE messages without considering *
* the packet type field size (1 byte) * 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 rlen_size Remaining length size
* @param items Number of topics * @param payload_size SUBSCRIBE or UNSUBSCRIBE payload size
* @param topics Array of C-strings containing the topics * @param items Number of topics
* to subscribe to * @param topics Array of C-strings containing the topics to subscribe to
* @param with_qos 0 for UNSUBSCRIBE, != 0 for SUBSCRIBE * @param with_qos 0 for UNSUBSCRIBE, != 0 for SUBSCRIBE
* @return 0 on success *
* @return -EINVAL on error * @retval 0 on success
* @retval -EINVAL on error
*/ */
static static
int subscribe_size(uint16_t *rlen_size, uint16_t *payload_size, uint8_t items, 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 * Packs the SUBSCRIBE and UNSUBSCRIBE messages
* @details Packs the SUBSCRIBE and UNSUBSCRIBE messages *
* @param buf Buffer where the message will be stored * @param buf Buffer where the message will be stored
* @param pkt_id Packet Identifier * @param pkt_id Packet Identifier
* @param items Number of topics * @param items Number of topics
* @param topics Array of C-strings containing the topics * @param topics Array of C-strings containing the topics to subscribe to
* to subscribe to * @param qos Array of QoS' values, qos[i] is the QoS of topic[i]
* @param qos Array of QoS' values, qos[i] is the QoS of topic[i] * @param type MQTT_SUBSCRIBE or MQTT_UNSUBSCRIBE
* @param type MQTT_SUBSCRIBE or MQTT_UNSUBSCRIBE *
* @return 0 on success * @retval 0 on success
* @return -EINVAL if invalid parameters were passed as arguments * @retval -EINVAL
* @return -ENOMEM if buf has no enough space to store the * @retval -ENOMEM
* resultant message
*/ */
static int mqtt_pack_subscribe_unsubscribe(uint8_t *buf, uint16_t *length, static int mqtt_pack_subscribe_unsubscribe(uint8_t *buf, uint16_t *length,
uint16_t size, uint16_t pkt_id, 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 * Packs a zero length message
* @details This function packs MQTT messages with no *
* payload. No validations are made about the * @details This function packs MQTT messages with no payload. No validations
* input arguments, besides 'size' that must be * are made about the input arguments, besides 'size' that must be at least
* at least 2 bytes * 2 bytes
* @param [out] buf Buffer where the resultant message is stored *
* @param [out] length Number of bytes required to codify the message * @param [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @param [in] pkt_type MQTT Control Packet Type. See MQTT 2.2.1 * @param [in] size Buffer size
* @param [in] reserved Reserved bits. See MQTT 2.2 * @param [in] pkt_type MQTT Control Packet Type. See MQTT 2.2.1
* @return 0 on success * @param [in] reserved Reserved bits. See MQTT 2.2
* @return -ENOMEM if buf has no enough reserved space *
* to store the resultant message * @retval 0 on success
* @retval -ENOMEM
*/ */
static static
int pack_zerolen(uint8_t *buf, uint16_t *length, uint16_t size, 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 * Unpacks a MQTT message with a Packet Id as payload
* as payload *
* @param [in] buf Buffer where the message is stored * @param [in] buf Buffer where the message is stored
* @param [in] length Message's length * @param [in] length Message's length
* @param [out] type MQTT Control Packet type * @param [out] type MQTT Control Packet type
* @param [out] reserved Reserved flags * @param [out] reserved Reserved flags
* @param [out] pkt_id Packet Identifier * @param [out] pkt_id Packet Identifier
* @return 0 on success *
* @return -EINVAL if an invalid parameter was passed * @retval 0 on success
* as an argument to this routine * @retval -EINVAL
*/ */
static static
int unpack_pktid(uint8_t *buf, uint16_t length, enum mqtt_packet *type, 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 * Unpacks and validates a MQTT message containing a Packet Identifier
* containing a Packet Identifier *
* @details The message codified in buf must contain a * @details The message codified in buf must contain a 1) packet type,
* 1) packet type, 2) reserved flags and * 2) reserved flags and 3) packet identifier. The user must provide the
* 3) packet identifier. * expected packet type and expected reserved flags. See MQTT 2.2.2 Flags.
* The user must provide the expected packet type * If the message contains different values for type and reserved flags
* and expected reserved flags. * than the ones passed as arguments, the function will return -EINVAL
* See MQTT 2.2.2 Flags. *
* If the message contains different values for * @param [in] buf Buffer where the message is stored
* type and reserved flags than the ones passed as * @param [in] length Message's length
* arguments, the function will return -EINVAL * @param [out] pkt_id Packet Identifier
* @param [in] buf Buffer where the message is stored * @param [in] expected_type Expected MQTT Control Packet type
* @param [in] length Message's length * @param [in] expected_reserv Expected Reserved Flags
* @param [out] pkt_id Packet Identifier *
* @param [in] expected_type Expected MQTT Control Packet type * @retval 0 on success
* @param [in] expected_reserv Expected Reserved Flags * @retval -EINVAL
* @return 0 on success
* @return -EINVAL if an invalid parameter was passed
* as an argument to this routine or if
* any test failed
*/ */
static static
int unpack_pktid_validate(uint8_t *buf, uint16_t length, uint16_t *pkt_id, 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 * Unpacks a zero-length MQTT message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @param [out] pkt_type MQTT Control Packet type * @param [in] length Message's length
* @param [out] reserved Reserved flags * @param [out] pkt_type MQTT Control Packet type
* @return 0 on success * @param [out] reserved Reserved flags
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @retval -EINVAL
*/ */
static static
int unpack_zerolen(uint8_t *buf, uint16_t length, enum mqtt_packet *pkt_type, 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 * Unpacks and validates a zero-len MQTT message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @param expected_type Expected MQTT Control Packet type * @param [in] length Message's length
* @param expected_reserved Expected Reserved Flags * @param expected_type Expected MQTT Control Packet type
* @return 0 on success * @param expected_reserved Expected Reserved Flags
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @retval -EINVAL
*/ */
static static
int unpack_zerolen_validate(uint8_t *buf, uint16_t length, int unpack_zerolen_validate(uint8_t *buf, uint16_t length,

495
subsys/net/lib/mqtt/mqtt_pkt.h
View file

@ -10,8 +10,8 @@
* @brief MQTT v3.1.1 packet library, see: * @brief MQTT v3.1.1 packet library, see:
* http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html * http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
* *
* This file is part of the Zephyr Project * This file is part of the Zephyr Project
* http://www.zephyrproject.org * http://www.zephyrproject.org
*/ */
#ifndef _MQTT_PKT_H_ #ifndef _MQTT_PKT_H_
@ -25,368 +25,383 @@
#define MQTT_PACKET_TYPE(first_byte) (((first_byte) & 0xF0) >> 4) #define MQTT_PACKET_TYPE(first_byte) (((first_byte) & 0xF0) >> 4)
/** /**
* @brief mqtt_pack_connack Packs the MQTT CONNACK message * Packs the MQTT CONNACK message. See MQTT 3.2 CONNACK - Acknowledge
* @details See MQTT 3.2 CONNACK - Acknowledge connection * connection request
* request *
* @param [out] buf Buffer where the resultant message is stored * @param [out] buf Buffer where the resultant message is stored
* @param [out] length Number of bytes required to codify the message * @param [out] length Number of bytes required to codify the message
* @param [in] size Buffer's size * @param [in] size Buffer size
* @param [in] session_present Session Present parameter (0 for clean session) * @param [in] session_present Session Present parameter (0 for clean session)
* @param [in] ret_code Connect return code. See MQTT 3.2.2.3 * @param [in] ret_code Connect return code. See MQTT 3.2.2.3
* @return 0 on success *
* @return -ENOMEM if size < 4 * @retval 0 on success
* @retval -ENOMEM if size < 4
*/ */
int mqtt_pack_connack(uint8_t *buf, uint16_t *length, uint16_t size, int mqtt_pack_connack(uint8_t *buf, uint16_t *length, uint16_t size,
uint8_t session_present, uint8_t ret_code); uint8_t session_present, uint8_t ret_code);
/** /**
* @brief mqtt_pack_puback Packs the MQTT PUBACK message * 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet * @param [in] size Buffer size
* Identifier * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
* @return 0 on success *
* @return -ENOMEM if size < 4 * @retval 0 on success
* @retval -ENOMEM if size < 4
*/ */
int mqtt_pack_puback(uint8_t *buf, uint16_t *length, uint16_t size, int mqtt_pack_puback(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id); uint16_t pkt_id);
/** /**
* @brief mqtt_pack_pubrec Packs the MQTT PUBREC message * 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet * @param [in] size Buffer size
* Identifier * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
* @return 0 on success *
* @return -ENOMEM if size < 4 * @retval 0 on success
* @retval -ENOMEM if size < 4
*/ */
int mqtt_pack_pubrec(uint8_t *buf, uint16_t *length, uint16_t size, int mqtt_pack_pubrec(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id); uint16_t pkt_id);
/** /**
* @brief mqtt_pack_puback Packs the MQTT PUBREL message * 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet * @param [in] size Buffer size
* Identifier * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
* @return 0 on success *
* @return -ENOMEM if size < 4 * @retval 0 on success
* @retval -ENOMEM if size < 4
*/ */
int mqtt_pack_pubrel(uint8_t *buf, uint16_t *length, uint16_t size, int mqtt_pack_pubrel(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id); uint16_t pkt_id);
/** /**
* @brief mqtt_pack_pubcomp Packs the MQTT PUBCOMP message * 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet * @param [in] size Buffer size
* Identifier * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
* @return 0 on success *
* @return -ENOMEM if size < 4 * @retval 0 on success
* @retval -ENOMEM if size < 4
*/ */
int mqtt_pack_pubcomp(uint8_t *buf, uint16_t *length, uint16_t size, int mqtt_pack_pubcomp(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id); uint16_t pkt_id);
/** /**
* @brief mqtt_pack_suback Packs the MQTT SUBACK 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 * @param [in] size Buffer size
* @param [in] elements Number of elements in the granted_qos array * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1
* @param [in] granted_qos Array where the QoS values are stored * @param [in] elements Number of elements in the granted_qos array
* See MQTT 3.9 SUBACK, 3.9.3 Payload * @param [in] granted_qos Array where the QoS values are stored
* @return 0 on success *
* @return -EINVAL if an invalid parameter was passed * @retval 0 on success
* as an argument to this routine * @retval -EINVAL
* @return -ENOMEM if buf does not have enough reserved * @retval -ENOMEM
* space to store the resultant message
*/ */
int mqtt_pack_suback(uint8_t *buf, uint16_t *length, uint16_t size, int mqtt_pack_suback(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id, uint8_t elements, uint16_t pkt_id, uint8_t elements,
enum mqtt_qos granted_qos[]); enum mqtt_qos granted_qos[]);
/** /**
* @brief mqtt_pack_connect Packs the MQTT CONNECT 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @param [in] msg MQTT CONNECT msg * @param [in] size Buffer size
* @return 0 on success * @param [in] msg MQTT CONNECT msg
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @return -ENOMEM if buf does not have enough reserved * @retval -EINVAL
* space to store the resultant message * @retval -ENOMEM
*/ */
int mqtt_pack_connect(uint8_t *buf, uint16_t *length, uint16_t size, int mqtt_pack_connect(uint8_t *buf, uint16_t *length, uint16_t size,
struct mqtt_connect_msg *msg); struct mqtt_connect_msg *msg);
/** /**
* @brief mqtt_unpack_connect Unpacks the MQTT CONNECT message * Unpacks the MQTT CONNECT message
* @param [in] buf Buffer where the message is stored *
* @param [in] length MQTT CONNECT message's length * @param [in] buf Buffer where the message is stored
* @param [out] msg MQTT CONNECT parameters * @param [in] length MQTT CONNECT message's length
* @return 0 on success * @param [out] msg MQTT CONNECT parameters
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_unpack_connect(uint8_t *buf, uint16_t length, int mqtt_unpack_connect(uint8_t *buf, uint16_t length,
struct mqtt_connect_msg *msg); struct mqtt_connect_msg *msg);
/** /**
* @brief mqtt_pack_subscribe Packs the MQTT SUBSCRIBE 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @param [in] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1 * @param [in] size Buffer size
* @param [in] items Number of elements in topics * @param [in] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1
* @param [in] topics Array of topics. * @param [in] items Number of elements in topics
* For example: {"sensors", "lights", "doors"} * @param [in] topics Array of topics.
* @param [in] qos Array of QoS values per topic. For example: * For example: {"sensors", "lights", "doors"}
{MQTT_QoS1, MQTT_QoS2, MQTT_QoS0} * @param [in] qos Array of QoS values per topic.
NOTE: qos and topics must have the same * For example: {MQTT_QoS1, MQTT_QoS2, MQTT_QoS0}
cardinality (# of items) * NOTE: qos and topics must have the same cardinality
* @return 0 on success * (# of items)
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @return -ENOMEM if buf does not have enough reserved * @retval -EINVAL
* space to store the resultant message * @retval -ENOMEM
*/ */
int mqtt_pack_subscribe(uint8_t *buf, uint16_t *length, uint16_t size, int mqtt_pack_subscribe(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id, uint8_t items, const char *topics[], uint16_t pkt_id, uint8_t items, const char *topics[],
const enum mqtt_qos qos[]); const enum mqtt_qos qos[]);
/** /**
* @brief mqtt_pack_unsubscribe Packs the MQTT UNSUBSCRIBE 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @param [in] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1 * @param [in] size Buffer size
* @param [in] items Number of elements in topics * @param [in] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1
* @param [in] topics Array of topics. * @param [in] items Number of elements in topics
* For example: {"sensors", "lights", "doors"} * @param [in] topics Array of topics.
* @return 0 on success * For example: {"sensors", "lights", "doors"}
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @return -ENOMEM if buf does not have enough reserved * @retval -EINVAL
* space to store the resultant message * @retval -ENOMEM
*/ */
int mqtt_pack_unsubscribe(uint8_t *buf, uint16_t *length, uint16_t size, int mqtt_pack_unsubscribe(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id, uint8_t items, const char *topics[]); uint16_t pkt_id, uint8_t items, const char *topics[]);
/** /**
* @brief mqtt_unpack_subscribe Unpacks the MQTT SUBSCRIBE message * Unpacks the MQTT SUBSCRIBE message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @param [out] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1 * @param [in] length Message's length
* @param [out] items Number of recovered topics * @param [out] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1
* @param [in] elements Max number of topics to recover from buf * @param [out] items Number of recovered topics
* @param [out] topics Array of topics. Each element in this array * @param [in] elements Max number of topics to recover from buf
* points to the beginning of a topic in buf * @param [out] topics Array of topics. Each element in this array points to
* @param [out] topic_len Array of topics' length. Each element in this * the beginning of a topic in buf
* array contains the length of the * @param [out] topic_len Array containing the length of each topic in topics
* @param [out] qos Array of QoS, * @param [out] qos Array of QoS values
* @return 0 on success *
* @return -EINVAL if an invalid parameter was passed * @retval 0 on success
* as an argument to this routine * @retval -EINVAL
*/ */
int mqtt_unpack_subscribe(uint8_t *buf, uint16_t length, uint16_t *pkt_id, int mqtt_unpack_subscribe(uint8_t *buf, uint16_t length, uint16_t *pkt_id,
uint8_t *items, uint8_t elements, char *topics[], uint8_t *items, uint8_t elements, char *topics[],
uint16_t topic_len[], enum mqtt_qos qos[]); uint16_t topic_len[], enum mqtt_qos qos[]);
/** /**
* @brief mqtt_unpack_suback Unpacks the MQTT SUBACK message * Unpacks the MQTT SUBACK message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @param [out] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1 * @param [in] length Message's length
* @param [out] items Number of recovered topics * @param [out] pkt_id MQTT Message Packet Identifier. See MQTT 2.3.1
* @param [in] elements Max number of topics to recover from buf * @param [out] items Number of recovered topics
* @param [out] granted_qos Granted QoS values per topic. See MQTT 3.9 * @param [in] elements Max number of topics to recover from buf
* @return 0 on success * @param [out] granted_qos Granted QoS values per topic. See MQTT 3.9
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_unpack_suback(uint8_t *buf, uint16_t length, uint16_t *pkt_id, int mqtt_unpack_suback(uint8_t *buf, uint16_t length, uint16_t *pkt_id,
uint8_t *items, uint8_t elements, uint8_t *items, uint8_t elements,
enum mqtt_qos granted_qos[]); enum mqtt_qos granted_qos[]);
/** /**
* @brief mqtt_pack_publish Packs the MQTT PUBLISH 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @param [in] msg MQTT PUBLISH message * @param [in] size Buffer size
* @return 0 on success * @param [in] msg MQTT PUBLISH message
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @return -ENOMEM if buf does not have enough reserved * @retval -EINVAL
* space to store the resultant message * @retval -ENOMEM
*/ */
int mqtt_pack_publish(uint8_t *buf, uint16_t *length, uint16_t size, int mqtt_pack_publish(uint8_t *buf, uint16_t *length, uint16_t size,
struct mqtt_publish_msg *msg); struct mqtt_publish_msg *msg);
/** /**
* @brief mqtt_unpack_publish Unpacks the MQTT PUBLISH message * Unpacks the MQTT PUBLISH message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @param [out] msg MQTT PUBLISH message * @param [in] length Message's length
* @return 0 on success * @param [out] msg MQTT PUBLISH message
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_unpack_publish(uint8_t *buf, uint16_t length, int mqtt_unpack_publish(uint8_t *buf, uint16_t length,
struct mqtt_publish_msg *msg); struct mqtt_publish_msg *msg);
/** /**
* @brief mqtt_unpack_connack Unpacks the MQTT CONNACK message * Unpacks the MQTT CONNACK message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @param [out] session Session Present. See MQTT 3.2.2.2 * @param [in] length Message's length
* @param [out] connect_rc CONNECT return code. See MQTT 3.2.2.3 * @param [out] session Session Present. See MQTT 3.2.2.2
* @return 0 on success * @param [out] connect_rc CONNECT return code. See MQTT 3.2.2.3
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_unpack_connack(uint8_t *buf, uint16_t length, uint8_t *session, int mqtt_unpack_connack(uint8_t *buf, uint16_t length, uint8_t *session,
uint8_t *connect_rc); uint8_t *connect_rc);
/** /**
* @brief mqtt_pack_pingreq Packs the MQTT PINGREQ 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @return 0 on success * @param [in] size Buffer size
* @return -ENOMEM if buf does not have enough reserved *
* space to store the resultant message * @retval 0 on success
* @retval -ENOMEM
*/ */
int mqtt_pack_pingreq(uint8_t *buf, uint16_t *length, uint16_t size); int mqtt_pack_pingreq(uint8_t *buf, uint16_t *length, uint16_t size);
/** /**
* @brief mqtt_pack_pingresp Packs the MQTT PINGRESP 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @return 0 on success * @param [in] size Buffer size
* @return -ENOMEM if buf does not have enough reserved *
* space to store the resultant message * @retval 0 on success
* @retval -ENOMEM
*/ */
int mqtt_pack_pingresp(uint8_t *buf, uint16_t *length, uint16_t size); int mqtt_pack_pingresp(uint8_t *buf, uint16_t *length, uint16_t size);
/** /**
* @brief mqtt_pack_disconnect Packs the MQTT DISCONNECT 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @return 0 on success * @param [in] size Buffer size
* @return -ENOMEM if buf does not have enough reserved *
* space to store the resultant message * @retval 0 on success
* @retval -ENOMEM
*/ */
int mqtt_pack_disconnect(uint8_t *buf, uint16_t *length, uint16_t size); int mqtt_pack_disconnect(uint8_t *buf, uint16_t *length, uint16_t size);
/** /**
* @brief mqtt_pack_unsuback Packs the MQTT UNSUBACK message * 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 [out] buf Buffer where the resultant message is stored
* @param [in] size Buffer's size * @param [out] length Number of bytes required to codify the message
* @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet * @param [in] size Buffer size
* Identifier * @param [in] pkt_id Packet Identifier. See MQTT 2.3.1 Packet Identifier
* @return 0 on success *
* @return -ENOMEM if size < 4 * @retval 0 on success
* @retval -ENOMEM if size < 4
*/ */
int mqtt_pack_unsuback(uint8_t *buf, uint16_t *length, uint16_t size, int mqtt_pack_unsuback(uint8_t *buf, uint16_t *length, uint16_t size,
uint16_t pkt_id); uint16_t pkt_id);
/** /**
* @brief mqtt_unpack_puback Unpacks the MQTT PUBACK message * Unpacks the MQTT PUBACK message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @param [out] pkt_id Packet Identifier * @param [in] length Message's length
* @return 0 on success * @param [out] pkt_id Packet Identifier
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine or if * @retval 0 on success
* buf does not contain the desired msg * @retval -EINVAL
*/ */
int mqtt_unpack_puback(uint8_t *buf, uint16_t length, uint16_t *pkt_id); int mqtt_unpack_puback(uint8_t *buf, uint16_t length, uint16_t *pkt_id);
/** /**
* @brief mqtt_unpack_pubrec Unpacks the MQTT PUBREC message * Unpacks the MQTT PUBREC message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @param [out] pkt_id Packet Identifier * @param [in] length Message's length
* @return 0 on success * @param [out] pkt_id Packet Identifier
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine or if * @retval 0 on success
* buf does not contain the desired msg * @retval -EINVAL
*/ */
int mqtt_unpack_pubrec(uint8_t *buf, uint16_t length, uint16_t *pkt_id); int mqtt_unpack_pubrec(uint8_t *buf, uint16_t length, uint16_t *pkt_id);
/** /**
* @brief mqtt_unpack_pubrel Unpacks the MQTT PUBREL message * Unpacks the MQTT PUBREL message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @param [out] pkt_id Packet Identifier * @param [in] length Message's length
* @return 0 on success * @param [out] pkt_id Packet Identifier
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine or if * @retval 0 on success
* buf does not contain the desired msg * @retval -EINVAL
*/ */
int mqtt_unpack_pubrel(uint8_t *buf, uint16_t length, uint16_t *pkt_id); int mqtt_unpack_pubrel(uint8_t *buf, uint16_t length, uint16_t *pkt_id);
/** /**
* @brief mqtt_unpack_pubcomp Unpacks the MQTT PUBCOMP message * Unpacks the MQTT PUBCOMP message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @param [out] pkt_id Packet Identifier * @param [in] length Message's length
* @return 0 on success * @param [out] pkt_id Packet Identifier
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine or if * @retval 0 on success
* buf does not contain the desired msg * @retval -EINVAL
*/ */
int mqtt_unpack_pubcomp(uint8_t *buf, uint16_t length, uint16_t *pkt_id); int mqtt_unpack_pubcomp(uint8_t *buf, uint16_t length, uint16_t *pkt_id);
/** /**
* @brief mqtt_unpack_unsuback Unpacks the MQTT UNSUBACK message * Unpacks the MQTT UNSUBACK message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @param [out] pkt_id Packet Identifier * @param [in] length Message's length
* @return 0 on success * @param [out] pkt_id Packet Identifier
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine or if * @retval 0 on success
* buf does not contain the desired msg * @retval -EINVAL
*/ */
int mqtt_unpack_unsuback(uint8_t *buf, uint16_t length, uint16_t *pkt_id); int mqtt_unpack_unsuback(uint8_t *buf, uint16_t length, uint16_t *pkt_id);
/** /**
* @brief mqtt_unpack_pingreq Unpacks the MQTT PINGREQ message * Unpacks the MQTT PINGREQ message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @return 0 on success * @param [in] length Message's length
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_unpack_pingreq(uint8_t *buf, uint16_t length); int mqtt_unpack_pingreq(uint8_t *buf, uint16_t length);
/** /**
* @brief mqtt_unpack_pingresp Unpacks the MQTT PINGRESP message * Unpacks the MQTT PINGRESP message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @return 0 on success * @param [in] length Message's length
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_unpack_pingresp(uint8_t *buf, uint16_t length); int mqtt_unpack_pingresp(uint8_t *buf, uint16_t length);
/** /**
* @brief mqtt_unpack_disconnect Unpacks the MQTT DISCONNECT message * Unpacks the MQTT DISCONNECT message
* @param [in] buf Buffer where the message is stored *
* @param [in] length Message's length * @param [in] buf Buffer where the message is stored
* @return 0 on success * @param [in] length Message's length
* @return -EINVAL if an invalid parameter was passed *
* as an argument to this routine * @retval 0 on success
* @retval -EINVAL
*/ */
int mqtt_unpack_disconnect(uint8_t *buf, uint16_t length); int mqtt_unpack_disconnect(uint8_t *buf, uint16_t length);