Unify MQTT Client

MQTT client interface. More...

Modules
	MQTT Client
	This is the implementation of all of the logic for our MQTT client.
	MQTT Client ID
	Generates and provide a Client ID for the application/machine.

Macros
#define	MQTT_TOPIC_MAX_LENGTH   512
#define	MQTT_MESSAGE_MAX_LENGTH   512
#define	REGEX_NOT_STATE_OR_MQTT_CLIENT_TOPICS   "^(?!((ucl\\/by-unid\\/.*\\/State$)|(ucl\\/by-mqtt-client\\/.*))).*"
#define	REGEX_NOT_STATE_TOPIC   "^(?!ucl\\/by-unid\\/.*\\/State$).*"
#define	REGEX_ALL_TOPICS   "^.+"

Typedefs
typedef void(*	mqtt_message_callback_t) (const char *topic, const char *message, const size_t message_length)
	A callback type for pushing incoming messages. More...
typedef void(*	mqtt_message_callback_ex_t) (const char *topic, const char *message, const size_t message_length, void *user)
typedef void(*	mqtt_connection_callbacks_t) ()
	A callback type for a before disconnect and after connect. More...

Functions
sl_status_t	uic_mqtt_setup ()
int	uic_mqtt_teardown ()
void	uic_mqtt_publish (const char *topic, const char *message, const size_t message_length, bool retain)
	Add the message and topic to publisher queue system. More...
void	uic_mqtt_unretain (const char *prefix_pattern)
	Un-retain a previously retained message. More...
int	uic_mqtt_count_topics (const char *prefix_pattern)
	Count the number of topics published. More...
void	uic_mqtt_unretain_by_regex (const char *regex)
	Un-retain a previously retained message. More...
void	uic_mqtt_subscribe (const char *topic, mqtt_message_callback_t callback)
	Subscribe to a topic. More...
void	uic_mqtt_subscribe_ex (const char *topic, mqtt_message_callback_ex_t callback, void *user)
	Subscribe to a topic. More...
void	uic_mqtt_unsubscribe (const char *topic, mqtt_message_callback_t callback)
	Unsubscribe from a topic. More...
void	uic_mqtt_unsubscribe_ex (const char *topic, mqtt_message_callback_ex_t callback, void *user)
	Unsubscribe from a topic. More...
void	uic_mqtt_set_before_disconnect_callback (mqtt_connection_callbacks_t callback)
	Set a callback which will be executed before calling a disconnect. More...
void	uic_mqtt_set_after_connect_callback (mqtt_connection_callbacks_t callback)
	Set a callback which will be executed after having connected. More...
const char *	uic_mqtt_get_client_id ()
	Gets the MQTT Client ID in used by the MQTT Client. More...
bool	uic_mqtt_is_connected_to_broker ()
	Checks if we are currently connected to an MQTT Broker. More...

Detailed Description

MQTT client interface.

This component implement an mqtt client interface. The mqtt client features connection state management, with re-connect on disconnects and cashing of publish messages in case the a publish message cannot be delivered to the broker.

Other components can use the MQTT component to subscribe (uic_mqtt_subscribe) to MQTT topics and register callbacks when new messages arrives.

This api also features publishing messages(uic_mqtt_publish) and keeping track on which messages has been published with the retained flag such that they mey be un-retaind again if desired (uic_mqtt_unretain uic_mqtt_unretain_by_regex).

Macro Definition Documentation

MQTT_MESSAGE_MAX_LENGTH

#define MQTT_MESSAGE_MAX_LENGTH   512

MQTT_TOPIC_MAX_LENGTH

#define MQTT_TOPIC_MAX_LENGTH   512

REGEX_ALL_TOPICS

#define REGEX_ALL_TOPICS   "^.+"

REGEX_NOT_STATE_OR_MQTT_CLIENT_TOPICS

#define REGEX_NOT_STATE_OR_MQTT_CLIENT_TOPICS   "^(?!((ucl\\/by-unid\\/.*\\/State$)|(ucl\\/by-mqtt-client\\/.*))).*"

REGEX_NOT_STATE_TOPIC

#define REGEX_NOT_STATE_TOPIC   "^(?!ucl\\/by-unid\\/.*\\/State$).*"

Typedef Documentation

mqtt_connection_callbacks_t

typedef void(* mqtt_connection_callbacks_t) ()

A callback type for a before disconnect and after connect.

mqtt_message_callback_ex_t

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

mqtt_message_callback_t

typedef void(* mqtt_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.

Function Documentation

uic_mqtt_count_topics()

int uic_mqtt_count_topics

(

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

prefix_pattern

Returns

int

uic_mqtt_get_client_id()

const char * uic_mqtt_get_client_id

(

)

Gets the MQTT Client ID in used by the MQTT Client.

Returns

NULL if no Client ID is in use, else a C string containing the Client ID.

uic_mqtt_is_connected_to_broker()

bool uic_mqtt_is_connected_to_broker

(

)

Checks if we are currently connected to an MQTT Broker.

Returns

true if connected to a broker

uic_mqtt_publish()

void uic_mqtt_publish	(	const char *	topic,
		const char *	message,
		const size_t	message_length,
		bool	retain
	)

Add the message and topic to publisher queue system.

Parameters

topic	Represent the topic to publish to.
message	A message that will be published to a given topic. It shall have a zero-terminated character.
message_length	A size of the message in bytes.
retain	Describes if the broker has to retain or not the message.

uic_mqtt_set_after_connect_callback()

void uic_mqtt_set_after_connect_callback

(

mqtt_connection_callbacks_t

callback

)

Set a callback which will be executed after having connected.

Parameters

callback

A callback function to be executed after having connected.

uic_mqtt_set_before_disconnect_callback()

void uic_mqtt_set_before_disconnect_callback

(

mqtt_connection_callbacks_t

callback

)

Set a callback which will be executed before calling a disconnect.

Parameters

callback

A callback function to be executed before calling disconnect.

uic_mqtt_setup()

sl_status_t uic_mqtt_setup

(

)

Initialize the MQTT client instance.

Returns

true if the library is initialized, and created an MQTT client instance.

true if initialization was successful and client_instance was created.

uic_mqtt_subscribe()

void uic_mqtt_subscribe	(	const char *	topic,
		mqtt_message_callback_t	callback
	)

Subscribe to a topic.

Parameters

topic	Describes the subscription topic pattern.
callback	A callback function, that will be called when a message is received from the broker.

uic_mqtt_subscribe_ex()

void uic_mqtt_subscribe_ex	(	const char *	topic,
		mqtt_message_callback_ex_t	callback,
		void *	user
	)

Subscribe to a topic.

Parameters

topic	Describes the subscription topic pattern.
callback	A callback function, that will be called when a message is received from the broker.
user	A pointer value that will be passed to the callabck function when invoked

uic_mqtt_teardown()

int uic_mqtt_teardown

(

)

Tear-down the MQTT library and client instances.

Returns

success

uic_mqtt_unretain()

void uic_mqtt_unretain

(

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.

Example: If retained topics are ["a/b", "a/b/c", "b"] and prefix_pattern is "a", then the following topics will be unretained: ["a/b", "a/b/c"]

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

Parameters

prefix_pattern

prefix to un-retain

uic_mqtt_unretain_by_regex()

void uic_mqtt_unretain_by_regex

(

const char *

regex

)

Un-retain a previously retained message.

Any topic matches the regex pattern

Parameters

regex

regular expression

uic_mqtt_unsubscribe()

void uic_mqtt_unsubscribe	(	const char *	topic,
		mqtt_message_callback_t	callback
	)

Unsubscribe from a topic.

Parameters

topic	Describes the subscription pattern.
callback	A callback function corresponds to unsubscribe topic

uic_mqtt_unsubscribe_ex()

void uic_mqtt_unsubscribe_ex	(	const char *	topic,
		mqtt_message_callback_ex_t	callback,
		void *	user
	)

Unsubscribe from a topic.

Parameters

topic	Describes the subscription pattern.
callback	A callback function corresponds to unsubscribe topic
user	User pointer value to pass to the MQTT message callback