MQTT Client

This is the implementation of all of the logic for our MQTT client. More...

Macros
#define	MQTT_CLIENT_POLL_TIMER_MILLISECONDS   2000
#define	MQTT_CLIENT_KEEP_ALIVE_INTERVAL_MILLISECONDS   60000
#define	MQTT_CLIENT_MINIMUM_RECONNECT_BACKOFF_MILLISECONDS   1000
#define	MQTT_CLIENT_MAXIMUM_RECONNECT_BACKOFF_MILLISECONDS   60000
#define	MQTT_CLIENT_QoS   0

Typedefs
typedef struct mqtt_client *	mqtt_client_t
	Type for internal consistency and to save typing. More...
typedef void(*	message_callback_t) (const char *topic, const char *message, const size_t message_length)
	A callback type for pushing incoming messages. More...
typedef void(*	message_callback_ex_t) (const char *topic, const char *message, const size_t message_length, void *user)
	A callback type for pushing incoming messages. More...
typedef void(*	mqtt_connection_callback_t) (mqtt_client_t instance, const int file_descriptor)
	A callback type for MQTT connection/disconnection events. More...
typedef void(*	mqtt_simple_callback_t) ()
	A void function type (void function()) to invoke when some events occurred. More...

Enumerations
enum	mqtt_event_t {   MQTT_EVENT_CONNECT , MQTT_EVENT_DISCONNECT , MQTT_EVENT_PUBLISH , MQTT_EVENT_SUBSCRIBE ,   MQTT_EVENT_UNSUBSCRIBE , MQTT_TRANSITION_DISCONNECTED , MQTT_TRANSITION_CONNECTING , MQTT_TRANSITION_CONNECTED }

Functions
	__attribute__ ((unused)) static const char *event_names[]
sl_status_t	mqtt_client_setup (mqtt_client_t instance)
	Initialize whatever resources the client needs. More...
sl_status_t	mqtt_client_teardown (mqtt_client_t instance)
	Close open connections and free up resources acquired by the client. More...
int	mqtt_client_file_descriptor (mqtt_client_t instance)
	Get the file-descriptor for the underlying MQTT TCP socket. More...
void	mqtt_client_poll (mqtt_client_t instance)
	Process any data that needs processed. More...
void	mqtt_client_disconnect (mqtt_client_t instance)
	Do a synchronous disconnect from the MQTT-broker. This can be used when a system is being shut down and the connection needs to be closed gracefully. More...
void	mqtt_client_event (mqtt_client_t instance, const int incoming_event)
	Push events to the mqtt_client. More...
void	mqtt_client_publish (mqtt_client_t instance, const char *topic, const char *message, const size_t message_length, bool retain)
	Publish a message to the MQTT-broker. More...
void	mqtt_client_unretain (mqtt_client_t instance, const char *prefix_pattern)
	Un-retain a previously retained message. More...
int	mqtt_client_count_topics (mqtt_client_t instance, const char *prefix_pattern)
	Count the number of topics published. More...
void	mqtt_client_unretain_by_regex (mqtt_client_t instance, const char *regex)
	Un-retain a previously retained message. More...
void	mqtt_client_subscribe (mqtt_client_t instance, const char *topic, message_callback_t callback)
	Subscribe to an MQTT-topic. More...
void	mqtt_client_subscribe_ex (mqtt_client_t instance, const char *topic, message_callback_ex_t callback, void *user)
	Subscribe to an MQTT-topic. More...
void	mqtt_client_unsubscribe (mqtt_client_t instance, const char *topic, message_callback_t callback)
	Unsubscribe from an MQTT-topic. More...
void	mqtt_client_unsubscribe_ex (mqtt_client_t instance, const char *topic, message_callback_ex_t callback, void *user)
	Unsubscribe from an MQTT-topic. More...
mqtt_client_t	mqtt_client_new (const char *hostname, const uint32_t port, const char *client_id, const char *cafile, const char *certfile, const char *keyfile, int(*event_sender)(const int event, void *procdata), void(*delayed_event_sender)(const int event, const unsigned long milliseconds), int(*event_counter)(const int event, void *procdata))
	Allocates a new mqtt_client instance. More...
void	mqtt_client_delete (mqtt_client_t instance)
	Deletes/frees the mqtt_client instance. More...
void	mqtt_client_on_connect_callback_set (mqtt_client_t instance, mqtt_connection_callback_t on_connect)
	Sets the callback to be invoked after an MQTT connection is established. More...
void	mqtt_client_on_disconnect_callback_set (mqtt_client_t instance, mqtt_connection_callback_t on_disconnect)
	Sets the callback to be invoked after an MQTT connection is disconnected. More...
void	mqtt_client_before_disconnect_callback_set (mqtt_client_t instance, mqtt_simple_callback_t before_disconnect)
	Sets a callback for calling before calling disconnect. More...
void	mqtt_client_after_connect_callback_set (mqtt_client_t instance, mqtt_simple_callback_t after_connect)
	Deletes/frees the mqtt_client instance. More...
const char *	mqtt_client_get_client_id (const mqtt_client_t client_instance)
	Returns the MQTT Client ID in use by the Client instance. More...
bool	mqtt_client_is_connected_to_broker (const mqtt_client_t instance)
	Checks if we are connected to the MQTT Broker. More...

Detailed Description

This is the implementation of all of the logic for our MQTT client.

The MQTT-Client is client-library-agnostic and depends on having the appropriate wrapper, e.g. mqtt_wrapper_mosquitto.cpp, to interface with the underlying client-library. All functionality is asynchronous where possible.

Macro Definition Documentation

MQTT_CLIENT_KEEP_ALIVE_INTERVAL_MILLISECONDS

#define MQTT_CLIENT_KEEP_ALIVE_INTERVAL_MILLISECONDS   60000

MQTT_CLIENT_MAXIMUM_RECONNECT_BACKOFF_MILLISECONDS

#define MQTT_CLIENT_MAXIMUM_RECONNECT_BACKOFF_MILLISECONDS   60000

MQTT_CLIENT_MINIMUM_RECONNECT_BACKOFF_MILLISECONDS

#define MQTT_CLIENT_MINIMUM_RECONNECT_BACKOFF_MILLISECONDS   1000

MQTT_CLIENT_POLL_TIMER_MILLISECONDS

#define MQTT_CLIENT_POLL_TIMER_MILLISECONDS   2000

MQTT_CLIENT_QoS

#define MQTT_CLIENT_QoS   0

Typedef Documentation

message_callback_ex_t

typedef void(* message_callback_ex_t) (const char *topic, const char *message, const size_t message_length, void *user)

A callback type for pushing incoming messages.

Parameters

topic	The topic the message came from
message	The message payload
message_length	The size of the message payload in bytes.
user	User defined pointer provided when subscribing

message_callback_t

typedef void(* message_callback_t) (const char *topic, const char *message, const size_t message_length)

A callback type for pushing incoming messages.

Parameters

topic	The topic the message came from
message	The message payload
message_length	The size of the message payload in bytes.

mqtt_client_t

typedef struct mqtt_client* mqtt_client_t

Type for internal consistency and to save typing.

mqtt_connection_callback_t

typedef void(* mqtt_connection_callback_t) (mqtt_client_t instance, const int file_descriptor)

A callback type for MQTT connection/disconnection events.

Parameters

instance	MQTT instance for the connection/disconnection
file_descriptor	File descriptor used for the MQTT connection

mqtt_simple_callback_t

typedef void(* mqtt_simple_callback_t) ()

A void function type (void function()) to invoke when some events occurred.

Enumeration Type Documentation

mqtt_event_t

enum mqtt_event_t

Internal events for the mqtt_client:

• MQTT_EVENT_*
  • Used for implementing the asynchronous architecture of the client. A function-call will enqueue some data, and then emit one of those events for later processing.
• MQTT_TRANSITION_*
  • Events for the FSM. The FSM should ONLY change states as a response to those events being emitted.

Enumerator
MQTT_EVENT_CONNECT	Request the client to connect to its broker.
MQTT_EVENT_DISCONNECT	Disconnect (from broker) request.
MQTT_EVENT_PUBLISH	Publish one queued up message.
MQTT_EVENT_SUBSCRIBE	Subscribe to one queued up topic.
MQTT_EVENT_UNSUBSCRIBE	Unsubscribe from one queued up topic.
MQTT_TRANSITION_DISCONNECTED	Request FSM to transition to the disconnected state.
MQTT_TRANSITION_CONNECTING	Request FSM to transition to the connecting state.
MQTT_TRANSITION_CONNECTED	Request FSM to transition to the connected state.

Function Documentation

__attribute__()

__attribute__

(

(unused)

)

const

mqtt_client_after_connect_callback_set()

void mqtt_client_after_connect_callback_set	(	mqtt_client_t	instance,
		mqtt_simple_callback_t	after_connect
	)

Deletes/frees the mqtt_client instance.

Parameters

instance	A pointer to an mqtt_client instance.
after_connect	function-pointer to the external-function after connect callback

mqtt_client_before_disconnect_callback_set()

void mqtt_client_before_disconnect_callback_set	(	mqtt_client_t	instance,
		mqtt_simple_callback_t	before_disconnect
	)

Sets a callback for calling before calling disconnect.

Parameters

instance	A pointer to an mqtt_client instance.
before_disconnect	A function-pointer to the external-function before disconnect callback

mqtt_client_count_topics()

int mqtt_client_count_topics	(	mqtt_client_t	instance,
		const char *	prefix_pattern
	)

Count the number of topics published.

This function counts the number of topics which has been published retained matching a pattern prefix.

Parameters

instance	Pointer to an mqtt_client instance.
prefix_pattern

Returns

int

mqtt_client_delete()

void mqtt_client_delete

(

mqtt_client_t

instance

)

Deletes/frees the mqtt_client instance.

Parameters

instance

A pointer to an mqtt_client instance.

mqtt_client_disconnect()

void mqtt_client_disconnect

(

mqtt_client_t

instance

)

Do a synchronous disconnect from the MQTT-broker. This can be used when a system is being shut down and the connection needs to be closed gracefully.

Parameters

instance

Pointer to an mqtt_client instance.

mqtt_client_event()

void mqtt_client_event	(	mqtt_client_t	instance,
		const int	incoming_event
	)

Push events to the mqtt_client.

This is the entry-point for all events. The mqtt_client proxies all events to its subsystems, including the FSM.

Parameters

instance	Pointer to an mqtt_client instance.
incoming_event	An event defined by mqtt_event_t

mqtt_client_file_descriptor()

int mqtt_client_file_descriptor

(

mqtt_client_t

instance

)

Get the file-descriptor for the underlying MQTT TCP socket.

Parameters

instance

Pointer to an mqtt_client instance.

Returns

The underlying TCP-socket file-descriptor.

mqtt_client_get_client_id()

const char * mqtt_client_get_client_id

(

const mqtt_client_t

client_instance

)

Returns the MQTT Client ID in use by the Client instance.

Parameters

client_instance

A pointer to an mqtt_client instance.

Returns

C String containing the Client ID. NULL if the instance is not in use.

mqtt_client_is_connected_to_broker()

bool mqtt_client_is_connected_to_broker

(

const mqtt_client_t

instance

)

Checks if we are connected to the MQTT Broker.

Parameters

instance

A pointer to an mqtt_client instance.

Returns

True if connected to the broker, false otherwise

mqtt_client_new()

mqtt_client_t mqtt_client_new	(	const char *	hostname,
		const uint32_t	port,
		const char *	client_id,
		const char *	cafile,
		const char *	certfile,
		const char *	keyfile,
		int(*)(const int event, void *procdata)	event_sender,
		void(*)(const int event, const unsigned long milliseconds)	delayed_event_sender,
		int(*)(const int event, void *procdata)	event_counter
	)

Allocates a new mqtt_client instance.

Parameters

hostname	The hostname/IP-address of the MQTT-broker this client should connect to.
port	The TCP-port the broker is listening on.
client_id	The client-id to use when identifying to the broker. This can be set to NULL.
cafile	path to a file containing the PEM encoded trusted CA certificate file.
certfile	path to a file containing the PEM encoded certificate file for this client.
keyfile	path to a file containing the PEM encoded private key for this client.
event_sender	A function-pointer to the external-function that the client shall use for emitting events.
delayed_event_sender	A function-pointer to an external-function that the client can use for emitting delayed events.
event_counter	A function-pointer to the external function that the client shall use for counting the number of events on the event-queue.

Returns

A pointer to the mqtt_client instance.

mqtt_client_on_connect_callback_set()

void mqtt_client_on_connect_callback_set	(	mqtt_client_t	instance,
		mqtt_connection_callback_t	on_connect
	)

Sets the callback to be invoked after an MQTT connection is established.

Parameters

instance	MQTT instance used for the connection
on_connect	Callback to invoke

mqtt_client_on_disconnect_callback_set()

void mqtt_client_on_disconnect_callback_set	(	mqtt_client_t	instance,
		mqtt_connection_callback_t	on_disconnect
	)

Sets the callback to be invoked after an MQTT connection is disconnected.

Parameters

instance	MQTT instance used for the connection
on_disconnect	Callback to invoke

mqtt_client_poll()

void mqtt_client_poll

(

mqtt_client_t

instance

)

Process any data that needs processed.

Also executes the network-loop of the underlying MQTT-client library, which means that this function should be called at least at the same interval as the configured keep-alive for the connection: MQTT_CLIENT_KEEP_ALIVE_INTERVAL_MILLISECONDS

Parameters

instance

Pointer to an mqtt_client instance.

mqtt_client_publish()

void mqtt_client_publish	(	mqtt_client_t	instance,
		const char *	topic,
		const char *	message,
		const size_t	message_length,
		bool	retain
	)

Publish a message to the MQTT-broker.

This, like (almost) all other functionality of the mqtt_client, is an asynchronous (non-blocking) call. The outgoing message is queued and then sent if/when the connection-state allows for it.

Parameters

instance	Pointer to an mqtt_client instance.
topic	The MQTT topic to publish to.
message	The message payload itself.
message_length	The size of the message.
retain	Set to true if the message shall be retained by the MQTT-broker.

mqtt_client_setup()

sl_status_t mqtt_client_setup

(

mqtt_client_t

instance

)

Initialize whatever resources the client needs.

Parameters

instance

Pointer to an mqtt_client instance.

Returns

true if initialization was successful. False otherwise.

mqtt_client_subscribe()

void mqtt_client_subscribe	(	mqtt_client_t	instance,
		const char *	topic,
		message_callback_t	callback
	)

Subscribe to an MQTT-topic.

This, like (almost) all other functionality of the mqtt_client, is an asynchronous (non-blocking) call. The subscription request is queued and then sent if/when the connection-state allows for it.

Parameters

instance	Pointer to an mqtt_client instance.
topic	The MQTT-topic name/pattern to subscribe to.
callback	Function-pointer to a callback-function that receives the incoming messages and has the message_callback_t function-signature.

mqtt_client_subscribe_ex()

void mqtt_client_subscribe_ex	(	mqtt_client_t	instance,
		const char *	topic,
		message_callback_ex_t	callback,
		void *	user
	)

Subscribe to an MQTT-topic.

This, like (almost) all other functionality of the mqtt_client, is an asynchronous (non-blocking) call. The subscription request is queued and then sent if/when the connection-state allows for it.

Parameters

instance	Pointer to an mqtt_client instance.
topic	The MQTT-topic name/pattern to subscribe to.
callback	Function-pointer to a callback-function that receives the incoming messages and has the message_callback_t function-signature.
user	User defined pointer which will be returned in the callback

mqtt_client_teardown()

sl_status_t mqtt_client_teardown

(

mqtt_client_t

instance

)

Close open connections and free up resources acquired by the client.

Parameters

instance

Pointer to an mqtt_client instance.

Returns

SL_STATUS_OK on success.

SL_STATUS_FAIL on failure.

mqtt_client_unretain()

void mqtt_client_unretain	(	mqtt_client_t	instance,
		const char *	prefix_pattern
	)

Un-retain a previously retained message.

This will send an empty retained message for all previously published retained topics which has the given prefix.

According to the mqtt specification it will cause the broker to delete the retained messages.

Parameters

instance	Pointer to an mqtt_client instance.
prefix_pattern	prefix to un-retain

mqtt_client_unretain_by_regex()

void mqtt_client_unretain_by_regex	(	mqtt_client_t	instance,
		const char *	regex
	)

Un-retain a previously retained message.

Any topic matches the regex pattern

Parameters

instance	Pointer to an mqtt_client instance.
regex	A regular expression to match topics against

mqtt_client_unsubscribe()

void mqtt_client_unsubscribe	(	mqtt_client_t	instance,
		const char *	topic,
		message_callback_t	callback
	)

Unsubscribe from an MQTT-topic.

This, like (almost) all other functionality of the mqtt_client, is an asynchronous (non-blocking) call. The unsubscription request is queued and then sent if/when the connection-state allows for it, with one caveat: The callback-registration happens immediately, but sending the unsubscription-command to the broker is asynchronous.

Parameters

instance	Pointer to an mqtt_client instance.
topic	The MQTT-topic name/pattern to unsubscribe from.
callback	Function-pointer to a callback-function that receives the incoming messages and has the message_callback_t function-signature.

mqtt_client_unsubscribe_ex()

void mqtt_client_unsubscribe_ex	(	mqtt_client_t	instance,
		const char *	topic,
		message_callback_ex_t	callback,
		void *	user
	)

Unsubscribe from an MQTT-topic.

This, like (almost) all other functionality of the mqtt_client, is an asynchronous (non-blocking) call. The unsubscription request is queued and then sent if/when the connection-state allows for it, with one caveat: The callback-registration happens immediately, but sending the unsubscription-command to the broker is asynchronous.

Parameters

instance	Pointer to an mqtt_client instance.
topic	The MQTT-topic name/pattern to unsubscribe from.
callback	Function-pointer to a callback-function that receives the incoming messages and has the message_callback_t function-signature.
user	Argument used when registering