Documentation of everything you need to know to use the MQTT-C client. More...

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

Functions
const char *	mqtt_error_str (enum MQTTErrors error)
	Returns an error message for error code, `error`. 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...

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_disconnect (struct mqtt_client *client)
	Terminate the session with the MQTT broker. More...

Detailed Description

Documentation of everything you need to know to use the MQTT-C client.

This module contains everything you need to know to use MQTT-C in your application. For usage examples see:

Note: MQTT-C can be used in both single-threaded and multi-threaded applications. All the functions in API are thread-safe.

Enumeration Type Documentation

◆ MQTTErrors

enum MQTTErrors

An enumeration of error codes. Error messages can be retrieved by calling mqtt_error_str.

See also: mqtt_error_str

Function Documentation

◆ mqtt_connect()

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.

Precondition: mqtt_init must have been called.

Parameters

[in,out]	client	The MQTT client.
[in]	client_id	The unique name identifying the client.
[in]	will_topic	The topic name of client's `will_message`. If no will message is desired set to `NULL`.
[in]	will_message	The application message (data) to be published in the event the client ungracefully disconnects. Set to `NULL` if `will_topic` is `NULL`.
[in]	will_message_size	The size of `will_message` in bytes.
[in]	user_name	The username to use when establishing the session with the MQTT broker. Set to `NULL` if a username is not required.
[in]	password	The password to use when establishing the session with the MQTT broker. Set to `NULL` if a password is not required.
[in]	connect_flags	Additional MQTTConnectFlags to use when establishing the connection. These flags are for forcing the session to start clean, `MQTT_CONNECT_CLEAN_SESSION`, the QOS level to publish the `will_message` with (provided `will_message` != `NULL`), MQTT_CONNECT_WILL_QOS_[0,1,2], and whether or not the broker should retain the `will_message`, MQTT_CONNECT_WILL_RETAIN.
[in]	keep_alive	The keep-alive time in seconds. A reasonable value for this is 400 [seconds].

Returns: MQTT_OK upon success, an MQTTErrors otherwise.

Examples:: bio_publisher.c, openssl_publisher.c, reconnect_subscriber.c, simple_publisher.c, and simple_subscriber.c.

◆ mqtt_disconnect()

enum MQTTErrors mqtt_disconnect ( struct mqtt_client * client )

Terminate the session with the MQTT broker.

Precondition: mqtt_connect must have been called.

Parameters

[in,out] client The MQTT client.

Note: To re-establish the session, mqtt_connect must be called.

Returns: MQTT_OK upon success, an MQTTErrors otherwise.

◆ mqtt_error_str()

const char* mqtt_error_str ( enum MQTTErrors error )

Returns an error message for error code, error.

Parameters

[in] error the error code.

Returns: The associated error message.

Examples:: bio_publisher.c, openssl_publisher.c, reconnect_subscriber.c, simple_publisher.c, and simple_subscriber.c.

◆ mqtt_init()

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()(void state, struct mqtt_response_publish publish)	publish_response_callback
	)

Initializes an MQTT client.This function must be called before any other API function calls.

Precondition: None.

Parameters

[out]	client	The MQTT client.
[in]	sockfd	The socket file descriptor (or equivalent socket handle, e.g. BIO pointer for OpenSSL sockets) connected to the MQTT broker.
[in]	sendbuf	A buffer that will be used for sending messages to the broker.
[in]	sendbufsz	The size of `sendbuf` in bytes.
[in]	recvbuf	A buffer that will be used for receiving messages from the broker.
[in]	recvbufsz	The size of `recvbuf` in bytes.
[in]	publish_response_callback	The callback to call whenever application messages are received from the broker.

Postcondition: mqtt_connect must be called.

Note: sockfd is a non-blocking TCP connection.; If sendbuf fills up completely during runtime a MQTT_ERROR_SEND_BUFFER_IS_FULL error will be set. Similarly if recvbuf is ever to small to receive a message from the broker an MQTT_ERROR_RECV_BUFFER_TOO_SMALL error will be set.; A pointer to mqtt_client::publish_response_callback_state is always passed as the state argument to publish_response_callback. Note that the second argument is the mqtt_response_publish that was received from the broker.

Attention: Only initialize an MQTT client once (i.e. don't call mqtt_init or mqtt_init_reconnect more than once per client).

Returns: MQTT_OK upon success, an MQTTErrors otherwise.

Examples:: bio_publisher.c, openssl_publisher.c, simple_publisher.c, and simple_subscriber.c.

◆ mqtt_init_reconnect()

void mqtt_init_reconnect	(	struct mqtt_client *	client,
		void()(struct mqtt_client client, void **state)	reconnect_callback,
		void *	reconnect_state,
		void()(void state, struct mqtt_response_publish publish)	publish_response_callback
	)

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

This is accomplished by calling the reconnect_callback whenever the client enters an error state. The job of the reconnect_callback is to: (1) perform error handling/logging, (2) clean up the old connection (i.e. close client->socketfd), (3) mqtt_reinit the client, and (4) reconfigure the MQTT session by calling mqtt_connect followed by other API calls such as mqtt_subscribe.

The first argument to the reconnect_callback is the client (which will be in an error state) and the second argument is a pointer to a void pointer where you can store some state information. Internally, MQTT-C calls the reconnect callback like so:

client->reconnect_callback(client, &client->reconnect_state)

Note that the reconnect_callback is also called to setup the initial session. After calling mqtt_init_reconnect the client will be in the error state MQTT_ERROR_INITIAL_RECONNECT.

Precondition: None.

Parameters

[in,out]	client	The MQTT client that will be initialized.
[in]	reconnect_callback	The callback that will be called to connect/reconnect the client to the broker and perform application level error handling.
[in]	reconnect_state	A pointer to some state data for your `reconnect_callback`. If your `reconnect_callback` does not require any state information set this to NULL. A pointer to the memory address where the client stores a copy of this pointer is passed as the second argumnet to `reconnect_callback`.
[in]	publish_response_callback	The callback to call whenever application messages are received from the broker.

Postcondition: Call reconnect_callback yourself, or call mqtt_sync (which will trigger the call to reconnect_callback).

Attention: Only initialize an MQTT client once (i.e. don't call mqtt_init or mqtt_init_reconnect more than once per client).

Examples:: reconnect_subscriber.c.

◆ mqtt_ping()

enum MQTTErrors mqtt_ping ( struct mqtt_client * client )

Ping the broker.

Precondition: mqtt_connect must have been called.

Parameters

[in,out] client The MQTT client.

Returns: MQTT_OK upon success, an MQTTErrors otherwise.

◆ mqtt_publish()

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.

Precondition: mqtt_connect must have been called.

Parameters

[in,out]	client	The MQTT client.
[in]	topic_name	The name of the topic.
[in]	application_message	The data to be published.
[in]	application_message_size	The size of `application_message` in bytes.
[in]	publish_flags	MQTTPublishFlags to be used, namely the QOS level to publish at (MQTT_PUBLISH_QOS_[0,1,2]) or whether or not the broker should retain the publish (MQTT_PUBLISH_RETAIN).

Returns: MQTT_OK upon success, an MQTTErrors otherwise.

Examples:: bio_publisher.c, openssl_publisher.c, and simple_publisher.c.

◆ mqtt_reinit()

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.

Precondition: This function must be called BEFORE mqtt_connect.

Parameters

[in,out]	client	The MQTT client.
[in]	socketfd	The new socket connected to the broker.
[in]	sendbuf	The buffer that will be used to buffer egress traffic to the broker.
[in]	sendbufsz	The size of `sendbuf` in bytes.
[in]	recvbuf	The buffer that will be used to buffer ingress traffic from the broker.
[in]	recvbufsz	The size of `recvbuf` in bytes.

Postcondition: Call mqtt_connect.

Attention: This function should be used in conjunction with clients that have been initialzed with mqtt_init_reconnect.

Examples:: reconnect_subscriber.c.

◆ mqtt_subscribe()

enum MQTTErrors mqtt_subscribe	(	struct mqtt_client *	client,
		const char *	topic_name,
		int	max_qos_level
	)

Subscribe to a topic.

Precondition: mqtt_connect must have been called.

Parameters

[in,out]	client	The MQTT client.
[in]	topic_name	The name of the topic to subscribe to.
[in]	max_qos_level	The maximum QOS level with which the broker can send application messages for this topic.

Returns: MQTT_OK upon success, an MQTTErrors otherwise.

Examples:: reconnect_subscriber.c, and simple_subscriber.c.

◆ mqtt_sync()

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.

Precondition: mqtt_init must have been called.

Parameters

[in,out] client The MQTT client.

Attention: It is the responsibility of the application programmer to call this function periodically. All functions in the API are thread-safe so it is perfectly reasonable to have a thread dedicated to calling this function every 200 ms or so. MQTT-C can be used in single threaded application though by simply calling this functino periodically inside your main thread. See simple_publisher.c and simple_subscriber.c for examples (specifically the client_refresher functions).

Returns: MQTT_OK upon success, an MQTTErrors otherwise.

Examples:: bio_publisher.c, openssl_publisher.c, reconnect_subscriber.c, simple_publisher.c, and simple_subscriber.c.

◆ mqtt_unsubscribe()

enum MQTTErrors mqtt_unsubscribe	(	struct mqtt_client *	client,
		const char *	topic_name
	)

Unsubscribe from a topic.

Precondition: mqtt_connect must have been called.

Parameters

[in,out]	client	The MQTT client.
[in]	topic_name	The name of the topic to unsubscribe from.

Returns: MQTT_OK upon success, an MQTTErrors otherwise.

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ MQTTErrors

Function Documentation

◆ mqtt_connect()

◆ mqtt_disconnect()

◆ mqtt_error_str()

◆ mqtt_init()

◆ mqtt_init_reconnect()

◆ mqtt_ping()

◆ mqtt_publish()

◆ mqtt_reinit()

◆ mqtt_subscribe()

◆ mqtt_sync()

◆ mqtt_unsubscribe()