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:

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.A publish packet is received from the broker when a client publishes to a topic that the {local client} is subscribed to. 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. More...

#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. More...

#define	GENERATE_ENUM(ENUM) ENUM,
	A macro used to generate the enum MQTTErrors from __ALL_MQTT_ERRORS. More...

#define	GENERATE_STRING(STRING) #STRING,
	A macro used to generate the error messages associated with MQTTErrors from __ALL_MQTT_ERRORS. More...

#define	__mqtt_packed_cstrlen(x) (2 + strlen(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. More...

#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. More...

#define	mqtt_mq_get(mq_ptr, index) (((struct mqtt_queued_message*) ((mq_ptr)->mem_end)) - 1 - index)
	Returns the mqtt_queued_message at `index`. More...

#define	mqtt_mq_length(mq_ptr) (((struct mqtt_queued_message*) ((mq_ptr)->mem_end)) - (mq_ptr)->queue_tail)
	Returns the number of messages in the message queue, `mq_ptr`.

#define	mqtt_mq_currsz(mq_ptr) (mq_ptr->curr >= (uint8_t) ((mq_ptr)->queue_tail - 1)) ? 0 : ((uint8_t) ((mq_ptr)->queue_tail - 1)) - (mq_ptr)->curr
	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_NULL_CLIENT_ID, 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_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`. More...

ssize_t	__mqtt_pack_uint16 (uint8_t *buf, uint16_t integer)
	Pack a MQTT 16 bit integer, given a native 16 bit integer . More...

uint16_t	__mqtt_unpack_uint16 (const uint8_t *buf)
	Unpack a MQTT 16 bit integer to a native 16 bit integer. More...

ssize_t	__mqtt_pack_str (uint8_t buf, const char str)
	Pack a MQTT string, given a c-string `str`. More...

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. More...

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`. More...

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. More...

ssize_t	mqtt_pack_publish_request (uint8_t buf, size_t bufsz, const char topic_name, uint16_t packet_id, void *application_message, size_t application_message_size, uint8_t publish_flags)
	Serialize a PUBLISH request and put it in `buf`. More...

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`. More...

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`. More...

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`. More...

ssize_t	mqtt_pack_ping_request (uint8_t *buf, size_t bufsz)
	Serialize a PINGREQ and put it into `buf`. More...

ssize_t	mqtt_pack_disconnect (uint8_t *buf, size_t bufsz)
	Serialize a DISCONNECT and put it into `buf`. More...

uint16_t	__mqtt_next_pid (struct mqtt_client *client)
	Generate a new next packet ID.Packet ID's are generated using a max-length LFSR. More...

ssize_t	__mqtt_send (struct mqtt_client *client)
	Handles egress client traffic. More...

ssize_t	__mqtt_recv (struct mqtt_client *client)
	Handles ingress client traffic. More...

enum MQTTErrors	mqtt_sync (struct mqtt_client *client)
	Function that does the actual sending and receiving of traffic from the network.All the other functions in the API simply stage messages for being sent to the broker. This function does the actual sending of those messages. Additionally this function receives traffic (responses and acknowledgements) from the broker and responds to that traffic accordingly. Lastly this function also calls the `publish_response_callback` when any `MQTT_CONTROL_PUBLISH` messages are received. More...

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.This function must be called before any other API function calls. More...

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.An alternative to mqtt_init that allows the client to automatically reconnect to the broker after an error occurs (e.g. socket error or internal buffer overflows). More...

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.This function also clears the `client` error state. Upon exiting this function `client->error` will be `MQTT_ERROR_CONNECT_NOT_CALLED` (which will be cleared) as soon as mqtt_connect is called. More...

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. More...

enum MQTTErrors	mqtt_publish (struct mqtt_client client, const char topic_name, void *application_message, size_t application_message_size, uint8_t publish_flags)
	Publish an application message.Publishes an application message to the MQTT broker. More...

ssize_t	__mqtt_puback (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree publish with QOS==1. More...

ssize_t	__mqtt_pubrec (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree publish with QOS==2. More...

ssize_t	__mqtt_pubrel (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree PUBREC packet. More...

ssize_t	__mqtt_pubcomp (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree PUBREL packet. More...

enum MQTTErrors	mqtt_subscribe (struct mqtt_client client, const char topic_name, int max_qos_level)
	Subscribe to a topic. More...

enum MQTTErrors	mqtt_unsubscribe (struct mqtt_client client, const char topic_name)
	Unsubscribe from a topic. More...

enum MQTTErrors	mqtt_ping (struct mqtt_client *client)
	Ping the broker. More...

enum MQTTErrors	__mqtt_ping (struct mqtt_client *client)
	Ping the broker without locking/unlocking the mutex. More...

enum MQTTErrors	mqtt_disconnect (struct mqtt_client *client)
	Terminate the session with the MQTT broker. More...

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_NULL_CLIENT_ID)        \
    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)

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

◆ GENERATE_ENUM

#define GENERATE_ENUM ( ENUM ) ENUM,

A macro used to generate the enum MQTTErrors from __ALL_MQTT_ERRORS.

See also: __ALL_MQTT_ERRORS

◆ GENERATE_STRING

#define GENERATE_STRING ( STRING ) #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

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ __ALL_MQTT_ERRORS

◆ GENERATE_ENUM

◆ GENERATE_STRING

Function Documentation

◆ __mqtt_pack_str()

◆ __mqtt_pack_uint16()

◆ __mqtt_ping()

◆ __mqtt_unpack_uint16()