#include <stdbool.h>
#include "sl_status.h"

Classes
struct	mqtt_message

Functions
sl_status_t	mqtt_wrapper_lib_init ()
	Initialize the underlying MQTT-client library. More...

void *	mqtt_wrapper_new (const char id, bool clean_session, void obj)
	Initialize a new instance of the underlying client implementation. More...

sl_status_t	mqtt_wrapper_lib_cleanup ()
	Do a cleanup of the underlying client-library. More...

void	mqtt_wrapper_destroy (void *instance)
	Destroy (free) a client-instance. More...

int	mqtt_wrapper_socket (void *instance)
	Fetch the file-descriptor for the underlying network-socket. More...

sl_status_t	mqtt_wrapper_tls_set (void instance, const char cafile, const char certfile, const char keyfile)
	Configure the client for Certficate based TLS support. More...

sl_status_t	mqtt_wrapper_tls_psk_set (void instance, const char psk, const char id, const char ciphers)
	Configure the client for pre-shared-key based TLS support. More...

sl_status_t	mqtt_wrapper_connect (void instance, const char host, int port, int keepalive)
	Connect to an MQTT-broker. More...

sl_status_t	mqtt_wrapper_disconnect (void *instance)
	Close the MQTT-broker connection. More...

sl_status_t	mqtt_wrapper_loop (void *instance, int timeout)
	Run an iteration of the network-loop of the underlying client-library. More...

sl_status_t	mqtt_wrapper_loop_read (void *instance)
	Carry out read-operations on the network-socket connected to the MQTT-broker. More...

sl_status_t	mqtt_wrapper_loop_write (void *instance)
	Carry out write-opeartions on the network-socket connected to the MQTT-broker. More...

sl_status_t	mqtt_wrapper_loop_misc (void *instance)
	Carry out miscellaneous operations required as part of the nwtwork-loop (e.g. PINGs). More...

sl_status_t	mqtt_wrapper_set_will_message (void instance, const char mqtt_client_id, int qos)
	Configures the MQTT Will message using the Client ID. More...

sl_status_t	mqtt_wrapper_publish (void instance, int mid, const char topic, int payloadlen, const void payload, int qos, bool retain)
	Publish a message to a topic. More...

sl_status_t	mqtt_wrapper_subscribe (void instance, int mid, const char *sub, int qos)
	Subscribe to a topic. More...

sl_status_t	mqtt_wrapper_unsubscribe (void instance, int mid, const char *sub)
	Unsubscribe from a topic. More...

sl_status_t	mqtt_wrapper_topic_matches_sub (const char sub, const char topic, bool *result)
	Check whether a given topic matches a subscription-pattern. More...

void	mqtt_wrapper_connect_callback_set (void instance, void(on_connect)(void inst, void obj, int result_code))
	Set the connect callback. More...

void	mqtt_wrapper_disconnect_callback_set (void instance, void(on_disconnect)(void inst, void obj, int rc))
	Set the disconnect callback. More...

void	mqtt_wrapper_message_callback_set (void instance, void(on_message)(void inst, void obj, const struct mqtt_message *msg))
	Set the message callback. More...

Function Documentation

◆ mqtt_wrapper_connect()

sl_status_t mqtt_wrapper_connect	(	void *	instance,
		const char *	host,
		int	port,
		int	keepalive
	)

Connect to an MQTT-broker.

Parameters

instance	Pointer to a client-instance.
host	MQTT-broker hostname/IP-address
port	TCP port to connect to
keepalive	The keep-alive interval for this connection.

Returns: SL_STATUS_OK No error.; SL_STATUS_INVALID_PARAMETER Generic invalid argument or consequence of invalid argument.; SL_STATUS_ERRNO System error: errno is set and strerror can be used to fetch the error-message.

◆ mqtt_wrapper_connect_callback_set()

void mqtt_wrapper_connect_callback_set	(	void *	instance,
		void()(void inst, void *obj, int result_code)	on_connect
	)

Set the connect callback.

This is called when the broker sends a CONNACK message in response to a connection.

Parameters

instance	Pointer to a client-instance.
on_connect	Function-pointer to a well-formed callback function: void callback(void instance, void obj, int result_code)

Callback result codes

0 - success
1 - connection refused (unacceptable protocol version)
2 - connection refused (identifier rejected)
3 - connection refused (broker unavailable)
4-255 - reserved for future use

◆ mqtt_wrapper_destroy()

void mqtt_wrapper_destroy ( void * instance )

Destroy (free) a client-instance.

Parameters

instance Pointer to a client-instance to free.

◆ mqtt_wrapper_disconnect()

sl_status_t mqtt_wrapper_disconnect ( void * instance )

Close the MQTT-broker connection.

Parameters

instance Pointer to a client-instance.

Returns: SL_STATUS_OK No error.; SL_STATUS_INVALID_PARAMETER Generic invalid argument or consequence of invalid argument.; SL_STATUS_NET_MQTT_NO_CONN Not connected to a broker.

◆ mqtt_wrapper_disconnect_callback_set()

void mqtt_wrapper_disconnect_callback_set	(	void *	instance,
		void()(void inst, void *obj, int rc)	on_disconnect
	)

Set the disconnect callback.

This is called when the broker has received the DISCONNECT command and has disconnected the client.

Parameters

instance	Pointer to a client-instance
on_disconnect	Function-pointer to a well-formed callback function: void callback(void instance, void obj, int result_code)

Callback result codes

0 - Success, i.e. the client has called its disconnect function.
Any other value means that an unexpected disconnect has occurred.

◆ mqtt_wrapper_lib_cleanup()

sl_status_t mqtt_wrapper_lib_cleanup ( )

Do a cleanup of the underlying client-library.

Returns: SL_STATUS_OK always.

◆ mqtt_wrapper_lib_init()

sl_status_t mqtt_wrapper_lib_init ( )

Initialize the underlying MQTT-client library.

This function is not thread-safe.

Returns: SL_STATUS_OK always.

◆ mqtt_wrapper_loop()

sl_status_t mqtt_wrapper_loop	(	void *	instance,
		int	timeout
	)

Run an iteration of the network-loop of the underlying client-library.

Parameters

instance	Pointer to a client-instance.
timeout	Maximum number of milliseconds to wait on the underlying select() call.

Returns: SL_STATUS_OK No error.; SL_STATUS_INVALID_PARAMETER Generic invalid argument or consequence of invalid argument.; SL_STATUS_ALLOCATION_FAILED Generic allocation error.; SL_STATUS_NET_MQTT_NO_CONN Not connected to a broker.; SL_STATUS_NET_MQTT_LOST_CONN Connection to broker lost.; SL_STATUS_NET_MQTT_PROTOCOL Protocol error.; SL_STATUS_ERRNO System error: errno is set and strerror can be used to fetch the error-message.

◆ mqtt_wrapper_loop_misc()

sl_status_t mqtt_wrapper_loop_misc ( void * instance )

Carry out miscellaneous operations required as part of the nwtwork-loop (e.g. PINGs).

Parameters

instance Pointer to a client-instance.

Returns: SL_STATUS_OK No error.; SL_STATUS_INVALID_PARAMETER Generic invalid argument or consequence of invalid argument.; SL_STATUS_NET_MQTT_NO_CONN Not connected to a broker.

◆ mqtt_wrapper_loop_read()

sl_status_t mqtt_wrapper_loop_read ( void * instance )

Carry out read-operations on the network-socket connected to the MQTT-broker.

Parameters

instance Pointer to a client-instance.

Returns: SL_STATUS_OK No error.; SL_STATUS_INVALID_PARAMETER Generic invalid argument or consequence of invalid argument.; SL_STATUS_ALLOCATION_FAILED Generic allocation error.; SL_STATUS_NET_MQTT_NO_CONN Not connected to a broker.; SL_STATUS_NET_MQTT_LOST_CONN Connection to broker lost.; SL_STATUS_NET_MQTT_PROTOCOL Protocol error.; SL_STATUS_ERRNO System error: errno is set and strerror can be used to fetch the error-message.

◆ mqtt_wrapper_loop_write()

sl_status_t mqtt_wrapper_loop_write ( void * instance )

Carry out write-opeartions on the network-socket connected to the MQTT-broker.

Parameters

instance Pointer to a client-instance.

Returns: SL_STATUS_OK No error.; SL_STATUS_INVALID_PARAMETER Generic invalid argument or consequence of invalid argument.; SL_STATUS_ALLOCATION_FAILED Generic allocation error.; SL_STATUS_NET_MQTT_NO_CONN Not connected to a broker.; SL_STATUS_NET_MQTT_LOST_CONN Connection to broker lost.; SL_STATUS_NET_MQTT_PROTOCOL Protocol error.; SL_STATUS_ERRNO System error: errno is set and strerror can be used to fetch the error-message.

◆ mqtt_wrapper_message_callback_set()

void mqtt_wrapper_message_callback_set	(	void *	instance,
		void()(void inst, void obj, const struct mqtt_message msg)	on_message
	)

Set the message callback.

This is called every time a new (published) message is received from the broker.

Parameters

instance	Pointer to a client-instance
on_message	Function-pointer to a well-formed callback function: void callback(void instance, void obj, const struct mqtt_message *msg)

◆ mqtt_wrapper_new()

void * mqtt_wrapper_new	(	const char *	id,
		bool	clean_session,
		void *	obj
	)

Initialize a new instance of the underlying client implementation.

Parameters

id	The client-ID to present to the MQTT-broker.
clean_session	True if the session should be clean.
obj	A pointer to a user-object that will be passed along with callbacks.

Returns: A pointer to the client-instance.

◆ mqtt_wrapper_publish()

sl_status_t mqtt_wrapper_publish	(	void *	instance,
		int *	mid,
		const char *	topic,
		int	payloadlen,
		const void *	payload,
		int	qos,
		bool	retain
	)

Publish a message to a topic.

Parameters

instance	Pointer to a client-instance.
mid	Message-ID. Can be set to NULL.
topic	Topic name to publish to.
payloadlen	Size of payload in bytes.
payload	Pointer to payload to send.
qos	QoS required for this message.
retain	Set to true if message should be retained on the broker.

Returns: SL_STATUS_OK No error.; SL_STATUS_INVALID_PARAMETER Generic invalid argument or consequence of invalid argument.; SL_STATUS_ALLOCATION_FAILED Generic allocation error.; SL_STATUS_NET_MQTT_NO_CONN Not connected to a broker.; SL_STATUS_NET_MQTT_PROTOCOL Protocol error.; SL_STATUS_NET_MQTT_PAYLOAD_SIZE Payload size is too large.; SL_STATUS_NET_MQTT_MALFORMED_UTF8 Malformed UTF-8 string in the specified MQTT-topic.; SL_STATUS_NET_MQTT_QOS_NOT_SUPPORTED The requested QoS level is not supported by the broker.; SL_STATUS_NET_MQTT_OVERSIZE_PACKET Resulting packet will become larger than the broker supports.

◆ mqtt_wrapper_set_will_message()

sl_status_t mqtt_wrapper_set_will_message	(	void *	instance,
		const char *	mqtt_client_id,
		int	qos
	)

Configures the MQTT Will message using the Client ID.

Parameters

instance	Pointer to a client-instance.
mqtt_client_id	String of the Client ID
qos	MQTT QoS for the Will message.

Returns: SL_STATUS_OK if successful, any other codes in case of error.

◆ mqtt_wrapper_socket()

int mqtt_wrapper_socket ( void * instance )

Fetch the file-descriptor for the underlying network-socket.

Parameters

instance Pointer to a client-instance.

Returns: The file-descriptor.

◆ mqtt_wrapper_subscribe()

sl_status_t mqtt_wrapper_subscribe	(	void *	instance,
		int *	mid,
		const char *	sub,
		int	qos
	)

Subscribe to a topic.

Parameters

instance	Pointer to a client-instance.
mid	Message-ID. Can be set to NULL.
sub	Topic/pattern to subscribe to.
qos	Requested QoS for this subscription.

Returns: SL_STATUS_OK No error.; SL_STATUS_INVALID_PARAMETER Generic invalid argument or consequence of invalid argument.; SL_STATUS_ALLOCATION_FAILED Generic allocation error.; SL_STATUS_NET_MQTT_NO_CONN Not connected to a broker.; SL_STATUS_NET_MQTT_MALFORMED_UTF8 Malformed UTF-8 string in the specified MQTT-topic.; SL_STATUS_NET_MQTT_OVERSIZE_PACKET Resulting packet will become larger than the broker supports.

◆ mqtt_wrapper_tls_psk_set()

sl_status_t mqtt_wrapper_tls_psk_set	(	void *	instance,
		const char *	psk,
		const char *	id,
		const char *	ciphers
	)

Configure the client for pre-shared-key based TLS support.

Wrapper to mosquitto_tls_psk_set()

Parameters

instance	Pointer to a client-instance.
psk	the pre-shared-key in hex format with no leading “0x”.
id	the identity of this client.
ciphers	a string describing the PSK ciphers available for use. See the “openssl ciphers” tool for more information. If NULL, the default ciphers will be used.

Returns: SL_STATUS_OK No error.; SL_STATUS_INVALID_PARAMETER Generic invalid argument or consequence of invalid argument.; SL_STATUS_ERRNO System error: errno is set and strerror can be used to fetch the error-message.

◆ mqtt_wrapper_tls_set()

sl_status_t mqtt_wrapper_tls_set	(	void *	instance,
		const char *	cafile,
		const char *	certfile,
		const char *	keyfile
	)

Configure the client for Certficate based TLS support.

Wrapper to mosquitto_tls_set()

Parameters

instance	Pointer to a client-instance.
cafile	path to a file containing the PEM encoded trusted CA certificate.
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.

Returns: SL_STATUS_OK No error.; SL_STATUS_INVALID_PARAMETER Generic invalid argument or consequence of invalid argument.; SL_STATUS_ERRNO System error: errno is set and strerror can be used to fetch the error-message.

◆ mqtt_wrapper_topic_matches_sub()

sl_status_t mqtt_wrapper_topic_matches_sub	(	const char *	sub,
		const char *	topic,
		bool *	result
	)

Check whether a given topic matches a subscription-pattern.

Parameters

sub	Subscription string to match topic against.
topic	Topic to check
result	Pointer to a bool to hold the result.

Returns: SL_STATUS_OK No error.; SL_STATUS_INVALID_PARAMETER Generic invalid argument or consequence of invalid argument.; SL_STATUS_ALLOCATION_FAILED Generic allocation error.

◆ mqtt_wrapper_unsubscribe()

sl_status_t mqtt_wrapper_unsubscribe	(	void *	instance,
		int *	mid,
		const char *	sub
	)

Unsubscribe from a topic.

Parameters

instance	Pointer to a client-instance.
mid	Message-ID. Can be set to NULL.
sub	Topic/pattern to unsubscribe from.

Returns: SL_STATUS_OK No error.; SL_STATUS_INVALID_PARAMETER Generic invalid argument or consequence of invalid argument.; SL_STATUS_ALLOCATION_FAILED Generic allocation error.; SL_STATUS_NET_MQTT_NO_CONN Not connected to a broker.; SL_STATUS_NET_MQTT_MALFORMED_UTF8 Malformed UTF-8 string in the specified MQTT-topic.; SL_STATUS_NET_MQTT_OVERSIZE_PACKET Resulting packet will become larger than the broker supports.

Classes

Functions

Function Documentation

◆ mqtt_wrapper_connect()

◆ mqtt_wrapper_connect_callback_set()

◆ mqtt_wrapper_destroy()

◆ mqtt_wrapper_disconnect()

◆ mqtt_wrapper_disconnect_callback_set()

◆ mqtt_wrapper_lib_cleanup()

◆ mqtt_wrapper_lib_init()

◆ mqtt_wrapper_loop()

◆ mqtt_wrapper_loop_misc()

◆ mqtt_wrapper_loop_read()

◆ mqtt_wrapper_loop_write()

◆ mqtt_wrapper_message_callback_set()

◆ mqtt_wrapper_new()

◆ mqtt_wrapper_publish()

◆ mqtt_wrapper_set_will_message()

◆ mqtt_wrapper_socket()

◆ mqtt_wrapper_subscribe()

◆ mqtt_wrapper_tls_psk_set()

◆ mqtt_wrapper_tls_set()

◆ mqtt_wrapper_topic_matches_sub()

◆ mqtt_wrapper_unsubscribe()