mqtt.h File Reference

Declares all the MQTT-C functions and datastructures. More...

#include <mqtt_pal.h>

Include dependency graph for mqtt.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	mqtt_fixed_header
	The fixed header of an MQTT control packet. More...
struct	mqtt_response_connack
	A connection response datastructure. More...
struct	mqtt_response_publish
	A publish packet received from the broker. More...
struct	mqtt_response_puback
	A publish acknowledgement for messages that were published with QoS level 1. More...
struct	mqtt_response_pubrec
	The response packet to a PUBLISH packet with QoS level 2. More...
struct	mqtt_response_pubrel
	The response to a PUBREC packet. More...
struct	mqtt_response_pubcomp
	The response to a PUBREL packet. More...
struct	mqtt_response_suback
	The response to a subscription request. More...
struct	mqtt_response_unsuback
	The brokers response to a UNSUBSCRIBE request. More...
struct	mqtt_response_pingresp
	The response to a ping request. More...
struct	mqtt_response
	A struct used to deserialize/interpret an incoming packet from the broker. More...
struct	mqtt_queued_message
	A message in a mqtt_message_queue. More...
struct	mqtt_message_queue
	A message queue. More...
struct	mqtt_client
	An MQTT client. More...

Macros
#define	MQTT_PROTOCOL_LEVEL   0x04
	The protocol identifier for MQTT v3.1.1.
#define	__ALL_MQTT_ERRORS(MQTT_ERROR)
	A macro used to declare the enum MQTTErrors and associated error messages (the members of the num) at the same time.
#define	GENERATE_ENUM(ENUM)
	A macro used to generate the enum MQTTErrors from __ALL_MQTT_ERRORS.
#define	GENERATE_STRING(STRING)
	A macro used to generate the error messages associated with MQTTErrors from __ALL_MQTT_ERRORS.
#define	__mqtt_packed_cstrlen(x)
	A macro to get the MQTT string length from a c-string.
#define	MQTT_SUBSCRIBE_REQUEST_MAX_NUM_TOPICS   8
	The maximum number topics that can be subscribed to in a single call to mqtt_pack_subscribe_request.
#define	MQTT_UNSUBSCRIBE_REQUEST_MAX_NUM_TOPICS   8
	The maximum number topics that can be subscribed to in a single call to mqtt_pack_unsubscribe_request.
#define	mqtt_mq_get(mq_ptr, index)
	Returns the mqtt_queued_message at index.
#define	mqtt_mq_length(mq_ptr)
	Returns the number of messages in the message queue, mq_ptr.
#define	mqtt_mq_currsz(mq_ptr)
	Used internally to recalculate the curr_sz.

Enumerations
enum	MQTTControlPacketType {   MQTT_CONTROL_CONNECT =1u , MQTT_CONTROL_CONNACK =2u , MQTT_CONTROL_PUBLISH =3u , MQTT_CONTROL_PUBACK =4u ,   MQTT_CONTROL_PUBREC =5u , MQTT_CONTROL_PUBREL =6u , MQTT_CONTROL_PUBCOMP =7u , MQTT_CONTROL_SUBSCRIBE =8u ,   MQTT_CONTROL_SUBACK =9u , MQTT_CONTROL_UNSUBSCRIBE =10u , MQTT_CONTROL_UNSUBACK =11u , MQTT_CONTROL_PINGREQ =12u ,   MQTT_CONTROL_PINGRESP =13u , MQTT_CONTROL_DISCONNECT =14u }
	An enumeration of the MQTT control packet types. More...
enum	MQTTErrors {   MQTT_ERROR_UNKNOWN =INT_MIN , MQTT_ERROR_NULLPTR , MQTT_ERROR_CONTROL_FORBIDDEN_TYPE , MQTT_ERROR_CONTROL_INVALID_FLAGS ,   MQTT_ERROR_CONTROL_WRONG_TYPE , MQTT_ERROR_CONNECT_CLIENT_ID_REFUSED , MQTT_ERROR_CONNECT_NULL_WILL_MESSAGE , MQTT_ERROR_CONNECT_FORBIDDEN_WILL_QOS ,   MQTT_ERROR_CONNACK_FORBIDDEN_FLAGS , MQTT_ERROR_CONNACK_FORBIDDEN_CODE , MQTT_ERROR_PUBLISH_FORBIDDEN_QOS , MQTT_ERROR_SUBSCRIBE_TOO_MANY_TOPICS ,   MQTT_ERROR_MALFORMED_RESPONSE , MQTT_ERROR_UNSUBSCRIBE_TOO_MANY_TOPICS , MQTT_ERROR_RESPONSE_INVALID_CONTROL_TYPE , MQTT_ERROR_CONNECT_NOT_CALLED ,   MQTT_ERROR_SEND_BUFFER_IS_FULL , MQTT_ERROR_SOCKET_ERROR , MQTT_ERROR_MALFORMED_REQUEST , MQTT_ERROR_RECV_BUFFER_TOO_SMALL ,   MQTT_ERROR_ACK_OF_UNKNOWN , MQTT_ERROR_NOT_IMPLEMENTED , MQTT_ERROR_CONNECTION_REFUSED , MQTT_ERROR_SUBSCRIBE_FAILED ,   MQTT_ERROR_CONNECTION_CLOSED , MQTT_ERROR_INITIAL_RECONNECT , MQTT_ERROR_INVALID_REMAINING_LENGTH , MQTT_ERROR_CLEAN_SESSION_IS_REQUIRED ,   MQTT_ERROR_RECONNECT_FAILED , MQTT_ERROR_RECONNECTING , MQTT_OK = 1 }
	An enumeration of error codes. Error messages can be retrieved by calling mqtt_error_str. More...
enum	MQTTConnackReturnCode {   MQTT_CONNACK_ACCEPTED = 0u , MQTT_CONNACK_REFUSED_PROTOCOL_VERSION = 1u , MQTT_CONNACK_REFUSED_IDENTIFIER_REJECTED = 2u , MQTT_CONNACK_REFUSED_SERVER_UNAVAILABLE = 3u ,   MQTT_CONNACK_REFUSED_BAD_USER_NAME_OR_PASSWORD = 4u , MQTT_CONNACK_REFUSED_NOT_AUTHORIZED = 5u }
	An enumeration of the return codes returned in a CONNACK packet. More...
enum	MQTTSubackReturnCodes { MQTT_SUBACK_SUCCESS_MAX_QOS_0 = 0u , MQTT_SUBACK_SUCCESS_MAX_QOS_1 = 1u , MQTT_SUBACK_SUCCESS_MAX_QOS_2 = 2u , MQTT_SUBACK_FAILURE = 128u }
	An enumeration of subscription acknowledgement return codes. More...
enum	MQTTConnectFlags {   MQTT_CONNECT_RESERVED = 1u , MQTT_CONNECT_CLEAN_SESSION = 2u , MQTT_CONNECT_WILL_FLAG = 4u , MQTT_CONNECT_WILL_QOS_0 = (0u & 0x03) << 3 ,   MQTT_CONNECT_WILL_QOS_1 = (1u & 0x03) << 3 , MQTT_CONNECT_WILL_QOS_2 = (2u & 0x03) << 3 , MQTT_CONNECT_WILL_RETAIN = 32u , MQTT_CONNECT_PASSWORD = 64u ,   MQTT_CONNECT_USER_NAME = 128u }
	An enumeration of CONNECT packet flags. More...
enum	MQTTPublishFlags {   MQTT_PUBLISH_DUP = 8u , MQTT_PUBLISH_QOS_0 = ((0u << 1) & 0x06) , MQTT_PUBLISH_QOS_1 = ((1u << 1) & 0x06) , MQTT_PUBLISH_QOS_2 = ((2u << 1) & 0x06) ,   MQTT_PUBLISH_QOS_MASK = ((3u << 1) & 0x06) , MQTT_PUBLISH_RETAIN = 0x01 }
	An enumeration of the PUBLISH flags. More...
enum	MQTTQueuedMessageState { MQTT_QUEUED_UNSENT , MQTT_QUEUED_AWAITING_ACK , MQTT_QUEUED_COMPLETE }
	An enumeration of queued message states.

Functions
const char *	mqtt_error_str (enum MQTTErrors error)
	Returns an error message for error code, error.
ssize_t	__mqtt_pack_uint16 (uint8_t *buf, uint16_t integer)
	Pack a MQTT 16 bit integer, given a native 16 bit integer .
uint16_t	__mqtt_unpack_uint16 (const uint8_t *buf)
	Unpack a MQTT 16 bit integer to a native 16 bit integer.
ssize_t	__mqtt_pack_str (uint8_t *buf, const char *str)
	Pack a MQTT string, given a c-string str.
ssize_t	mqtt_unpack_fixed_header (struct mqtt_response *response, const uint8_t *buf, size_t bufsz)
	Deserialize the contents of buf into an mqtt_fixed_header object.
ssize_t	mqtt_pack_fixed_header (uint8_t *buf, size_t bufsz, const struct mqtt_fixed_header *fixed_header)
	Serialize an mqtt_fixed_header and write it to buf.
ssize_t	mqtt_pack_connection_request (uint8_t *buf, size_t bufsz, const char *client_id, const char *will_topic, const void *will_message, size_t will_message_size, const char *user_name, const char *password, uint8_t connect_flags, uint16_t keep_alive)
	Serialize a connection request into a buffer.
ssize_t	mqtt_pack_publish_request (uint8_t *buf, size_t bufsz, const char *topic_name, uint16_t packet_id, const void *application_message, size_t application_message_size, uint8_t publish_flags)
	Serialize a PUBLISH request and put it in buf.
ssize_t	mqtt_pack_pubxxx_request (uint8_t *buf, size_t bufsz, enum MQTTControlPacketType control_type, uint16_t packet_id)
	Serialize a PUBACK, PUBREC, PUBREL, or PUBCOMP packet and put it in buf.
ssize_t	mqtt_pack_subscribe_request (uint8_t *buf, size_t bufsz, unsigned int packet_id,...)
	Serialize a SUBSCRIBE packet and put it in buf.
ssize_t	mqtt_pack_unsubscribe_request (uint8_t *buf, size_t bufsz, unsigned int packet_id,...)
	Serialize a UNSUBSCRIBE packet and put it in buf.
ssize_t	mqtt_pack_ping_request (uint8_t *buf, size_t bufsz)
	Serialize a PINGREQ and put it into buf.
ssize_t	mqtt_pack_disconnect (uint8_t *buf, size_t bufsz)
	Serialize a DISCONNECT and put it into buf.
uint16_t	__mqtt_next_pid (struct mqtt_client *client)
	Generate a new next packet ID.
ssize_t	__mqtt_send (struct mqtt_client *client)
	Handles egress client traffic.
ssize_t	__mqtt_recv (struct mqtt_client *client)
	Handles ingress client traffic.
enum MQTTErrors	mqtt_sync (struct mqtt_client *client)
	Function that does the actual sending and receiving of traffic from the network.
enum MQTTErrors	mqtt_init (struct mqtt_client *client, mqtt_pal_socket_handle sockfd, uint8_t *sendbuf, size_t sendbufsz, uint8_t *recvbuf, size_t recvbufsz, void(*publish_response_callback)(void **state, struct mqtt_response_publish *publish))
	Initializes an MQTT client.
void	mqtt_init_reconnect (struct mqtt_client *client, void(*reconnect_callback)(struct mqtt_client *client, void **state), void *reconnect_state, void(*publish_response_callback)(void **state, struct mqtt_response_publish *publish))
	Initializes an MQTT client and enables automatic reconnections.
void	mqtt_reinit (struct mqtt_client *client, mqtt_pal_socket_handle socketfd, uint8_t *sendbuf, size_t sendbufsz, uint8_t *recvbuf, size_t recvbufsz)
	Safely assign/reassign a socket and buffers to an new/existing client.
enum MQTTErrors	mqtt_connect (struct mqtt_client *client, const char *client_id, const char *will_topic, const void *will_message, size_t will_message_size, const char *user_name, const char *password, uint8_t connect_flags, uint16_t keep_alive)
	Establishes a session with the MQTT broker.
enum MQTTErrors	mqtt_publish (struct mqtt_client *client, const char *topic_name, const void *application_message, size_t application_message_size, uint8_t publish_flags)
	Publish an application message.
ssize_t	__mqtt_puback (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree publish with QOS==1.
ssize_t	__mqtt_pubrec (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree publish with QOS==2.
ssize_t	__mqtt_pubrel (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree PUBREC packet.
ssize_t	__mqtt_pubcomp (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree PUBREL packet.
enum MQTTErrors	mqtt_subscribe (struct mqtt_client *client, const char *topic_name, int max_qos_level)
	Subscribe to a topic.
enum MQTTErrors	mqtt_unsubscribe (struct mqtt_client *client, const char *topic_name)
	Unsubscribe from a topic.
enum MQTTErrors	mqtt_ping (struct mqtt_client *client)
	Ping the broker.
enum MQTTErrors	__mqtt_ping (struct mqtt_client *client)
	Ping the broker without locking/unlocking the mutex.
enum MQTTErrors	mqtt_disconnect (struct mqtt_client *client)
	Terminate the session with the MQTT broker.
enum MQTTErrors	mqtt_reconnect (struct mqtt_client *client)
	Terminate the session with the MQTT broker and prepare to reconnect. Client code should call mqtt_sync immediately after this call to prevent message loss.

Detailed Description

Declares all the MQTT-C functions and datastructures.

Note

You should #include <mqtt.h>.

Macro Definition Documentation

__ALL_MQTT_ERRORS

#define __ALL_MQTT_ERRORS

(

MQTT_ERROR

)

Value:

MQTT_ERROR(MQTT_ERROR_NULLPTR)                       \
MQTT_ERROR(MQTT_ERROR_CONTROL_FORBIDDEN_TYPE)        \
MQTT_ERROR(MQTT_ERROR_CONTROL_INVALID_FLAGS)         \
MQTT_ERROR(MQTT_ERROR_CONTROL_WRONG_TYPE)            \
MQTT_ERROR(MQTT_ERROR_CONNECT_CLIENT_ID_REFUSED)     \
MQTT_ERROR(MQTT_ERROR_CONNECT_NULL_WILL_MESSAGE)     \
MQTT_ERROR(MQTT_ERROR_CONNECT_FORBIDDEN_WILL_QOS)    \
MQTT_ERROR(MQTT_ERROR_CONNACK_FORBIDDEN_FLAGS)       \
MQTT_ERROR(MQTT_ERROR_CONNACK_FORBIDDEN_CODE)        \
MQTT_ERROR(MQTT_ERROR_PUBLISH_FORBIDDEN_QOS)         \
MQTT_ERROR(MQTT_ERROR_SUBSCRIBE_TOO_MANY_TOPICS)     \
MQTT_ERROR(MQTT_ERROR_MALFORMED_RESPONSE)            \
MQTT_ERROR(MQTT_ERROR_UNSUBSCRIBE_TOO_MANY_TOPICS)   \
MQTT_ERROR(MQTT_ERROR_RESPONSE_INVALID_CONTROL_TYPE) \
MQTT_ERROR(MQTT_ERROR_CONNECT_NOT_CALLED)            \
MQTT_ERROR(MQTT_ERROR_SEND_BUFFER_IS_FULL)           \
MQTT_ERROR(MQTT_ERROR_SOCKET_ERROR)                  \
MQTT_ERROR(MQTT_ERROR_MALFORMED_REQUEST)             \
MQTT_ERROR(MQTT_ERROR_RECV_BUFFER_TOO_SMALL)         \
MQTT_ERROR(MQTT_ERROR_ACK_OF_UNKNOWN)                \
MQTT_ERROR(MQTT_ERROR_NOT_IMPLEMENTED)               \
MQTT_ERROR(MQTT_ERROR_CONNECTION_REFUSED)            \
MQTT_ERROR(MQTT_ERROR_SUBSCRIBE_FAILED)              \
MQTT_ERROR(MQTT_ERROR_CONNECTION_CLOSED)             \
MQTT_ERROR(MQTT_ERROR_INITIAL_RECONNECT)             \
MQTT_ERROR(MQTT_ERROR_INVALID_REMAINING_LENGTH)      \
MQTT_ERROR(MQTT_ERROR_CLEAN_SESSION_IS_REQUIRED)     \
MQTT_ERROR(MQTT_ERROR_RECONNECT_FAILED)              \
MQTT_ERROR(MQTT_ERROR_RECONNECTING)

A macro used to declare the enum MQTTErrors and associated error messages (the members of the num) at the same time.

__mqtt_packed_cstrlen

#define __mqtt_packed_cstrlen

(

x

)

Value:

(2 + (unsigned int)strlen(x))

A macro to get the MQTT string length from a c-string.

GENERATE_ENUM

#define GENERATE_ENUM

(

ENUM

)

Value:

ENUM,

A macro used to generate the enum MQTTErrors from __ALL_MQTT_ERRORS.

See also

__ALL_MQTT_ERRORS

GENERATE_STRING

#define GENERATE_STRING

(

STRING

)

Value:

#STRING,

A macro used to generate the error messages associated with MQTTErrors from __ALL_MQTT_ERRORS.

See also

__ALL_MQTT_ERRORS

Function Documentation

__mqtt_pack_str()

ssize_t __mqtt_pack_str	(	uint8_t *	buf,
		const char *	str )

Pack a MQTT string, given a c-string str.

Parameters

[out]	buf	the buffer that the MQTT string will be written to.
[in]	str	the c-string to be written to buf.

Warning

This function provides no error checking.

Returns

strlen(str) + 2

__mqtt_pack_uint16()

ssize_t __mqtt_pack_uint16	(	uint8_t *	buf,
		uint16_t	integer )

Pack a MQTT 16 bit integer, given a native 16 bit integer .

Parameters

[out]	buf	the buffer that the MQTT integer will be written to.
[in]	integer	the native integer to be written to buf.

Warning

This function provides no error checking.

Returns

2

__mqtt_ping()

enum MQTTErrors __mqtt_ping

(

struct mqtt_client *

client

)

Ping the broker without locking/unlocking the mutex.

See also

mqtt_ping

__mqtt_unpack_uint16()

uint16_t __mqtt_unpack_uint16

(

const uint8_t *

buf

)

Unpack a MQTT 16 bit integer to a native 16 bit integer.

Parameters

[in]

buf

the buffer that the MQTT integer will be read from.

Warning

This function provides no error checking and does not modify buf.

Returns

The native integer