Zigbee Protocol Controller 1.6.0
mqtt_wrapper.h File Reference
#include <stdbool.h>
#include "sl_status.h"

Go to the source code of this file.

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
instancePointer to a client-instance.
hostMQTT-broker hostname/IP-address
portTCP port to connect to
keepaliveThe 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
instancePointer to a client-instance.
on_connectFunction-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
instancePointer to a client-instance to free.

◆ mqtt_wrapper_disconnect()

sl_status_t mqtt_wrapper_disconnect ( void *  instance)

Close the MQTT-broker connection.

Parameters
instancePointer 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
instancePointer to a client-instance
on_disconnectFunction-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
instancePointer to a client-instance.
timeoutMaximum 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
instancePointer 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
instancePointer 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
instancePointer 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
instancePointer to a client-instance
on_messageFunction-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
idThe client-ID to present to the MQTT-broker.
clean_sessionTrue if the session should be clean.
objA 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
instancePointer to a client-instance.
midMessage-ID. Can be set to NULL.
topicTopic name to publish to.
payloadlenSize of payload in bytes.
payloadPointer to payload to send.
qosQoS required for this message.
retainSet 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
instancePointer to a client-instance.
mqtt_client_idString of the Client ID
qosMQTT 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
instancePointer 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
instancePointer to a client-instance.
midMessage-ID. Can be set to NULL.
subTopic/pattern to subscribe to.
qosRequested 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
instancePointer to a client-instance.
pskthe pre-shared-key in hex format with no leading “0x”.
idthe identity of this client.
ciphersa 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
instancePointer to a client-instance.
cafilepath to a file containing the PEM encoded trusted CA certificate.
certfilepath to a file containing the PEM encoded certificate file for this client.
keyfilepath 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
subSubscription string to match topic against.
topicTopic to check
resultPointer 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
instancePointer to a client-instance.
midMessage-ID. Can be set to NULL.
subTopic/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.