net/mqtt: Fix inline doc for MQTT
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
Jukka Rissanen
parent
449cbbd874
commit
bed71d0a02
4 changed files with 659 additions and 623 deletions
|
|
@ -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,32 +74,30 @@ 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.
|
||||
*
|
||||
* <b>Note: this callback must be not NULL</b>
|
||||
*
|
||||
* @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 <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,
|
||||
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
|
||||
*
|
||||
* <b>Note: this callback must be not NULL</b>
|
||||
*
|
||||
|
|
@ -108,24 +106,14 @@ struct mqtt_ctx {
|
|||
* 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 <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,
|
||||
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.
|
||||
*
|
||||
* <b>Note: this callback must be not NULL</b>
|
||||
*
|
||||
|
|
@ -133,25 +121,19 @@ struct mqtt_ctx {
|
|||
* @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
|
||||
*/
|
||||
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
|
||||
*
|
||||
* <b>Note: this callback must be not NULL</b>
|
||||
*
|
||||
* @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
|
||||
* Initializes the MQTT context structure
|
||||
*
|
||||
* @param ctx MQTT context structure
|
||||
* @param app_type See enum mqtt_app
|
||||
* @return 0, always.
|
||||
* @retval 0, always.
|
||||
*/
|
||||
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
|
||||
* @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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* Parses and validates the MQTT PUBREL message
|
||||
*
|
||||
* @param [in] ctx MQTT context structure
|
||||
* @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);
|
||||
|
||||
/**
|
||||
* @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
|
||||
* @return 0 on success
|
||||
* @return -EINVAL on error
|
||||
*
|
||||
* @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
|
||||
* Parses the MQTT SUBACK message
|
||||
*
|
||||
* @param [in] ctx MQTT context structure
|
||||
* @param [in] rx Data buffer
|
||||
* @return 0 on success
|
||||
* @return -EINVAL on error
|
||||
*
|
||||
* @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
|
||||
* Parses the MQTT UNSUBACK message
|
||||
*
|
||||
* @param [in] ctx MQTT context structure
|
||||
* @param [in] rx Data buffer
|
||||
* @return 0 on success
|
||||
* @return -EINVAL on error
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @retval 0 on success
|
||||
* @retval -EINVAL
|
||||
* @retval -ENOMEM
|
||||
*/
|
||||
int mqtt_rx_publish(struct mqtt_ctx *ctx, struct net_buf *rx);
|
||||
|
||||
|
|
|
|||
|
|
@ -113,16 +113,16 @@ exit_disconnect:
|
|||
}
|
||||
|
||||
/**
|
||||
* @brief mqtt_tx_pub_msgs Writes the MQTT PUBxxx msg indicated by pkt_type
|
||||
* with identifier 'id'
|
||||
* 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
|
||||
*
|
||||
* @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.
|
||||
* 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
|
||||
* @return 0 on success
|
||||
* @return -EINVAL on error
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
* @return Data buffer
|
||||
* @return NULL on error
|
||||
* @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)
|
||||
* 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
|
||||
*
|
||||
* @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,17 +743,18 @@ 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)
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
* @return 0 on success
|
||||
* @return -EINVAL is len is out of range
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
* @return 0 always
|
||||
*
|
||||
* @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
|
||||
* 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] buf Buffer where the codified Remaining Length is codified
|
||||
* @param [in] size Buffer size
|
||||
* @return 0 on success
|
||||
* @return -ENOMEM if size < 4
|
||||
*
|
||||
* @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.
|
||||
*
|
||||
* @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.
|
||||
*
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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)
|
||||
* 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 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
|
||||
*
|
||||
* @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
|
||||
* 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 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
|
||||
*
|
||||
* @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
|
||||
* 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] 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
|
||||
* @return 0 on success
|
||||
* @return -ENOMEM if buf has no enough reserved space
|
||||
* to store the resultant message
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @retval 0 on success
|
||||
* @retval -EINVAL
|
||||
*/
|
||||
static
|
||||
int unpack_zerolen_validate(uint8_t *buf, uint16_t length,
|
||||
|
|
|
|||
|
|
@ -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
|
||||
* 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's size
|
||||
* @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
|
||||
* @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,
|
||||
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 [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
|
||||
* @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
|
||||
* 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
|
||||
* @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
|
||||
* 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
|
||||
* @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
|
||||
* 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
|
||||
* @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
|
||||
* 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] 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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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] size Buffer 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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] 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)
|
||||
* @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
|
||||
* @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
|
||||
* 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] 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"}
|
||||
* @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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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] size Buffer 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
* @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
|
||||
* 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
|
||||
* @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
|
||||
* 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
|
||||
* @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
|
||||
* 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
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* @retval 0 on success
|
||||
* @retval -EINVAL
|
||||
*/
|
||||
int mqtt_unpack_disconnect(uint8_t *buf, uint16_t length);
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue