diff --git a/lib/libpaho-mqtt/bin/paho_c_pub b/lib/libpaho-mqtt/bin/paho_c_pub
new file mode 100755
index 0000000..3b54bec
Binary files /dev/null and b/lib/libpaho-mqtt/bin/paho_c_pub differ
diff --git a/lib/libpaho-mqtt/bin/paho_c_sub b/lib/libpaho-mqtt/bin/paho_c_sub
new file mode 100755
index 0000000..bf6423a
Binary files /dev/null and b/lib/libpaho-mqtt/bin/paho_c_sub differ
diff --git a/lib/libpaho-mqtt/bin/paho_c_version b/lib/libpaho-mqtt/bin/paho_c_version
new file mode 100755
index 0000000..daa5114
Binary files /dev/null and b/lib/libpaho-mqtt/bin/paho_c_version differ
diff --git a/lib/libpaho-mqtt/bin/paho_cs_pub b/lib/libpaho-mqtt/bin/paho_cs_pub
new file mode 100755
index 0000000..dd5f9b4
Binary files /dev/null and b/lib/libpaho-mqtt/bin/paho_cs_pub differ
diff --git a/lib/libpaho-mqtt/bin/paho_cs_sub b/lib/libpaho-mqtt/bin/paho_cs_sub
new file mode 100755
index 0000000..ce085eb
Binary files /dev/null and b/lib/libpaho-mqtt/bin/paho_cs_sub differ
diff --git a/lib/libpaho-mqtt/include/MQTTAsync.h b/lib/libpaho-mqtt/include/MQTTAsync.h
new file mode 100644
index 0000000..e11af04
--- /dev/null
+++ b/lib/libpaho-mqtt/include/MQTTAsync.h
@@ -0,0 +1,2383 @@
+/*******************************************************************************
+ * Copyright (c) 2009, 2023 IBM Corp., Ian Craggs and others
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v2.0
+ * and Eclipse Distribution License v1.0 which accompany this distribution.
+ *
+ * The Eclipse Public License is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * Contributors:
+ * Ian Craggs - initial API and implementation
+ * Ian Craggs, Allan Stockdill-Mander - SSL connections
+ * Ian Craggs - multiple server connection support
+ * Ian Craggs - MQTT 3.1.1 support
+ * Ian Craggs - fix for bug 444103 - success/failure callbacks not invoked
+ * Ian Craggs - automatic reconnect and offline buffering (send while disconnected)
+ * Ian Craggs - binary will message
+ * Ian Craggs - binary password
+ * Ian Craggs - remove const on eyecatchers #168
+ * Ian Craggs - MQTT 5.0
+ *******************************************************************************/
+
+/********************************************************************/
+
+/**
+ * @cond MQTTAsync_main
+ * @mainpage Asynchronous MQTT client library for C (MQTTAsync)
+ *
+ * © Copyright 2009, 2023 IBM Corp., Ian Craggs and others
+ *
+ * @brief An Asynchronous MQTT client library for C.
+ *
+ * An MQTT client application connects to MQTT-capable servers.
+ * A typical client is responsible for collecting information from a telemetry
+ * device and publishing the information to the server. It can also subscribe
+ * to topics, receive messages, and use this information to control the
+ * telemetry device.
+ *
+ * MQTT clients implement the published MQTT v3 protocol. You can write your own
+ * API to the MQTT protocol using the programming language and platform of your
+ * choice. This can be time-consuming and error-prone.
+ *
+ * To simplify writing MQTT client applications, this library encapsulates
+ * the MQTT v3 protocol for you. Using this library enables a fully functional
+ * MQTT client application to be written in a few lines of code.
+ * The information presented here documents the API provided
+ * by the Asynchronous MQTT Client library for C.
+ *
+ * <b>Using the client</b><br>
+ * Applications that use the client library typically use a similar structure:
+ * <ul>
+ * <li>Create a client object</li>
+ * <li>Set the options to connect to an MQTT server</li>
+ * <li>Set up callback functions</li>
+ * <li>Connect the client to an MQTT server</li>
+ * <li>Subscribe to any topics the client needs to receive</li>
+ * <li>Repeat until finished:</li>
+ * <ul>
+ * <li>Publish any messages the client needs to</li>
+ * <li>Handle any incoming messages</li>
+ * </ul>
+ * <li>Disconnect the client</li>
+ * <li>Free any memory being used by the client</li>
+ * </ul>
+ * Some simple examples are shown here:
+ * <ul>
+ * <li>@ref publish</li>
+ * <li>@ref subscribe</li>
+ * </ul>
+ * Additional information about important concepts is provided here:
+ * <ul>
+ * <li>@ref async</li>
+ * <li>@ref wildcard</li>
+ * <li>@ref qos</li>
+ * <li>@ref tracing</li>
+ * <li>@ref auto_reconnect</li>
+ * <li>@ref offline_publish</li>
+ * </ul>
+ * @endcond
+ */
+
+/*
+/// @cond EXCLUDE
+*/
+#if !defined(MQTTASYNC_H)
+#define MQTTASYNC_H
+
+#if defined(__cplusplus)
+ extern "C" {
+#endif
+
+#include <stdio.h>
+/*
+/// @endcond
+*/
+
+#include "MQTTExportDeclarations.h"
+
+#include "MQTTProperties.h"
+#include "MQTTReasonCodes.h"
+#include "MQTTSubscribeOpts.h"
+#if !defined(NO_PERSISTENCE)
+#include "MQTTClientPersistence.h"
+#endif
+
+/**
+ * Return code: No error. Indicates successful completion of an MQTT client
+ * operation.
+ */
+#define MQTTASYNC_SUCCESS 0
+/**
+ * Return code: A generic error code indicating the failure of an MQTT client
+ * operation.
+ */
+#define MQTTASYNC_FAILURE -1
+
+/* error code -2 is MQTTAsync_PERSISTENCE_ERROR */
+
+#define MQTTASYNC_PERSISTENCE_ERROR -2
+
+/**
+ * Return code: The client is disconnected.
+ */
+#define MQTTASYNC_DISCONNECTED -3
+/**
+ * Return code: The maximum number of messages allowed to be simultaneously
+ * in-flight has been reached.
+ */
+#define MQTTASYNC_MAX_MESSAGES_INFLIGHT -4
+/**
+ * Return code: An invalid UTF-8 string has been detected.
+ */
+#define MQTTASYNC_BAD_UTF8_STRING -5
+/**
+ * Return code: A NULL parameter has been supplied when this is invalid.
+ */
+#define MQTTASYNC_NULL_PARAMETER -6
+/**
+ * Return code: The topic has been truncated (the topic string includes
+ * embedded NULL characters). String functions will not access the full topic.
+ * Use the topic length value to access the full topic.
+ */
+#define MQTTASYNC_TOPICNAME_TRUNCATED -7
+/**
+ * Return code: A structure parameter does not have the correct eyecatcher
+ * and version number.
+ */
+#define MQTTASYNC_BAD_STRUCTURE -8
+/**
+ * Return code: A qos parameter is not 0, 1 or 2
+ */
+#define MQTTASYNC_BAD_QOS -9
+/**
+ * Return code: All 65535 MQTT msgids are being used
+ */
+#define MQTTASYNC_NO_MORE_MSGIDS -10
+/**
+ * Return code: the request is being discarded when not complete
+ */
+#define MQTTASYNC_OPERATION_INCOMPLETE -11
+/**
+ * Return code: no more messages can be buffered
+ */
+#define MQTTASYNC_MAX_BUFFERED_MESSAGES -12
+/**
+ * Return code: Attempting SSL connection using non-SSL version of library
+ */
+#define MQTTASYNC_SSL_NOT_SUPPORTED -13
+/**
+ * Return code: protocol prefix in serverURI should be:
+ * @li @em tcp:// or @em mqtt:// - Insecure TCP
+ * @li @em ssl:// or @em mqtts:// - Encrypted SSL/TLS
+ * @li @em ws:// - Insecure websockets
+ * @li @em wss:// - Secure web sockets
+ *
+ * The TLS enabled prefixes (ssl, mqtts, wss) are only valid if the TLS
+ * version of the library is linked with.
+ */
+#define MQTTASYNC_BAD_PROTOCOL -14
+/**
+ * Return code: don't use options for another version of MQTT
+ */
+#define MQTTASYNC_BAD_MQTT_OPTION -15
+/**
+ * Return code: call not applicable to the client's version of MQTT
+ */
+#define MQTTASYNC_WRONG_MQTT_VERSION -16
+/**
+ * Return code: 0 length will topic
+ */
+#define MQTTASYNC_0_LEN_WILL_TOPIC -17
+/*
+ * Return code: connect or disconnect command ignored because there is already a connect or disconnect
+ * command at the head of the list waiting to be processed. Use the onSuccess/onFailure callbacks to wait
+ * for the previous connect or disconnect command to be complete.
+ */
+#define MQTTASYNC_COMMAND_IGNORED -18
+ /*
+ * Return code: maxBufferedMessages in the connect options must be >= 0
+ */
+ #define MQTTASYNC_MAX_BUFFERED -19
+
+/**
+ * Default MQTT version to connect with. Use 3.1.1 then fall back to 3.1
+ */
+#define MQTTVERSION_DEFAULT 0
+/**
+ * MQTT version to connect with: 3.1
+ */
+#define MQTTVERSION_3_1 3
+/**
+ * MQTT version to connect with: 3.1.1
+ */
+#define MQTTVERSION_3_1_1 4
+/**
+ * MQTT version to connect with: 5
+ */
+#define MQTTVERSION_5 5
+/**
+ * Bad return code from subscribe, as defined in the 3.1.1 specification
+ */
+#define MQTT_BAD_SUBSCRIBE 0x80
+
+
+/**
+ * Initialization options
+ */
+typedef struct
+{
+ /** The eyecatcher for this structure. Must be MQTG. */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0 */
+ int struct_version;
+ /** 1 = we do openssl init, 0 = leave it to the application */
+ int do_openssl_init;
+} MQTTAsync_init_options;
+
+#define MQTTAsync_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
+
+/**
+ * Global init of mqtt library. Call once on program start to set global behaviour.
+ * handle_openssl_init - if mqtt library should handle openssl init (1) or rely on the caller to init it before using mqtt (0)
+ */
+LIBMQTT_API void MQTTAsync_global_init(MQTTAsync_init_options* inits);
+
+/**
+ * A handle representing an MQTT client. A valid client handle is available
+ * following a successful call to MQTTAsync_create().
+ */
+typedef void* MQTTAsync;
+/**
+ * A value representing an MQTT message. A token is returned to the
+ * client application when a message is published. The token can then be used to
+ * check that the message was successfully delivered to its destination (see
+ * MQTTAsync_publish(),
+ * MQTTAsync_publishMessage(),
+ * MQTTAsync_deliveryComplete(), and
+ * MQTTAsync_getPendingTokens()).
+ */
+typedef int MQTTAsync_token;
+
+/**
+ * A structure representing the payload and attributes of an MQTT message. The
+ * message topic is not part of this structure (see MQTTAsync_publishMessage(),
+ * MQTTAsync_publish(), MQTTAsync_receive(), MQTTAsync_freeMessage()
+ * and MQTTAsync_messageArrived()).
+ */
+typedef struct
+{
+ /** The eyecatcher for this structure. must be MQTM. */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0 or 1.
+ * 0 indicates no message properties */
+ int struct_version;
+ /** The length of the MQTT message payload in bytes. */
+ int payloadlen;
+ /** A pointer to the payload of the MQTT message. */
+ void* payload;
+ /**
+ * The quality of service (QoS) assigned to the message.
+ * There are three levels of QoS:
+ * <DL>
+ * <DT><B>QoS0</B></DT>
+ * <DD>Fire and forget - the message may not be delivered</DD>
+ * <DT><B>QoS1</B></DT>
+ * <DD>At least once - the message will be delivered, but may be
+ * delivered more than once in some circumstances.</DD>
+ * <DT><B>QoS2</B></DT>
+ * <DD>Once and one only - the message will be delivered exactly once.</DD>
+ * </DL>
+ */
+ int qos;
+ /**
+ * The retained flag serves two purposes depending on whether the message
+ * it is associated with is being published or received.
+ *
+ * <b>retained = true</b><br>
+ * For messages being published, a true setting indicates that the MQTT
+ * server should retain a copy of the message. The message will then be
+ * transmitted to new subscribers to a topic that matches the message topic.
+ * For subscribers registering a new subscription, the flag being true
+ * indicates that the received message is not a new one, but one that has
+ * been retained by the MQTT server.
+ *
+ * <b>retained = false</b> <br>
+ * For publishers, this indicates that this message should not be retained
+ * by the MQTT server. For subscribers, a false setting indicates this is
+ * a normal message, received as a result of it being published to the
+ * server.
+ */
+ int retained;
+ /**
+ * The dup flag indicates whether or not this message is a duplicate.
+ * It is only meaningful when receiving QoS1 messages. When true, the
+ * client application should take appropriate action to deal with the
+ * duplicate message. This is an output parameter only.
+ */
+ int dup;
+ /** The message identifier is reserved for internal use by the
+ * MQTT client and server. It is an output parameter only - writing
+ * to it will serve no purpose. It contains the MQTT message id of
+ * an incoming publish message.
+ */
+ int msgid;
+ /**
+ * The MQTT V5 properties associated with the message.
+ */
+ MQTTProperties properties;
+} MQTTAsync_message;
+
+#define MQTTAsync_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer }
+
+/**
+ * This is a callback function. The client application
+ * must provide an implementation of this function to enable asynchronous
+ * receipt of messages. The function is registered with the client library by
+ * passing it as an argument to MQTTAsync_setCallbacks(). It is
+ * called by the client library when a new message that matches a client
+ * subscription has been received from the server. This function is executed on
+ * a separate thread to the one on which the client application is running.
+ *
+ * <b>Note:</b> Neither MQTTAsync_create() nor MQTTAsync_destroy() should be
+ * called within this callback.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * MQTTAsync_setCallbacks(), which contains any application-specific context.
+ * @param topicName The topic associated with the received message.
+ * @param topicLen The length of the topic if there are one
+ * more NULL characters embedded in <i>topicName</i>, otherwise <i>topicLen</i>
+ * is 0. If <i>topicLen</i> is 0, the value returned by <i>strlen(topicName)</i>
+ * can be trusted. If <i>topicLen</i> is greater than 0, the full topic name
+ * can be retrieved by accessing <i>topicName</i> as a byte array of length
+ * <i>topicLen</i>.
+ * @param message The MQTTAsync_message structure for the received message.
+ * This structure contains the message payload and attributes.
+ * @return This function must return 0 or 1 indicating whether or not
+ * the message has been safely received by the client application. <br>
+ * Returning 1 indicates that the message has been successfully handled.
+ * To free the message storage, ::MQTTAsync_freeMessage must be called.
+ * To free the topic name storage, ::MQTTAsync_free must be called.<br>
+ * Returning 0 indicates that there was a problem. In this
+ * case, the client library will reinvoke MQTTAsync_messageArrived() to
+ * attempt to deliver the message to the application again.
+ * Do not free the message and topic storage when returning 0, otherwise
+ * the redelivery will fail.
+ */
+typedef int MQTTAsync_messageArrived(void* context, char* topicName, int topicLen, MQTTAsync_message* message);
+
+/**
+ * This is a callback function. The client application
+ * must provide an implementation of this function to enable asynchronous
+ * notification of delivery of messages to the server. The function is
+ * registered with the client library by passing it as an argument to MQTTAsync_setCallbacks().
+ * It is called by the client library after the client application has
+ * published a message to the server. It indicates that the necessary
+ * handshaking and acknowledgements for the requested quality of service (see
+ * MQTTAsync_message.qos) have been completed. This function is executed on a
+ * separate thread to the one on which the client application is running.
+ *
+ * <b>Note:</b> Neither MQTTAsync_create() nor MQTTAsync_destroy() should be
+ * called within this callback.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * MQTTAsync_setCallbacks(), which contains any application-specific context.
+ * @param token The ::MQTTAsync_token associated with
+ * the published message. Applications can check that all messages have been
+ * correctly published by matching the tokens returned from calls to
+ * MQTTAsync_send() and MQTTAsync_sendMessage() with the tokens passed
+ * to this callback.
+ */
+typedef void MQTTAsync_deliveryComplete(void* context, MQTTAsync_token token);
+
+/**
+ * This is a callback function. The client application
+ * must provide an implementation of this function to enable asynchronous
+ * notification of the loss of connection to the server. The function is
+ * registered with the client library by passing it as an argument to
+ * MQTTAsync_setCallbacks(). It is called by the client library if the client
+ * loses its connection to the server. The client application must take
+ * appropriate action, such as trying to reconnect or reporting the problem.
+ * This function is executed on a separate thread to the one on which the
+ * client application is running.
+ *
+ * <b>Note:</b> Neither MQTTAsync_create() nor MQTTAsync_destroy() should be
+ * called within this callback.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * MQTTAsync_setCallbacks(), which contains any application-specific context.
+ * @param cause The reason for the disconnection.
+ * Currently, <i>cause</i> is always set to NULL.
+ */
+typedef void MQTTAsync_connectionLost(void* context, char* cause);
+
+
+/**
+ * This is a callback function, which will be called when the client
+ * library successfully connects. This is superfluous when the connection
+ * is made in response to a MQTTAsync_connect call, because the onSuccess
+ * callback can be used. It is intended for use when automatic reconnect
+ * is enabled, so that when a reconnection attempt succeeds in the background,
+ * the application is notified and can take any required actions.
+ *
+ * <b>Note:</b> Neither MQTTAsync_create() nor MQTTAsync_destroy() should be
+ * called within this callback.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * MQTTAsync_setCallbacks(), which contains any application-specific context.
+ * @param cause The reason for the disconnection.
+ * Currently, <i>cause</i> is always set to NULL.
+ */
+typedef void MQTTAsync_connected(void* context, char* cause);
+
+/**
+ * This is a callback function, which will be called when the client
+ * library receives a disconnect packet from the server. This applies to MQTT V5 and above only.
+ *
+ * <b>Note:</b> Neither MQTTAsync_create() nor MQTTAsync_destroy() should be
+ * called within this callback.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * MQTTAsync_setCallbacks(), which contains any application-specific context.
+ * @param properties the properties in the disconnect packet.
+ * @param properties the reason code from the disconnect packet
+ * Currently, <i>cause</i> is always set to NULL.
+ */
+typedef void MQTTAsync_disconnected(void* context, MQTTProperties* properties,
+ enum MQTTReasonCodes reasonCode);
+
+/**
+ * Sets the MQTTAsync_disconnected() callback function for a client.
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ *
+ * <b>Note:</b> Neither MQTTAsync_create() nor MQTTAsync_destroy() should be
+ * called within this callback.
+ * @param context A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to each of the callback functions to
+ * provide access to the context information in the callback.
+ * @param co A pointer to an MQTTAsync_connected() callback
+ * function. NULL removes the callback setting.
+ * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set,
+ * ::MQTTASYNC_FAILURE if an error occurred.
+ */
+LIBMQTT_API int MQTTAsync_setDisconnected(MQTTAsync handle, void* context, MQTTAsync_disconnected* co);
+
+/** The connect options that can be updated before an automatic reconnect. */
+typedef struct
+{
+ /** The eyecatcher for this structure. Will be MQCD. */
+ char struct_id[4];
+ /** The version number of this structure. Will be 0 */
+ int struct_version;
+ /**
+ * MQTT servers that support the MQTT v3.1 protocol provide authentication
+ * and authorisation by user name and password. This is the user name parameter.
+ * Set data to NULL to remove. To change, allocate new
+ * storage with ::MQTTAsync_allocate - this will then be free later by the library.
+ */
+ const char* username;
+ /**
+ * The password parameter of the MQTT authentication.
+ * Set data to NULL to remove. To change, allocate new
+ * storage with ::MQTTAsync_allocate - this will then be free later by the library.
+ */
+ struct {
+ int len; /**< binary password length */
+ const void* data; /**< binary password data */
+ } binarypwd;
+} MQTTAsync_connectData;
+
+#define MQTTAsync_connectData_initializer {{'M', 'Q', 'C', 'D'}, 0, NULL, {0, NULL}}
+
+/**
+ * This is a callback function which will allow the client application to update the
+ * connection data.
+ * @param data The connection data which can be modified by the application.
+ * @return Return a non-zero value to update the connect data, zero to keep the same data.
+ */
+typedef int MQTTAsync_updateConnectOptions(void* context, MQTTAsync_connectData* data);
+
+/**
+ * Sets the MQTTAsync_updateConnectOptions() callback function for a client.
+ * @param handle A valid client handle from a successful call to MQTTAsync_create().
+ * @param context A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to each of the callback functions to
+ * provide access to the context information in the callback.
+ * @param co A pointer to an MQTTAsync_updateConnectOptions() callback
+ * function. NULL removes the callback setting.
+ */
+LIBMQTT_API int MQTTAsync_setUpdateConnectOptions(MQTTAsync handle, void* context, MQTTAsync_updateConnectOptions* co);
+
+/**
+ * Sets the MQTTPersistence_beforeWrite() callback function for a client.
+ * @param handle A valid client handle from a successful call to MQTTAsync_create().
+ * @param context A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to the callback function to
+ * provide access to the context information in the callback.
+ * @param co A pointer to an MQTTPersistence_beforeWrite() callback
+ * function. NULL removes the callback setting.
+ */
+LIBMQTT_API int MQTTAsync_setBeforePersistenceWrite(MQTTAsync handle, void* context, MQTTPersistence_beforeWrite* co);
+
+
+/**
+ * Sets the MQTTPersistence_afterRead() callback function for a client.
+ * @param handle A valid client handle from a successful call to MQTTAsync_create().
+ * @param context A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to the callback function to
+ * provide access to the context information in the callback.
+ * @param co A pointer to an MQTTPersistence_beforeWrite() callback
+ * function. NULL removes the callback setting.
+ */
+LIBMQTT_API int MQTTAsync_setAfterPersistenceRead(MQTTAsync handle, void* context, MQTTPersistence_afterRead* co);
+
+
+/** The data returned on completion of an unsuccessful API call in the response callback onFailure. */
+typedef struct
+{
+ /** A token identifying the failed request. */
+ MQTTAsync_token token;
+ /** A numeric code identifying the error. */
+ int code;
+ /** Optional text explaining the error. Can be NULL. */
+ const char *message;
+} MQTTAsync_failureData;
+
+
+/** The data returned on completion of an unsuccessful API call in the response callback onFailure. */
+typedef struct
+{
+ /** The eyecatcher for this structure. Will be MQFD. */
+ char struct_id[4];
+ /** The version number of this structure. Will be 0 */
+ int struct_version;
+ /** A token identifying the failed request. */
+ MQTTAsync_token token;
+ /** The MQTT reason code returned. */
+ enum MQTTReasonCodes reasonCode;
+ /** The MQTT properties on the ack, if any. */
+ MQTTProperties properties;
+ /** A numeric code identifying the MQTT client library error. */
+ int code;
+ /** Optional further text explaining the error. Can be NULL. */
+ const char *message;
+ /** Packet type on which the failure occurred - used for publish QoS 1/2 exchanges*/
+ int packet_type;
+} MQTTAsync_failureData5;
+
+#define MQTTAsync_failureData5_initializer {{'M', 'Q', 'F', 'D'}, 0, 0, MQTTREASONCODE_SUCCESS, MQTTProperties_initializer, 0, NULL, 0}
+
+/** The data returned on completion of a successful API call in the response callback onSuccess. */
+typedef struct
+{
+ /** A token identifying the successful request. Can be used to refer to the request later. */
+ MQTTAsync_token token;
+ /** A union of the different values that can be returned for subscribe, unsubscribe and publish. */
+ union
+ {
+ /** For subscribe, the granted QoS of the subscription returned by the server.
+ * Also for subscribeMany, if only 1 subscription was requested. */
+ int qos;
+ /** For subscribeMany, if more than one subscription was requested,
+ * the list of granted QoSs of the subscriptions returned by the server. */
+ int* qosList;
+ /** For publish, the message being sent to the server. */
+ struct
+ {
+ MQTTAsync_message message; /**< the message being sent to the server */
+ char* destinationName; /**< the topic destination for the message */
+ } pub;
+ /* For connect, the server connected to, MQTT version used, and sessionPresent flag */
+ struct
+ {
+ char* serverURI; /**< the connection string of the server */
+ int MQTTVersion; /**< the version of MQTT being used */
+ int sessionPresent; /**< the session present flag returned from the server */
+ } connect;
+ } alt;
+} MQTTAsync_successData;
+
+
+/** The data returned on completion of a successful API call in the response callback onSuccess. */
+typedef struct
+{
+ char struct_id[4]; /**< The eyecatcher for this structure. Will be MQSD. */
+ int struct_version; /**< The version number of this structure. Will be 0 */
+ /** A token identifying the successful request. Can be used to refer to the request later. */
+ MQTTAsync_token token;
+ enum MQTTReasonCodes reasonCode; /**< MQTT V5 reason code returned */
+ MQTTProperties properties; /**< MQTT V5 properties returned, if any */
+ /** A union of the different values that can be returned for subscribe, unsubscribe and publish. */
+ union
+ {
+ /** For subscribeMany, the list of reasonCodes returned by the server. */
+ struct
+ {
+ int reasonCodeCount; /**< the number of reason codes in the reasonCodes array */
+ enum MQTTReasonCodes* reasonCodes; /**< an array of reasonCodes */
+ } sub;
+ /** For publish, the message being sent to the server. */
+ struct
+ {
+ MQTTAsync_message message; /**< the message being sent to the server */
+ char* destinationName; /**< the topic destination for the message */
+ } pub;
+ /* For connect, the server connected to, MQTT version used, and sessionPresent flag */
+ struct
+ {
+ char* serverURI; /**< the connection string of the server */
+ int MQTTVersion; /**< the version of MQTT being used */
+ int sessionPresent; /**< the session present flag returned from the server */
+ } connect;
+ /** For unsubscribeMany, the list of reasonCodes returned by the server. */
+ struct
+ {
+ int reasonCodeCount; /**< the number of reason codes in the reasonCodes array */
+ enum MQTTReasonCodes* reasonCodes; /**< an array of reasonCodes */
+ } unsub;
+ } alt;
+} MQTTAsync_successData5;
+
+#define MQTTAsync_successData5_initializer {{'M', 'Q', 'S', 'D'}, 0, 0, MQTTREASONCODE_SUCCESS, MQTTProperties_initializer, {.sub={0,0}}}
+
+/**
+ * This is a callback function. The client application
+ * must provide an implementation of this function to enable asynchronous
+ * notification of the successful completion of an API call. The function is
+ * registered with the client library by passing it as an argument in
+ * ::MQTTAsync_responseOptions.
+ *
+ * <b>Note:</b> Neither MQTTAsync_create() nor MQTTAsync_destroy() should be
+ * called within this callback.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * ::MQTTAsync_responseOptions, which contains any application-specific context.
+ * @param response Any success data associated with the API completion.
+ */
+typedef void MQTTAsync_onSuccess(void* context, MQTTAsync_successData* response);
+
+/**
+ * This is a callback function, the MQTT V5 version of ::MQTTAsync_onSuccess.
+ * The client application
+ * must provide an implementation of this function to enable asynchronous
+ * notification of the successful completion of an API call. The function is
+ * registered with the client library by passing it as an argument in
+ * ::MQTTAsync_responseOptions.
+ *
+ * <b>Note:</b> Neither MQTTAsync_create() nor MQTTAsync_destroy() should be
+ * called within this callback.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * ::MQTTAsync_responseOptions, which contains any application-specific context.
+ * @param response Any success data associated with the API completion.
+ */
+typedef void MQTTAsync_onSuccess5(void* context, MQTTAsync_successData5* response);
+
+/**
+ * This is a callback function. The client application
+ * must provide an implementation of this function to enable asynchronous
+ * notification of the unsuccessful completion of an API call. The function is
+ * registered with the client library by passing it as an argument in
+ * ::MQTTAsync_responseOptions.
+ *
+ * <b>Note:</b> Neither MQTTAsync_create() nor MQTTAsync_destroy() should be
+ * called within this callback.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * ::MQTTAsync_responseOptions, which contains any application-specific context.
+ * @param response Failure data associated with the API completion.
+ */
+typedef void MQTTAsync_onFailure(void* context, MQTTAsync_failureData* response);
+
+/**
+ * This is a callback function, the MQTT V5 version of ::MQTTAsync_onFailure.
+ * The application must provide an implementation of this function to enable asynchronous
+ * notification of the unsuccessful completion of an API call. The function is
+ * registered with the client library by passing it as an argument in
+ * ::MQTTAsync_responseOptions.
+ *
+ * <b>Note:</b> Neither MQTTAsync_create() nor MQTTAsync_destroy() should be
+ * called within this callback.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * ::MQTTAsync_responseOptions, which contains any application-specific context.
+ * @param response Failure data associated with the API completion.
+ */
+typedef void MQTTAsync_onFailure5(void* context, MQTTAsync_failureData5* response);
+
+/** Structure to define call options. For MQTT 5.0 there is input data as well as that
+ * describing the response method. So there is now also a synonym ::MQTTAsync_callOptions
+ * to better reflect the use. This responseOptions name is kept for backward
+ * compatibility.
+ */
+typedef struct MQTTAsync_responseOptions
+{
+ /** The eyecatcher for this structure. Must be MQTR */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0 or 1
+ * if 0, no MQTTV5 options */
+ int struct_version;
+ /**
+ * A pointer to a callback function to be called if the API call successfully
+ * completes. Can be set to NULL, in which case no indication of successful
+ * completion will be received.
+ */
+ MQTTAsync_onSuccess* onSuccess;
+ /**
+ * A pointer to a callback function to be called if the API call fails.
+ * Can be set to NULL, in which case no indication of unsuccessful
+ * completion will be received.
+ */
+ MQTTAsync_onFailure* onFailure;
+ /**
+ * A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to success or failure callback functions to
+ * provide access to the context information in the callback.
+ */
+ void* context;
+ /**
+ * A token is returned from the call. It can be used to track
+ * the state of this request, both in the callbacks and in future calls
+ * such as ::MQTTAsync_waitForCompletion. This is output only - any
+ * change by the application will be ignored.
+ */
+ MQTTAsync_token token;
+ /**
+ * A pointer to a callback function to be called if the API call successfully
+ * completes. Can be set to NULL, in which case no indication of successful
+ * completion will be received.
+ */
+ MQTTAsync_onSuccess5* onSuccess5;
+ /**
+ * A pointer to a callback function to be called if the API call successfully
+ * completes. Can be set to NULL, in which case no indication of successful
+ * completion will be received.
+ */
+ MQTTAsync_onFailure5* onFailure5;
+ /**
+ * MQTT V5 input properties
+ */
+ MQTTProperties properties;
+ /*
+ * MQTT V5 subscribe options, when used with subscribe only.
+ */
+ MQTTSubscribe_options subscribeOptions;
+ /*
+ * MQTT V5 subscribe option count, when used with subscribeMany only.
+ * The number of entries in the subscribe_options_list array.
+ */
+ int subscribeOptionsCount;
+ /*
+ * MQTT V5 subscribe option array, when used with subscribeMany only.
+ */
+ MQTTSubscribe_options* subscribeOptionsList;
+} MQTTAsync_responseOptions;
+
+#define MQTTAsync_responseOptions_initializer { {'M', 'Q', 'T', 'R'}, 1, NULL, NULL, 0, 0, NULL, NULL, MQTTProperties_initializer, MQTTSubscribe_options_initializer, 0, NULL}
+
+/** A synonym for responseOptions to better reflect its usage since MQTT 5.0 */
+typedef struct MQTTAsync_responseOptions MQTTAsync_callOptions;
+#define MQTTAsync_callOptions_initializer MQTTAsync_responseOptions_initializer
+
+/**
+ * This function sets the global callback functions for a specific client.
+ * If your client application doesn't use a particular callback, set the
+ * relevant parameter to NULL. Any necessary message acknowledgements and
+ * status communications are handled in the background without any intervention
+ * from the client application. If you do not set a messageArrived callback
+ * function, you will not be notified of the receipt of any messages as a
+ * result of a subscription.
+ *
+ * <b>Note:</b> The MQTT client must be disconnected when this function is
+ * called.
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param context A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to each of the callback functions to
+ * provide access to the context information in the callback.
+ * @param cl A pointer to an MQTTAsync_connectionLost() callback
+ * function. You can set this to NULL if your application doesn't handle
+ * disconnections.
+ * @param ma A pointer to an MQTTAsync_messageArrived() callback
+ * function. If this callback is not set, an error will be returned.
+ * You must set this callback because otherwise there would be
+ * no way to deliver any incoming messages.
+ * @param dc A pointer to an MQTTAsync_deliveryComplete() callback
+ * function. You can set this to NULL if you do not want to check
+ * for successful delivery.
+ * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set,
+ * ::MQTTASYNC_FAILURE if an error occurred.
+ */
+LIBMQTT_API int MQTTAsync_setCallbacks(MQTTAsync handle, void* context, MQTTAsync_connectionLost* cl,
+ MQTTAsync_messageArrived* ma, MQTTAsync_deliveryComplete* dc);
+
+/**
+ * This function sets the callback function for a connection lost event for
+ * a specific client. Any necessary message acknowledgements and status
+ * communications are handled in the background without any intervention
+ * from the client application.
+ *
+ * <b>Note:</b> The MQTT client must be disconnected when this function is
+ * called.
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param context A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed the callback functions to provide
+ * access to the context information in the callback.
+ * @param cl A pointer to an MQTTAsync_connectionLost() callback
+ * function. You can set this to NULL if your application doesn't handle
+ * disconnections.
+ * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set,
+ * ::MQTTASYNC_FAILURE if an error occurred.
+ */
+
+LIBMQTT_API int MQTTAsync_setConnectionLostCallback(MQTTAsync handle, void* context,
+ MQTTAsync_connectionLost* cl);
+
+/**
+ * This function sets the callback function for a message arrived event for
+ * a specific client. Any necessary message acknowledgements and status
+ * communications are handled in the background without any intervention
+ * from the client application. If you do not set a messageArrived callback
+ * function, you will not be notified of the receipt of any messages as a
+ * result of a subscription.
+ *
+ * <b>Note:</b> The MQTT client must be disconnected when this function is
+ * called.
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param context A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to the callback functions to provide
+ * access to the context information in the callback.
+ * @param ma A pointer to an MQTTAsync_messageArrived() callback
+ * function. You can set this to NULL if your application doesn't handle
+ * receipt of messages.
+ * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set,
+ * ::MQTTASYNC_FAILURE if an error occurred.
+ */
+LIBMQTT_API int MQTTAsync_setMessageArrivedCallback(MQTTAsync handle, void* context,
+ MQTTAsync_messageArrived* ma);
+
+/**
+ * This function sets the callback function for a delivery complete event
+ * for a specific client. Any necessary message acknowledgements and status
+ * communications are handled in the background without any intervention
+ * from the client application.
+ *
+ * <b>Note:</b> The MQTT client must be disconnected when this function is
+ * called.
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param context A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to the callback functions to provide
+ * access to the context information in the callback.
+ * @param dc A pointer to an MQTTAsync_deliveryComplete() callback
+ * function. You can set this to NULL if you do not want to check
+ * for successful delivery.
+ * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set,
+ * ::MQTTASYNC_FAILURE if an error occurred.
+ */
+LIBMQTT_API int MQTTAsync_setDeliveryCompleteCallback(MQTTAsync handle, void* context,
+ MQTTAsync_deliveryComplete* dc);
+
+/**
+ * Sets the MQTTAsync_connected() callback function for a client.
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param context A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to each of the callback functions to
+ * provide access to the context information in the callback.
+ * @param co A pointer to an MQTTAsync_connected() callback
+ * function. NULL removes the callback setting.
+ * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set,
+ * ::MQTTASYNC_FAILURE if an error occurred.
+ */
+LIBMQTT_API int MQTTAsync_setConnected(MQTTAsync handle, void* context, MQTTAsync_connected* co);
+
+
+/**
+ * Reconnects a client with the previously used connect options. Connect
+ * must have previously been called for this to work.
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @return ::MQTTASYNC_SUCCESS if the callbacks were correctly set,
+ * ::MQTTASYNC_FAILURE if an error occurred.
+ */
+LIBMQTT_API int MQTTAsync_reconnect(MQTTAsync handle);
+
+
+/**
+ * This function creates an MQTT client ready for connection to the
+ * specified server and using the specified persistent storage (see
+ * MQTTAsync_persistence). See also MQTTAsync_destroy().
+ * @param handle A pointer to an ::MQTTAsync handle. The handle is
+ * populated with a valid client reference following a successful return from
+ * this function.
+ * @param serverURI A null-terminated string specifying the server to
+ * which the client will connect. It takes the form
+ * <i>protocol://host:port</i> where <i>protocol</i> must be:
+ * <br>
+ * @em tcp:// or @em mqtt:// - Insecure TCP
+ * <br>
+ * @em ssl:// or @em mqtts:// - Encrypted SSL/TLS
+ * <br>
+ * @em ws:// - Insecure websockets
+ * <br>
+ * @em wss:// - Secure web sockets
+ * <br>
+ * The TLS enabled prefixes (ssl, mqtts, wss) are only valid if a TLS
+ * version of the library is linked with.
+ * For <i>host</i>, you can specify either an IP address or a host name. For
+ * instance, to connect to a server running on the local machines with the
+ * default MQTT port, specify <i>tcp://localhost:1883</i>.
+ * @param clientId The client identifier passed to the server when the
+ * client connects to it. It is a null-terminated UTF-8 encoded string.
+ * @param persistence_type The type of persistence to be used by the client:
+ * <br>
+ * ::MQTTCLIENT_PERSISTENCE_NONE: Use in-memory persistence. If the device or
+ * system on which the client is running fails or is switched off, the current
+ * state of any in-flight messages is lost and some messages may not be
+ * delivered even at QoS1 and QoS2.
+ * <br>
+ * ::MQTTCLIENT_PERSISTENCE_DEFAULT: Use the default (file system-based)
+ * persistence mechanism. Status about in-flight messages is held in persistent
+ * storage and provides some protection against message loss in the case of
+ * unexpected failure.
+ * <br>
+ * ::MQTTCLIENT_PERSISTENCE_USER: Use an application-specific persistence
+ * implementation. Using this type of persistence gives control of the
+ * persistence mechanism to the application. The application has to implement
+ * the MQTTClient_persistence interface.
+ * @param persistence_context If the application uses
+ * ::MQTTCLIENT_PERSISTENCE_NONE persistence, this argument is unused and should
+ * be set to NULL. For ::MQTTCLIENT_PERSISTENCE_DEFAULT persistence, it
+ * should be set to the location of the persistence directory (if set
+ * to NULL, the persistence directory used is the working directory).
+ * Applications that use ::MQTTCLIENT_PERSISTENCE_USER persistence set this
+ * argument to point to a valid MQTTClient_persistence structure.
+ * @return ::MQTTASYNC_SUCCESS if the client is successfully created, otherwise
+ * an error code is returned.
+ */
+LIBMQTT_API int MQTTAsync_create(MQTTAsync* handle, const char* serverURI, const char* clientId,
+ int persistence_type, void* persistence_context);
+
+/** Options for the ::MQTTAsync_createWithOptions call */
+typedef struct
+{
+ /** The eyecatcher for this structure. must be MQCO. */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0, 1, 2 or 3
+ * 0 means no MQTTVersion
+ * 1 means no allowDisconnectedSendAtAnyTime, deleteOldestMessages, restoreMessages
+ * 2 means no persistQoS0
+ */
+ int struct_version;
+ /** Whether to allow messages to be sent when the client library is not connected. */
+ int sendWhileDisconnected;
+ /** The maximum number of messages allowed to be buffered. This is intended to be used to
+ * limit the number of messages queued while the client is not connected. It also applies
+ * when the client is connected, however, so has to be greater than 0. */
+ int maxBufferedMessages;
+ /** Whether the MQTT version is 3.1, 3.1.1, or 5. To use V5, this must be set.
+ * MQTT V5 has to be chosen here, because during the create call the message persistence
+ * is initialized, and we want to know whether the format of any persisted messages
+ * is appropriate for the MQTT version we are going to connect with. Selecting 3.1 or
+ * 3.1.1 and attempting to read 5.0 persisted messages will result in an error on create. */
+ int MQTTVersion;
+ /**
+ * Allow sending of messages while disconnected before a first successful connect.
+ */
+ int allowDisconnectedSendAtAnyTime;
+ /*
+ * When the maximum number of buffered messages is reached, delete the oldest rather than the newest.
+ */
+ int deleteOldestMessages;
+ /*
+ * Restore messages from persistence on create - or clear it.
+ */
+ int restoreMessages;
+ /*
+ * Persist QoS0 publish commands - an option to not persist them.
+ */
+ int persistQoS0;
+} MQTTAsync_createOptions;
+
+#define MQTTAsync_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 2, 0, 100, MQTTVERSION_DEFAULT, 0, 0, 1, 1}
+
+#define MQTTAsync_createOptions_initializer5 { {'M', 'Q', 'C', 'O'}, 2, 0, 100, MQTTVERSION_5, 0, 0, 1, 1}
+
+
+LIBMQTT_API int MQTTAsync_createWithOptions(MQTTAsync* handle, const char* serverURI, const char* clientId,
+ int persistence_type, void* persistence_context, MQTTAsync_createOptions* options);
+
+/**
+ * MQTTAsync_willOptions defines the MQTT "Last Will and Testament" (LWT) settings for
+ * the client. In the event that a client unexpectedly loses its connection to
+ * the server, the server publishes the LWT message to the LWT topic on
+ * behalf of the client. This allows other clients (subscribed to the LWT topic)
+ * to be made aware that the client has disconnected. To enable the LWT
+ * function for a specific client, a valid pointer to an MQTTAsync_willOptions
+ * structure is passed in the MQTTAsync_connectOptions structure used in the
+ * MQTTAsync_connect() call that connects the client to the server. The pointer
+ * to MQTTAsync_willOptions can be set to NULL if the LWT function is not
+ * required.
+ */
+typedef struct
+{
+ /** The eyecatcher for this structure. must be MQTW. */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0 or 1
+ 0 indicates no binary will message support
+ */
+ int struct_version;
+ /** The LWT topic to which the LWT message will be published. */
+ const char* topicName;
+ /** The LWT payload. */
+ const char* message;
+ /**
+ * The retained flag for the LWT message (see MQTTAsync_message.retained).
+ */
+ int retained;
+ /**
+ * The quality of service setting for the LWT message (see
+ * MQTTAsync_message.qos and @ref qos).
+ */
+ int qos;
+ /** The LWT payload in binary form. This is only checked and used if the message option is NULL */
+ struct
+ {
+ int len; /**< binary payload length */
+ const void* data; /**< binary payload data */
+ } payload;
+} MQTTAsync_willOptions;
+
+#define MQTTAsync_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, { 0, NULL } }
+
+#define MQTT_SSL_VERSION_DEFAULT 0
+#define MQTT_SSL_VERSION_TLS_1_0 1
+#define MQTT_SSL_VERSION_TLS_1_1 2
+#define MQTT_SSL_VERSION_TLS_1_2 3
+
+/**
+* MQTTAsync_sslProperties defines the settings to establish an SSL/TLS connection using the
+* OpenSSL library. It covers the following scenarios:
+* - Server authentication: The client needs the digital certificate of the server. It is included
+* in a store containting trusted material (also known as "trust store").
+* - Mutual authentication: Both client and server are authenticated during the SSL handshake. In
+* addition to the digital certificate of the server in a trust store, the client will need its own
+* digital certificate and the private key used to sign its digital certificate stored in a "key store".
+* - Anonymous connection: Both client and server do not get authenticated and no credentials are needed
+* to establish an SSL connection. Note that this scenario is not fully secure since it is subject to
+* man-in-the-middle attacks.
+*/
+typedef struct
+{
+ /** The eyecatcher for this structure. Must be MQTS */
+ char struct_id[4];
+
+ /** The version number of this structure. Must be 0, 1, 2, 3, 4 or 5.
+ * 0 means no sslVersion
+ * 1 means no verify, CApath
+ * 2 means no ssl_error_context, ssl_error_cb
+ * 3 means no ssl_psk_cb, ssl_psk_context, disableDefaultTrustStore
+ * 4 means no protos, protos_len
+ */
+ int struct_version;
+
+ /** The file in PEM format containing the public digital certificates trusted by the client. */
+ const char* trustStore;
+
+ /** The file in PEM format containing the public certificate chain of the client. It may also include
+ * the client's private key.
+ */
+ const char* keyStore;
+
+ /** If not included in the sslKeyStore, this setting points to the file in PEM format containing
+ * the client's private key.
+ */
+ const char* privateKey;
+
+ /** The password to load the client's privateKey if encrypted. */
+ const char* privateKeyPassword;
+
+ /**
+ * The list of cipher suites that the client will present to the server during the SSL handshake. For a
+ * full explanation of the cipher list format, please see the OpenSSL on-line documentation:
+ * http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT
+ * If this setting is ommitted, its default value will be "ALL", that is, all the cipher suites -excluding
+ * those offering no encryption- will be considered.
+ * This setting can be used to set an SSL anonymous connection ("aNULL" string value, for instance).
+ */
+ const char* enabledCipherSuites;
+
+ /** True/False option to enable verification of the server certificate **/
+ int enableServerCertAuth;
+
+ /** The SSL/TLS version to use. Specify one of MQTT_SSL_VERSION_DEFAULT (0),
+ * MQTT_SSL_VERSION_TLS_1_0 (1), MQTT_SSL_VERSION_TLS_1_1 (2) or MQTT_SSL_VERSION_TLS_1_2 (3).
+ * Only used if struct_version is >= 1.
+ */
+ int sslVersion;
+
+ /**
+ * Whether to carry out post-connect checks, including that a certificate
+ * matches the given host name.
+ * Exists only if struct_version >= 2
+ */
+ int verify;
+
+ /**
+ * From the OpenSSL documentation:
+ * If CApath is not NULL, it points to a directory containing CA certificates in PEM format.
+ * Exists only if struct_version >= 2
+ */
+ const char* CApath;
+
+ /**
+ * Callback function for OpenSSL error handler ERR_print_errors_cb
+ * Exists only if struct_version >= 3
+ */
+ int (*ssl_error_cb) (const char *str, size_t len, void *u);
+
+ /**
+ * Application-specific contex for OpenSSL error handler ERR_print_errors_cb
+ * Exists only if struct_version >= 3
+ */
+ void* ssl_error_context;
+
+ /**
+ * Callback function for setting TLS-PSK options. Parameters correspond to that of
+ * SSL_CTX_set_psk_client_callback, except for u which is the pointer ssl_psk_context.
+ * Exists only if struct_version >= 4
+ */
+ unsigned int (*ssl_psk_cb) (const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len, void *u);
+
+ /**
+ * Application-specific contex for ssl_psk_cb
+ * Exists only if struct_version >= 4
+ */
+ void* ssl_psk_context;
+
+ /**
+ * Don't load default SSL CA. Should be used together with PSK to make sure
+ * regular servers with certificate in place is not accepted.
+ * Exists only if struct_version >= 4
+ */
+ int disableDefaultTrustStore;
+
+ /**
+ * The protocol-lists must be in wire-format, which is defined as a vector of non-empty, 8-bit length-prefixed, byte strings.
+ * The length-prefix byte is not included in the length. Each string is limited to 255 bytes. A byte-string length of 0 is invalid.
+ * A truncated byte-string is invalid.
+ * Check documentation for SSL_CTX_set_alpn_protos
+ * Exists only if struct_version >= 5
+ */
+ const unsigned char *protos;
+
+ /**
+ * The length of the vector protos vector
+ * Exists only if struct_version >= 5
+ */
+ unsigned int protos_len;
+} MQTTAsync_SSLOptions;
+
+#define MQTTAsync_SSLOptions_initializer { {'M', 'Q', 'T', 'S'}, 5, NULL, NULL, NULL, NULL, NULL, 1, MQTT_SSL_VERSION_DEFAULT, 0, NULL, NULL, NULL, NULL, NULL, 0, NULL, 0 }
+
+/** Utility structure where name/value pairs are needed */
+typedef struct
+{
+ const char* name; /**< name string */
+ const char* value; /**< value string */
+} MQTTAsync_nameValue;
+
+/**
+ * MQTTAsync_connectOptions defines several settings that control the way the
+ * client connects to an MQTT server.
+ *
+ * Suitable default values are set in the following initializers:
+ * - MQTTAsync_connectOptions_initializer: for MQTT 3.1.1 non-WebSockets
+ * - MQTTAsync_connectOptions_initializer5: for MQTT 5.0 non-WebSockets
+ * - MQTTAsync_connectOptions_initializer_ws: for MQTT 3.1.1 WebSockets
+ * - MQTTAsync_connectOptions_initializer5_ws: for MQTT 5.0 WebSockets
+ */
+typedef struct
+{
+ /** The eyecatcher for this structure. must be MQTC. */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0, 1, 2, 3 4 5 6, 7 or 8.
+ * 0 signifies no SSL options and no serverURIs
+ * 1 signifies no serverURIs
+ * 2 signifies no MQTTVersion
+ * 3 signifies no automatic reconnect options
+ * 4 signifies no binary password option (just string)
+ * 5 signifies no MQTTV5 properties
+ * 6 signifies no HTTP headers option
+ * 7 signifies no HTTP proxy and HTTPS proxy options
+ */
+ int struct_version;
+ /** The "keep alive" interval, measured in seconds, defines the maximum time
+ * that should pass without communication between the client and the server
+ * The client will ensure that at least one message travels across the
+ * network within each keep alive period. In the absence of a data-related
+ * message during the time period, the client sends a very small MQTT
+ * "ping" message, which the server will acknowledge. The keep alive
+ * interval enables the client to detect when the server is no longer
+ * available without having to wait for the long TCP/IP timeout.
+ * Set to 0 if you do not want any keep alive processing.
+ */
+ int keepAliveInterval;
+ /**
+ * This is a boolean value. The cleansession setting controls the behaviour
+ * of both the client and the server at connection and disconnection time.
+ * The client and server both maintain session state information. This
+ * information is used to ensure "at least once" and "exactly once"
+ * delivery, and "exactly once" receipt of messages. Session state also
+ * includes subscriptions created by an MQTT client. You can choose to
+ * maintain or discard state information between sessions.
+ *
+ * When cleansession is true, the state information is discarded at
+ * connect and disconnect. Setting cleansession to false keeps the state
+ * information. When you connect an MQTT client application with
+ * MQTTAsync_connect(), the client identifies the connection using the
+ * client identifier and the address of the server. The server checks
+ * whether session information for this client
+ * has been saved from a previous connection to the server. If a previous
+ * session still exists, and cleansession=true, then the previous session
+ * information at the client and server is cleared. If cleansession=false,
+ * the previous session is resumed. If no previous session exists, a new
+ * session is started.
+ */
+ int cleansession;
+ /**
+ * This controls how many messages can be in-flight simultaneously.
+ */
+ int maxInflight;
+ /**
+ * This is a pointer to an MQTTAsync_willOptions structure. If your
+ * application does not make use of the Last Will and Testament feature,
+ * set this pointer to NULL.
+ */
+ MQTTAsync_willOptions* will;
+ /**
+ * MQTT servers that support the MQTT v3.1 protocol provide authentication
+ * and authorisation by user name and password. This is the user name
+ * parameter.
+ */
+ const char* username;
+ /**
+ * MQTT servers that support the MQTT v3.1 protocol provide authentication
+ * and authorisation by user name and password. This is the password
+ * parameter.
+ */
+ const char* password;
+ /**
+ * The time interval in seconds to allow a connect to complete.
+ */
+ int connectTimeout;
+ /**
+ * The time interval in seconds after which unacknowledged publish requests are
+ * retried during a TCP session. With MQTT 3.1.1 and later, retries are
+ * not required except on reconnect. 0 turns off in-session retries, and is the
+ * recommended setting. Adding retries to an already overloaded network only
+ * exacerbates the problem.
+ */
+ int retryInterval;
+ /**
+ * This is a pointer to an MQTTAsync_SSLOptions structure. If your
+ * application does not make use of SSL, set this pointer to NULL.
+ */
+ MQTTAsync_SSLOptions* ssl;
+ /**
+ * A pointer to a callback function to be called if the connect successfully
+ * completes. Can be set to NULL, in which case no indication of successful
+ * completion will be received.
+ */
+ MQTTAsync_onSuccess* onSuccess;
+ /**
+ * A pointer to a callback function to be called if the connect fails.
+ * Can be set to NULL, in which case no indication of unsuccessful
+ * completion will be received.
+ */
+ MQTTAsync_onFailure* onFailure;
+ /**
+ * A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to success or failure callback functions to
+ * provide access to the context information in the callback.
+ */
+ void* context;
+ /**
+ * The number of entries in the serverURIs array.
+ */
+ int serverURIcount;
+ /**
+ * An array of null-terminated strings specifying the servers to
+ * which the client will connect. Each string takes the form <i>protocol://host:port</i>.
+ * <i>protocol</i> must be <i>tcp</i>, <i>ssl</i>, <i>ws</i> or <i>wss</i>.
+ * The TLS enabled prefixes (ssl, wss) are only valid if a TLS version of the library
+ * is linked with.
+ * For <i>host</i>, you can
+ * specify either an IP address or a domain name. For instance, to connect to
+ * a server running on the local machines with the default MQTT port, specify
+ * <i>tcp://localhost:1883</i>.
+ */
+ char* const* serverURIs;
+ /**
+ * Sets the version of MQTT to be used on the connect.
+ * MQTTVERSION_DEFAULT (0) = default: start with 3.1.1, and if that fails, fall back to 3.1
+ * MQTTVERSION_3_1 (3) = only try version 3.1
+ * MQTTVERSION_3_1_1 (4) = only try version 3.1.1
+ */
+ int MQTTVersion;
+ /**
+ * Reconnect automatically in the case of a connection being lost. 0=false, 1=true
+ */
+ int automaticReconnect;
+ /**
+ * The minimum automatic reconnect retry interval in seconds. Doubled on each failed retry.
+ */
+ int minRetryInterval;
+ /**
+ * The maximum automatic reconnect retry interval in seconds. The doubling stops here on failed retries.
+ */
+ int maxRetryInterval;
+ /**
+ * Optional binary password. Only checked and used if the password option is NULL
+ */
+ struct {
+ int len; /**< binary password length */
+ const void* data; /**< binary password data */
+ } binarypwd;
+ /*
+ * MQTT V5 clean start flag. Only clears state at the beginning of the session.
+ */
+ int cleanstart;
+ /**
+ * MQTT V5 properties for connect
+ */
+ MQTTProperties *connectProperties;
+ /**
+ * MQTT V5 properties for the will message in the connect
+ */
+ MQTTProperties *willProperties;
+ /**
+ * A pointer to a callback function to be called if the connect successfully
+ * completes. Can be set to NULL, in which case no indication of successful
+ * completion will be received.
+ */
+ MQTTAsync_onSuccess5* onSuccess5;
+ /**
+ * A pointer to a callback function to be called if the connect fails.
+ * Can be set to NULL, in which case no indication of unsuccessful
+ * completion will be received.
+ */
+ MQTTAsync_onFailure5* onFailure5;
+ /**
+ * HTTP headers for websockets
+ */
+ const MQTTAsync_nameValue* httpHeaders;
+ /**
+ * HTTP proxy
+ */
+ const char* httpProxy;
+ /**
+ * HTTPS proxy
+ */
+ const char* httpsProxy;
+} MQTTAsync_connectOptions;
+
+/** Initializer for connect options for MQTT 3.1.1 non-WebSocket connections */
+#define MQTTAsync_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 8, 60, 1, 65535, NULL, NULL, NULL, 30, 0,\
+NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_DEFAULT, 0, 1, 60, {0, NULL}, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
+
+/** Initializer for connect options for MQTT 5.0 non-WebSocket connections */
+#define MQTTAsync_connectOptions_initializer5 { {'M', 'Q', 'T', 'C'}, 8, 60, 0, 65535, NULL, NULL, NULL, 30, 0,\
+NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_5, 0, 1, 60, {0, NULL}, 1, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
+
+/** Initializer for connect options for MQTT 3.1.1 WebSockets connections.
+ * The keepalive interval is set to 45 seconds to avoid webserver 60 second inactivity timeouts.
+ */
+#define MQTTAsync_connectOptions_initializer_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 1, 65535, NULL, NULL, NULL, 30, 0,\
+NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_DEFAULT, 0, 1, 60, {0, NULL}, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
+
+/** Initializer for connect options for MQTT 5.0 WebSockets connections.
+ * The keepalive interval is set to 45 seconds to avoid webserver 60 second inactivity timeouts.
+ */
+#define MQTTAsync_connectOptions_initializer5_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 0, 65535, NULL, NULL, NULL, 30, 0,\
+NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_5, 0, 1, 60, {0, NULL}, 1, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
+
+
+/**
+ * This function attempts to connect a previously-created client (see
+ * MQTTAsync_create()) to an MQTT server using the specified options. If you
+ * want to enable asynchronous message and status notifications, you must call
+ * MQTTAsync_setCallbacks() prior to MQTTAsync_connect().
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param options A pointer to a valid MQTTAsync_connectOptions
+ * structure.
+ * @return ::MQTTASYNC_SUCCESS if the client connect request was accepted.
+ * If the client was unable to connect to the server, an error code is
+ * returned via the onFailure callback, if set.
+ * Error codes greater than 0 are returned by the MQTT protocol:<br><br>
+ * <b>1</b>: Connection refused: Unacceptable protocol version<br>
+ * <b>2</b>: Connection refused: Identifier rejected<br>
+ * <b>3</b>: Connection refused: Server unavailable<br>
+ * <b>4</b>: Connection refused: Bad user name or password<br>
+ * <b>5</b>: Connection refused: Not authorized<br>
+ * <b>6-255</b>: Reserved for future use<br>
+ */
+LIBMQTT_API int MQTTAsync_connect(MQTTAsync handle, const MQTTAsync_connectOptions* options);
+
+/** Options for the ::MQTTAsync_disconnect call */
+typedef struct
+{
+ /** The eyecatcher for this structure. Must be MQTD. */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0 or 1. 0 signifies no V5 properties */
+ int struct_version;
+ /**
+ * The client delays disconnection for up to this time (in
+ * milliseconds) in order to allow in-flight message transfers to complete.
+ */
+ int timeout;
+ /**
+ * A pointer to a callback function to be called if the disconnect successfully
+ * completes. Can be set to NULL, in which case no indication of successful
+ * completion will be received.
+ */
+ MQTTAsync_onSuccess* onSuccess;
+ /**
+ * A pointer to a callback function to be called if the disconnect fails.
+ * Can be set to NULL, in which case no indication of unsuccessful
+ * completion will be received.
+ */
+ MQTTAsync_onFailure* onFailure;
+ /**
+ * A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to success or failure callback functions to
+ * provide access to the context information in the callback.
+ */
+ void* context;
+ /**
+ * MQTT V5 input properties
+ */
+ MQTTProperties properties;
+ /**
+ * Reason code for MQTTV5 disconnect
+ */
+ enum MQTTReasonCodes reasonCode;
+ /**
+ * A pointer to a callback function to be called if the disconnect successfully
+ * completes. Can be set to NULL, in which case no indication of successful
+ * completion will be received.
+ */
+ MQTTAsync_onSuccess5* onSuccess5;
+ /**
+ * A pointer to a callback function to be called if the disconnect fails.
+ * Can be set to NULL, in which case no indication of unsuccessful
+ * completion will be received.
+ */
+ MQTTAsync_onFailure5* onFailure5;
+} MQTTAsync_disconnectOptions;
+
+#define MQTTAsync_disconnectOptions_initializer { {'M', 'Q', 'T', 'D'}, 0, 0, NULL, NULL, NULL,\
+ MQTTProperties_initializer, MQTTREASONCODE_SUCCESS, NULL, NULL }
+
+#define MQTTAsync_disconnectOptions_initializer5 { {'M', 'Q', 'T', 'D'}, 1, 0, NULL, NULL, NULL,\
+ MQTTProperties_initializer, MQTTREASONCODE_SUCCESS, NULL, NULL }
+
+/**
+ * This function attempts to disconnect the client from the MQTT
+ * server. In order to allow the client time to complete handling of messages
+ * that are in-flight when this function is called, a timeout period is
+ * specified. When the timeout period has expired, the client disconnects even
+ * if there are still outstanding message acknowledgements.
+ * The next time the client connects to the same server, any QoS 1 or 2
+ * messages which have not completed will be retried depending on the
+ * cleansession settings for both the previous and the new connection (see
+ * MQTTAsync_connectOptions.cleansession and MQTTAsync_connect()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param options The client delays disconnection for up to this time (in
+ * milliseconds) in order to allow in-flight message transfers to complete.
+ * @return ::MQTTASYNC_SUCCESS if the client successfully disconnects from
+ * the server. An error code is returned if the client was unable to disconnect
+ * from the server
+ */
+LIBMQTT_API int MQTTAsync_disconnect(MQTTAsync handle, const MQTTAsync_disconnectOptions* options);
+
+
+/**
+ * This function allows the client application to test whether or not a
+ * client is currently connected to the MQTT server.
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @return Boolean true if the client is connected, otherwise false.
+ */
+LIBMQTT_API int MQTTAsync_isConnected(MQTTAsync handle);
+
+
+/**
+ * This function attempts to subscribe a client to a single topic, which may
+ * contain wildcards (see @ref wildcard). This call also specifies the
+ * @ref qos requested for the subscription
+ * (see also MQTTAsync_subscribeMany()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param topic The subscription topic, which may include wildcards.
+ * @param qos The requested quality of service for the subscription.
+ * @param response A pointer to a response options structure. Used to set callback functions.
+ * @return ::MQTTASYNC_SUCCESS if the subscription request is successful.
+ * An error code is returned if there was a problem registering the
+ * subscription.
+ */
+LIBMQTT_API int MQTTAsync_subscribe(MQTTAsync handle, const char* topic, int qos, MQTTAsync_responseOptions* response);
+
+
+/**
+ * This function attempts to subscribe a client to a list of topics, which may
+ * contain wildcards (see @ref wildcard). This call also specifies the
+ * @ref qos requested for each topic (see also MQTTAsync_subscribe()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param count The number of topics for which the client is requesting
+ * subscriptions.
+ * @param topic An array (of length <i>count</i>) of pointers to
+ * topics, each of which may include wildcards.
+ * @param qos An array (of length <i>count</i>) of @ref qos
+ * values. qos[n] is the requested QoS for topic[n].
+ * @param response A pointer to a response options structure. Used to set callback functions.
+ * @return ::MQTTASYNC_SUCCESS if the subscription request is successful.
+ * An error code is returned if there was a problem registering the
+ * subscriptions.
+ */
+LIBMQTT_API int MQTTAsync_subscribeMany(MQTTAsync handle, int count, char* const* topic, const int* qos, MQTTAsync_responseOptions* response);
+
+/**
+ * This function attempts to remove an existing subscription made by the
+ * specified client.
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param topic The topic for the subscription to be removed, which may
+ * include wildcards (see @ref wildcard).
+ * @param response A pointer to a response options structure. Used to set callback functions.
+ * @return ::MQTTASYNC_SUCCESS if the subscription is removed.
+ * An error code is returned if there was a problem removing the
+ * subscription.
+ */
+LIBMQTT_API int MQTTAsync_unsubscribe(MQTTAsync handle, const char* topic, MQTTAsync_responseOptions* response);
+
+/**
+ * This function attempts to remove existing subscriptions to a list of topics
+ * made by the specified client.
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param count The number subscriptions to be removed.
+ * @param topic An array (of length <i>count</i>) of pointers to the topics of
+ * the subscriptions to be removed, each of which may include wildcards.
+ * @param response A pointer to a response options structure. Used to set callback functions.
+ * @return ::MQTTASYNC_SUCCESS if the subscriptions are removed.
+ * An error code is returned if there was a problem removing the subscriptions.
+ */
+LIBMQTT_API int MQTTAsync_unsubscribeMany(MQTTAsync handle, int count, char* const* topic, MQTTAsync_responseOptions* response);
+
+
+/**
+ * This function attempts to publish a message to a given topic (see also
+ * ::MQTTAsync_sendMessage()). An ::MQTTAsync_token is issued when
+ * this function returns successfully if the QoS is greater than 0.
+ * If the client application needs to
+ * test for successful delivery of messages, a callback should be set
+ * (see ::MQTTAsync_onSuccess() and ::MQTTAsync_deliveryComplete()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param destinationName The topic associated with this message.
+ * @param payloadlen The length of the payload in bytes.
+ * @param payload A pointer to the byte array payload of the message.
+ * @param qos The @ref qos of the message.
+ * @param retained The retained flag for the message.
+ * @param response A pointer to an ::MQTTAsync_responseOptions structure. Used to set callback functions.
+ * This is optional and can be set to NULL.
+ * @return ::MQTTASYNC_SUCCESS if the message is accepted for publication.
+ * An error code is returned if there was a problem accepting the message.
+ */
+LIBMQTT_API int MQTTAsync_send(MQTTAsync handle, const char* destinationName, int payloadlen, const void* payload, int qos,
+ int retained, MQTTAsync_responseOptions* response);
+
+/**
+ * This function attempts to publish a message to a given topic (see also
+ * MQTTAsync_publish()). An ::MQTTAsync_token is issued when
+ * this function returns successfully if the QoS is greater than 0.
+ * If the client application needs to
+ * test for successful delivery of messages, a callback should be set
+ * (see ::MQTTAsync_onSuccess() and ::MQTTAsync_deliveryComplete()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param destinationName The topic associated with this message.
+ * @param msg A pointer to a valid MQTTAsync_message structure containing
+ * the payload and attributes of the message to be published.
+ * @param response A pointer to an ::MQTTAsync_responseOptions structure. Used to set callback functions.
+ * @return ::MQTTASYNC_SUCCESS if the message is accepted for publication.
+ * An error code is returned if there was a problem accepting the message.
+ */
+LIBMQTT_API int MQTTAsync_sendMessage(MQTTAsync handle, const char* destinationName, const MQTTAsync_message* msg, MQTTAsync_responseOptions* response);
+
+
+/**
+ * This function sets a pointer to an array of tokens for
+ * messages that are currently in-flight (pending completion).
+ *
+ * <b>Important note:</b> The memory used to hold the array of tokens is
+ * malloc()'d in this function. The client application is responsible for
+ * freeing this memory when it is no longer required.
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param tokens The address of a pointer to an ::MQTTAsync_token.
+ * When the function returns successfully, the pointer is set to point to an
+ * array of tokens representing messages pending completion. The last member of
+ * the array is set to -1 to indicate there are no more tokens. If no tokens
+ * are pending, the pointer is set to NULL.
+ * @return ::MQTTASYNC_SUCCESS if the function returns successfully.
+ * An error code is returned if there was a problem obtaining the list of
+ * pending tokens.
+ */
+LIBMQTT_API int MQTTAsync_getPendingTokens(MQTTAsync handle, MQTTAsync_token **tokens);
+
+/**
+ * Tests whether a request corresponding to a token is complete.
+ *
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param token An ::MQTTAsync_token associated with a request.
+ * @return 1 if the request has been completed, 0 if not.
+ */
+#define MQTTASYNC_TRUE 1
+LIBMQTT_API int MQTTAsync_isComplete(MQTTAsync handle, MQTTAsync_token token);
+
+
+/**
+ * Waits for a request corresponding to a token to complete. This only works for
+ * messages with QoS greater than 0. A QoS 0 message has no MQTT token.
+ * This function will always return ::MQTTASYNC_SUCCESS for a QoS 0 message.
+ *
+ * @param handle A valid client handle from a successful call to
+ * MQTTAsync_create().
+ * @param token An ::MQTTAsync_token associated with a request.
+ * @param timeout the maximum time to wait for completion, in milliseconds
+ * @return ::MQTTASYNC_SUCCESS if the request has been completed in the time allocated,
+ * ::MQTTASYNC_FAILURE or ::MQTTASYNC_DISCONNECTED if not.
+ */
+LIBMQTT_API int MQTTAsync_waitForCompletion(MQTTAsync handle, MQTTAsync_token token, unsigned long timeout);
+
+
+/**
+ * This function frees memory allocated to an MQTT message, including the
+ * additional memory allocated to the message payload. The client application
+ * calls this function when the message has been fully processed. <b>Important
+ * note:</b> This function does not free the memory allocated to a message
+ * topic string. It is the responsibility of the client application to free
+ * this memory using the MQTTAsync_free() library function.
+ * @param msg The address of a pointer to the ::MQTTAsync_message structure
+ * to be freed.
+ */
+LIBMQTT_API void MQTTAsync_freeMessage(MQTTAsync_message** msg);
+
+/**
+ * This function frees memory allocated by the MQTT C client library, especially the
+ * topic name. This is needed on Windows when the client library and application
+ * program have been compiled with different versions of the C compiler. It is
+ * thus good policy to always use this function when freeing any MQTT C client-
+ * allocated memory.
+ * @param ptr The pointer to the client library storage to be freed.
+ */
+LIBMQTT_API void MQTTAsync_free(void* ptr);
+
+/**
+ * This function is used to allocate memory to be used or freed by the MQTT C client library,
+ * especially the data in the ::MQTTPersistence_afterRead and ::MQTTPersistence_beforeWrite
+ * callbacks. This is needed on Windows when the client library and application
+ * program have been compiled with different versions of the C compiler.
+ * @param size The size of the memory to be allocated.
+ */
+LIBMQTT_API void* MQTTAsync_malloc(size_t size);
+
+/**
+ * This function frees the memory allocated to an MQTT client (see
+ * MQTTAsync_create()). It should be called when the client is no longer
+ * required.
+ * @param handle A pointer to the handle referring to the ::MQTTAsync
+ * structure to be freed.
+ */
+LIBMQTT_API void MQTTAsync_destroy(MQTTAsync* handle);
+
+
+
+enum MQTTASYNC_TRACE_LEVELS
+{
+ MQTTASYNC_TRACE_MAXIMUM = 1,
+ MQTTASYNC_TRACE_MEDIUM,
+ MQTTASYNC_TRACE_MINIMUM,
+ MQTTASYNC_TRACE_PROTOCOL,
+ MQTTASYNC_TRACE_ERROR,
+ MQTTASYNC_TRACE_SEVERE,
+ MQTTASYNC_TRACE_FATAL,
+};
+
+
+/**
+ * This function sets the level of trace information which will be
+ * returned in the trace callback.
+ * @param level the trace level required
+ */
+LIBMQTT_API void MQTTAsync_setTraceLevel(enum MQTTASYNC_TRACE_LEVELS level);
+
+
+/**
+ * This is a callback function prototype which must be implemented if you want
+ * to receive trace information. Do not invoke any other Paho API calls in this
+ * callback function - unpredictable behavior may result.
+ * @param level the trace level of the message returned
+ * @param message the trace message. This is a pointer to a static buffer which
+ * will be overwritten on each call. You must copy the data if you want to keep
+ * it for later.
+ */
+typedef void MQTTAsync_traceCallback(enum MQTTASYNC_TRACE_LEVELS level, char* message);
+
+/**
+ * This function sets the trace callback if needed. If set to NULL,
+ * no trace information will be returned. The default trace level is
+ * MQTTASYNC_TRACE_MINIMUM.
+ * @param callback a pointer to the function which will handle the trace information
+ */
+LIBMQTT_API void MQTTAsync_setTraceCallback(MQTTAsync_traceCallback* callback);
+
+/**
+ * This function returns version information about the library.
+ * no trace information will be returned. The default trace level is
+ * MQTTASYNC_TRACE_MINIMUM
+ * @return an array of strings describing the library. The last entry is a NULL pointer.
+ */
+LIBMQTT_API MQTTAsync_nameValue* MQTTAsync_getVersionInfo(void);
+
+/**
+ * Returns a pointer to a string representation of the error code, or NULL.
+ * Do not free after use. Returns NULL if the error code is unknown.
+ * @param code the MQTTASYNC_ return code.
+ * @return a static string representation of the error code.
+ */
+LIBMQTT_API const char* MQTTAsync_strerror(int code);
+
+
+/*!
+ * @cond MQTTAsync_main
+ * @page async Threading
+ * The client application runs on several threads.
+ * Processing of handshaking and maintaining
+ * the network connection is performed in the background.
+ * This API is thread safe: functions may be called by multiple application
+ * threads.
+ * Notifications of status and message reception are provided to the client
+ * application using callbacks registered with the library by the call to
+ * MQTTAsync_setCallbacks() (see MQTTAsync_messageArrived(),
+ * MQTTAsync_connectionLost() and MQTTAsync_deliveryComplete()).
+ * In addition, some functions allow success and failure callbacks to be set
+ * for individual requests, in the ::MQTTAsync_responseOptions structure. Applications
+ * can be written as a chain of callback functions.
+ *
+ * @page callbacks Callbacks
+ * Any function from this API may be used within a callback. It is not advisable to
+ * use ::MQTTAsync_waitForCompletion within a callback, however, as it is the only
+ * API call that may take some time to complete, which may cause unpredictable
+ * behaviour. All the other API calls are intended to complete quickly, starting
+ * a request in the background, with success or failure notified by other callbacks.
+ *
+ * If no callbacks are assigned, this will include the message arrived callback.
+ * This could be done if the application is a pure publisher, and does
+ * not subscribe to any topics. If however messages are received, and no message
+ * arrived callback is set, then those messages will accumulate
+ * and take up memory, as there is no place for them to be delivered.
+ * A log message will be written to highlight the issue, but it is up
+ * to the application to protect against this situation.
+ *
+ * @page auto_reconnect Automatic Reconnect
+ * The ability for the client library to reconnect automatically in the event
+ * of a connection failure was added in 1.1. The connection lost callback
+ * allows a flexible response to the loss of a connection, so almost any
+ * behaviour can be implemented in that way. Automatic reconnect does have the
+ * advantage of being a little simpler to use.
+ *
+ * To switch on automatic reconnect, the connect options field
+ * automaticReconnect should be set to non-zero. The minimum and maximum times
+ * before the next connection attempt can also be set, the defaults being 1 and
+ * 60 seconds. At each failure to reconnect, the retry interval is doubled until
+ * the maximum value is reached, and there it stays until the connection is
+ * successfully re-established whereupon it is reset.
+ *
+ * When a reconnection attempt is successful, the ::MQTTAsync_connected callback
+ * function is invoked, if set by calling ::MQTTAsync_setConnected. This allows
+ * the application to take any actions needed, such as amending subscriptions.
+ *
+ * @page offline_publish Publish While Disconnected
+ * This feature was not originally available because with persistence enabled,
+ * messages could be stored locally without ever knowing if they could be sent.
+ * The client application could have created the client with an erroneous broker
+ * address or port for instance.
+ *
+ * To enable messages to be published when the application is disconnected
+ * ::MQTTAsync_createWithOptions must be used instead of ::MQTTAsync_create to
+ * create the client object. The ::MQTTAsync_createOptions field sendWhileDisconnected
+ * must be set to non-zero, and the maxBufferedMessages field set as required -
+ * the default being 100.
+ *
+ * ::MQTTAsync_getPendingTokens can be called to return the ids of the messages
+ * waiting to be sent, or for which the sending process has not completed.
+ *
+ * @page wildcard Subscription wildcards
+ * Every MQTT message includes a topic that classifies it. MQTT servers use
+ * topics to determine which subscribers should receive messages published to
+ * the server.
+ *
+ * Consider the server receiving messages from several environmental sensors.
+ * Each sensor publishes its measurement data as a message with an associated
+ * topic. Subscribing applications need to know which sensor originally
+ * published each received message. A unique topic is thus used to identify
+ * each sensor and measurement type. Topics such as SENSOR1TEMP,
+ * SENSOR1HUMIDITY, SENSOR2TEMP and so on achieve this but are not very
+ * flexible. If additional sensors are added to the system at a later date,
+ * subscribing applications must be modified to receive them.
+ *
+ * To provide more flexibility, MQTT supports a hierarchical topic namespace.
+ * This allows application designers to organize topics to simplify their
+ * management. Levels in the hierarchy are delimited by the '/' character,
+ * such as SENSOR/1/HUMIDITY. Publishers and subscribers use these
+ * hierarchical topics as already described.
+ *
+ * For subscriptions, two wildcard characters are supported:
+ * <ul>
+ * <li>A '#' character represents a complete sub-tree of the hierarchy and
+ * thus must be the last character in a subscription topic string, such as
+ * SENSOR/#. This will match any topic starting with SENSOR/, such as
+ * SENSOR/1/TEMP and SENSOR/2/HUMIDITY.</li>
+ * <li> A '+' character represents a single level of the hierarchy and is
+ * used between delimiters. For example, SENSOR/+/TEMP will match
+ * SENSOR/1/TEMP and SENSOR/2/TEMP.</li>
+ * </ul>
+ * Publishers are not allowed to use the wildcard characters in their topic
+ * names.
+ *
+ * Deciding on your topic hierarchy is an important step in your system design.
+ *
+ * @page qos Quality of service
+ * The MQTT protocol provides three qualities of service for delivering
+ * messages between clients and servers: "at most once", "at least once" and
+ * "exactly once".
+ *
+ * Quality of service (QoS) is an attribute of an individual message being
+ * published. An application sets the QoS for a specific message by setting the
+ * MQTTAsync_message.qos field to the required value.
+ *
+ * A subscribing client can set the maximum quality of service a server uses
+ * to send messages that match the client subscriptions. The
+ * MQTTAsync_subscribe() and MQTTAsync_subscribeMany() functions set this
+ * maximum. The QoS of a message forwarded to a subscriber thus might be
+ * different to the QoS given to the message by the original publisher.
+ * The lower of the two values is used to forward a message.
+ *
+ * The three levels are:
+ *
+ * <b>QoS0, At most once:</b> The message is delivered at most once, or it
+ * may not be delivered at all. Its delivery across the network is not
+ * acknowledged. The message is not stored. The message could be lost if the
+ * client is disconnected, or if the server fails. QoS0 is the fastest mode of
+ * transfer. It is sometimes called "fire and forget".
+ *
+ * The MQTT protocol does not require servers to forward publications at QoS0
+ * to a client. If the client is disconnected at the time the server receives
+ * the publication, the publication might be discarded, depending on the
+ * server implementation.
+ *
+ * <b>QoS1, At least once:</b> The message is always delivered at least once.
+ * It might be delivered multiple times if there is a failure before an
+ * acknowledgment is received by the sender. The message must be stored
+ * locally at the sender, until the sender receives confirmation that the
+ * message has been published by the receiver. The message is stored in case
+ * the message must be sent again.
+ *
+ * <b>QoS2, Exactly once:</b> The message is always delivered exactly once.
+ * The message must be stored locally at the sender, until the sender receives
+ * confirmation that the message has been published by the receiver. The
+ * message is stored in case the message must be sent again. QoS2 is the
+ * safest, but slowest mode of transfer. A more sophisticated handshaking
+ * and acknowledgement sequence is used than for QoS1 to ensure no duplication
+ * of messages occurs.
+ * @page publish Publication example
+@code
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "MQTTAsync.h"
+
+#if !defined(_WIN32)
+#include <unistd.h>
+#else
+#include <windows.h>
+#endif
+
+#if defined(_WRS_KERNEL)
+#include <OsWrapper.h>
+#endif
+
+#define ADDRESS "tcp://mqtt.eclipseprojects.io:1883"
+#define CLIENTID "ExampleClientPub"
+#define TOPIC "MQTT Examples"
+#define PAYLOAD "Hello World!"
+#define QOS 1
+#define TIMEOUT 10000L
+
+int finished = 0;
+
+void connlost(void *context, char *cause)
+{
+ MQTTAsync client = (MQTTAsync)context;
+ MQTTAsync_connectOptions conn_opts = MQTTAsync_connectOptions_initializer;
+ int rc;
+
+ printf("\nConnection lost\n");
+ printf(" cause: %s\n", cause);
+
+ printf("Reconnecting\n");
+ conn_opts.keepAliveInterval = 20;
+ conn_opts.cleansession = 1;
+ if ((rc = MQTTAsync_connect(client, &conn_opts)) != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to start connect, return code %d\n", rc);
+ finished = 1;
+ }
+}
+
+void onDisconnectFailure(void* context, MQTTAsync_failureData* response)
+{
+ printf("Disconnect failed\n");
+ finished = 1;
+}
+
+void onDisconnect(void* context, MQTTAsync_successData* response)
+{
+ printf("Successful disconnection\n");
+ finished = 1;
+}
+
+void onSendFailure(void* context, MQTTAsync_failureData* response)
+{
+ MQTTAsync client = (MQTTAsync)context;
+ MQTTAsync_disconnectOptions opts = MQTTAsync_disconnectOptions_initializer;
+ int rc;
+
+ printf("Message send failed token %d error code %d\n", response->token, response->code);
+ opts.onSuccess = onDisconnect;
+ opts.onFailure = onDisconnectFailure;
+ opts.context = client;
+ if ((rc = MQTTAsync_disconnect(client, &opts)) != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to start disconnect, return code %d\n", rc);
+ exit(EXIT_FAILURE);
+ }
+}
+
+void onSend(void* context, MQTTAsync_successData* response)
+{
+ MQTTAsync client = (MQTTAsync)context;
+ MQTTAsync_disconnectOptions opts = MQTTAsync_disconnectOptions_initializer;
+ int rc;
+
+ printf("Message with token value %d delivery confirmed\n", response->token);
+ opts.onSuccess = onDisconnect;
+ opts.onFailure = onDisconnectFailure;
+ opts.context = client;
+ if ((rc = MQTTAsync_disconnect(client, &opts)) != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to start disconnect, return code %d\n", rc);
+ exit(EXIT_FAILURE);
+ }
+}
+
+
+void onConnectFailure(void* context, MQTTAsync_failureData* response)
+{
+ printf("Connect failed, rc %d\n", response ? response->code : 0);
+ finished = 1;
+}
+
+
+void onConnect(void* context, MQTTAsync_successData* response)
+{
+ MQTTAsync client = (MQTTAsync)context;
+ MQTTAsync_responseOptions opts = MQTTAsync_responseOptions_initializer;
+ MQTTAsync_message pubmsg = MQTTAsync_message_initializer;
+ int rc;
+
+ printf("Successful connection\n");
+ opts.onSuccess = onSend;
+ opts.onFailure = onSendFailure;
+ opts.context = client;
+ pubmsg.payload = PAYLOAD;
+ pubmsg.payloadlen = (int)strlen(PAYLOAD);
+ pubmsg.qos = QOS;
+ pubmsg.retained = 0;
+ if ((rc = MQTTAsync_sendMessage(client, TOPIC, &pubmsg, &opts)) != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to start sendMessage, return code %d\n", rc);
+ exit(EXIT_FAILURE);
+ }
+}
+
+int messageArrived(void* context, char* topicName, int topicLen, MQTTAsync_message* m)
+{
+ // not expecting any messages
+ return 1;
+}
+
+int main(int argc, char* argv[])
+{
+ MQTTAsync client;
+ MQTTAsync_connectOptions conn_opts = MQTTAsync_connectOptions_initializer;
+ int rc;
+
+ if ((rc = MQTTAsync_create(&client, ADDRESS, CLIENTID, MQTTCLIENT_PERSISTENCE_NONE, NULL)) != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to create client object, return code %d\n", rc);
+ exit(EXIT_FAILURE);
+ }
+
+ if ((rc = MQTTAsync_setCallbacks(client, NULL, connlost, messageArrived, NULL)) != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to set callback, return code %d\n", rc);
+ exit(EXIT_FAILURE);
+ }
+
+ conn_opts.keepAliveInterval = 20;
+ conn_opts.cleansession = 1;
+ conn_opts.onSuccess = onConnect;
+ conn_opts.onFailure = onConnectFailure;
+ conn_opts.context = client;
+ if ((rc = MQTTAsync_connect(client, &conn_opts)) != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to start connect, return code %d\n", rc);
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Waiting for publication of %s\n"
+ "on topic %s for client with ClientID: %s\n",
+ PAYLOAD, TOPIC, CLIENTID);
+ while (!finished)
+ #if defined(_WIN32)
+ Sleep(100);
+ #else
+ usleep(10000L);
+ #endif
+
+ MQTTAsync_destroy(&client);
+ return rc;
+}
+
+ * @endcode
+ * @page subscribe Subscription example
+@code
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "MQTTAsync.h"
+
+#if !defined(_WIN32)
+#include <unistd.h>
+#else
+#include <windows.h>
+#endif
+
+#if defined(_WRS_KERNEL)
+#include <OsWrapper.h>
+#endif
+
+#define ADDRESS "tcp://mqtt.eclipseprojects.io:1883"
+#define CLIENTID "ExampleClientSub"
+#define TOPIC "MQTT Examples"
+#define PAYLOAD "Hello World!"
+#define QOS 1
+#define TIMEOUT 10000L
+
+int disc_finished = 0;
+int subscribed = 0;
+int finished = 0;
+
+void connlost(void *context, char *cause)
+{
+ MQTTAsync client = (MQTTAsync)context;
+ MQTTAsync_connectOptions conn_opts = MQTTAsync_connectOptions_initializer;
+ int rc;
+
+ printf("\nConnection lost\n");
+ if (cause)
+ printf(" cause: %s\n", cause);
+
+ printf("Reconnecting\n");
+ conn_opts.keepAliveInterval = 20;
+ conn_opts.cleansession = 1;
+ if ((rc = MQTTAsync_connect(client, &conn_opts)) != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to start connect, return code %d\n", rc);
+ finished = 1;
+ }
+}
+
+
+int msgarrvd(void *context, char *topicName, int topicLen, MQTTAsync_message *message)
+{
+ printf("Message arrived\n");
+ printf(" topic: %s\n", topicName);
+ printf(" message: %.*s\n", message->payloadlen, (char*)message->payload);
+ MQTTAsync_freeMessage(&message);
+ MQTTAsync_free(topicName);
+ return 1;
+}
+
+void onDisconnectFailure(void* context, MQTTAsync_failureData* response)
+{
+ printf("Disconnect failed, rc %d\n", response->code);
+ disc_finished = 1;
+}
+
+void onDisconnect(void* context, MQTTAsync_successData* response)
+{
+ printf("Successful disconnection\n");
+ disc_finished = 1;
+}
+
+void onSubscribe(void* context, MQTTAsync_successData* response)
+{
+ printf("Subscribe succeeded\n");
+ subscribed = 1;
+}
+
+void onSubscribeFailure(void* context, MQTTAsync_failureData* response)
+{
+ printf("Subscribe failed, rc %d\n", response->code);
+ finished = 1;
+}
+
+
+void onConnectFailure(void* context, MQTTAsync_failureData* response)
+{
+ printf("Connect failed, rc %d\n", response->code);
+ finished = 1;
+}
+
+
+void onConnect(void* context, MQTTAsync_successData* response)
+{
+ MQTTAsync client = (MQTTAsync)context;
+ MQTTAsync_responseOptions opts = MQTTAsync_responseOptions_initializer;
+ int rc;
+
+ printf("Successful connection\n");
+
+ printf("Subscribing to topic %s\nfor client %s using QoS%d\n\n"
+ "Press Q<Enter> to quit\n\n", TOPIC, CLIENTID, QOS);
+ opts.onSuccess = onSubscribe;
+ opts.onFailure = onSubscribeFailure;
+ opts.context = client;
+ if ((rc = MQTTAsync_subscribe(client, TOPIC, QOS, &opts)) != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to start subscribe, return code %d\n", rc);
+ finished = 1;
+ }
+}
+
+
+int main(int argc, char* argv[])
+{
+ MQTTAsync client;
+ MQTTAsync_connectOptions conn_opts = MQTTAsync_connectOptions_initializer;
+ MQTTAsync_disconnectOptions disc_opts = MQTTAsync_disconnectOptions_initializer;
+ int rc;
+ int ch;
+
+ if ((rc = MQTTAsync_create(&client, ADDRESS, CLIENTID, MQTTCLIENT_PERSISTENCE_NONE, NULL))
+ != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to create client, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ goto exit;
+ }
+
+ if ((rc = MQTTAsync_setCallbacks(client, client, connlost, msgarrvd, NULL)) != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to set callbacks, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ goto destroy_exit;
+ }
+
+ conn_opts.keepAliveInterval = 20;
+ conn_opts.cleansession = 1;
+ conn_opts.onSuccess = onConnect;
+ conn_opts.onFailure = onConnectFailure;
+ conn_opts.context = client;
+ if ((rc = MQTTAsync_connect(client, &conn_opts)) != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to start connect, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ goto destroy_exit;
+ }
+
+ while (!subscribed && !finished)
+ #if defined(_WIN32)
+ Sleep(100);
+ #else
+ usleep(10000L);
+ #endif
+
+ if (finished)
+ goto exit;
+
+ do
+ {
+ ch = getchar();
+ } while (ch!='Q' && ch != 'q');
+
+ disc_opts.onSuccess = onDisconnect;
+ disc_opts.onFailure = onDisconnectFailure;
+ if ((rc = MQTTAsync_disconnect(client, &disc_opts)) != MQTTASYNC_SUCCESS)
+ {
+ printf("Failed to start disconnect, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ goto destroy_exit;
+ }
+ while (!disc_finished)
+ {
+ #if defined(_WIN32)
+ Sleep(100);
+ #else
+ usleep(10000L);
+ #endif
+ }
+
+destroy_exit:
+ MQTTAsync_destroy(&client);
+exit:
+ return rc;
+}
+
+ * @endcode
+* @page tracing Tracing
+ *
+ * Runtime tracing can be controlled by environment variables or API calls.
+ *
+ * #### Environment variables
+ *
+ * Tracing is switched on by setting the MQTT_C_CLIENT_TRACE environment variable.
+ * A value of ON, or stdout, prints to stdout, any other value is interpreted as a file name to use.
+ *
+ * The amount of trace detail is controlled with the MQTT_C_CLIENT_TRACE_LEVEL environment
+ * variable - valid values are ERROR, PROTOCOL, MINIMUM, MEDIUM and MAXIMUM
+ * (from least to most verbose).
+ *
+ * The variable MQTT_C_CLIENT_TRACE_MAX_LINES limits the number of lines of trace that are output
+ * to a file. Two files are used at most, when they are full, the last one is overwritten with the
+ * new trace entries. The default size is 1000 lines.
+ *
+ * #### Trace API calls
+ *
+ * MQTTAsync_traceCallback() is used to set a callback function which is called whenever trace
+ * information is available. This will be the same information as that printed if the
+ * environment variables were used to control the trace.
+ *
+ * The MQTTAsync_setTraceLevel() calls is used to set the maximum level of trace entries that will be
+ * passed to the callback function. The levels are:
+ * 1. ::MQTTASYNC_TRACE_MAXIMUM
+ * 2. ::MQTTASYNC_TRACE_MEDIUM
+ * 3. ::MQTTASYNC_TRACE_MINIMUM
+ * 4. ::MQTTASYNC_TRACE_PROTOCOL
+ * 5. ::MQTTASYNC_TRACE_ERROR
+ * 6. ::MQTTASYNC_TRACE_SEVERE
+ * 7. ::MQTTASYNC_TRACE_FATAL
+ *
+ * Selecting ::MQTTASYNC_TRACE_MAXIMUM will cause all trace entries at all levels to be returned.
+ * Choosing ::MQTTASYNC_TRACE_ERROR will cause ERROR, SEVERE and FATAL trace entries to be returned
+ * to the callback function.
+ *
+ * ### MQTT Packet Tracing
+ *
+ * A feature that can be very useful is printing the MQTT packets that are sent and received. To
+ * achieve this, use the following environment variable settings:
+ * @code
+ MQTT_C_CLIENT_TRACE=ON
+ MQTT_C_CLIENT_TRACE_LEVEL=PROTOCOL
+ * @endcode
+ * The output you should see looks like this:
+ * @code
+ 20130528 155936.813 3 stdout-subscriber -> CONNECT cleansession: 1 (0)
+ 20130528 155936.813 3 stdout-subscriber <- CONNACK rc: 0
+ 20130528 155936.813 3 stdout-subscriber -> SUBSCRIBE msgid: 1 (0)
+ 20130528 155936.813 3 stdout-subscriber <- SUBACK msgid: 1
+ 20130528 155941.818 3 stdout-subscriber -> DISCONNECT (0)
+ * @endcode
+ * where the fields are:
+ * 1. date
+ * 2. time
+ * 3. socket number
+ * 4. client id
+ * 5. direction (-> from client to server, <- from server to client)
+ * 6. packet details
+ *
+ * ### Default Level Tracing
+ *
+ * This is an extract of a default level trace of a call to connect:
+ * @code
+ 19700101 010000.000 (1152206656) (0)> MQTTClient_connect:893
+ 19700101 010000.000 (1152206656) (1)> MQTTClient_connectURI:716
+ 20130528 160447.479 Connecting to serverURI localhost:1883
+ 20130528 160447.479 (1152206656) (2)> MQTTProtocol_connect:98
+ 20130528 160447.479 (1152206656) (3)> MQTTProtocol_addressPort:48
+ 20130528 160447.479 (1152206656) (3)< MQTTProtocol_addressPort:73
+ 20130528 160447.479 (1152206656) (3)> Socket_new:599
+ 20130528 160447.479 New socket 4 for localhost, port 1883
+ 20130528 160447.479 (1152206656) (4)> Socket_addSocket:163
+ 20130528 160447.479 (1152206656) (5)> Socket_setnonblocking:73
+ 20130528 160447.479 (1152206656) (5)< Socket_setnonblocking:78 (0)
+ 20130528 160447.479 (1152206656) (4)< Socket_addSocket:176 (0)
+ 20130528 160447.479 (1152206656) (4)> Socket_error:95
+ 20130528 160447.479 (1152206656) (4)< Socket_error:104 (115)
+ 20130528 160447.479 Connect pending
+ 20130528 160447.479 (1152206656) (3)< Socket_new:683 (115)
+ 20130528 160447.479 (1152206656) (2)< MQTTProtocol_connect:131 (115)
+ * @endcode
+ * where the fields are:
+ * 1. date
+ * 2. time
+ * 3. thread id
+ * 4. function nesting level
+ * 5. function entry (>) or exit (<)
+ * 6. function name : line of source code file
+ * 7. return value (if there is one)
+ *
+ * ### Memory Allocation Tracing
+ *
+ * Setting the trace level to maximum causes memory allocations and frees to be traced along with
+ * the default trace entries, with messages like the following:
+ * @code
+ 20130528 161819.657 Allocating 16 bytes in heap at file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c line 177 ptr 0x179f930
+
+ 20130528 161819.657 Freeing 16 bytes in heap at file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c line 201, heap use now 896 bytes
+ * @endcode
+ * When the last MQTT client object is destroyed, if the trace is being recorded
+ * and all memory allocated by the client library has not been freed, an error message will be
+ * written to the trace. This can help with fixing memory leaks. The message will look like this:
+ * @code
+ 20130528 163909.208 Some memory not freed at shutdown, possible memory leak
+ 20130528 163909.208 Heap scan start, total 880 bytes
+ 20130528 163909.208 Heap element size 32, line 354, file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c, ptr 0x260cb00
+ 20130528 163909.208 Content
+ 20130528 163909.209 Heap scan end
+ * @endcode
+ * @endcond
+ */
+
+#if defined(__cplusplus)
+ }
+#endif
+
+#endif
diff --git a/lib/libpaho-mqtt/include/MQTTClient.h b/lib/libpaho-mqtt/include/MQTTClient.h
new file mode 100644
index 0000000..a5dc7f2
--- /dev/null
+++ b/lib/libpaho-mqtt/include/MQTTClient.h
@@ -0,0 +1,1980 @@
+/*******************************************************************************
+ * Copyright (c) 2009, 2023 IBM Corp., Ian Craggs and others
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v2.0
+ * and Eclipse Distribution License v1.0 which accompany this distribution.
+ *
+ * The Eclipse Public License is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * Contributors:
+ * Ian Craggs - initial API and implementation and/or initial documentation
+ * Ian Craggs, Allan Stockdill-Mander - SSL updates
+ * Ian Craggs - multiple server connection support
+ * Ian Craggs - MQTT 3.1.1 support
+ * Ian Craggs - remove const from eyecatchers #168
+ *******************************************************************************/
+
+/**
+ * @cond MQTTClient_internal
+ * @mainpage MQTT Client Library Internals
+ * In the beginning there was one MQTT C client library, MQTTClient, as implemented in MQTTClient.c
+ * This library was designed to be easy to use for applications which didn't mind if some of the calls
+ * blocked for a while. For instance, the MQTTClient_connect call will block until a successful
+ * connection has completed, or a connection has failed, which could be as long as the "connection
+ * timeout" interval, whose default is 30 seconds.
+ *
+ * However in mobile devices and other windowing environments, blocking on the GUI thread is a bad
+ * thing as it causes the user interface to freeze. Hence a new API, MQTTAsync, implemented
+ * in MQTTAsync.c, was devised. There are no blocking calls in this library, so it is well suited
+ * to GUI and mobile environments, at the expense of some extra complexity.
+ *
+ * Both libraries are designed to be sparing in the use of threads. So multiple client objects are
+ * handled by one or two threads, with a select call in Socket_getReadySocket(), used to determine
+ * when a socket has incoming data. This API is thread safe: functions may be called by multiple application
+ * threads, with the exception of ::MQTTClient_yield and ::MQTTClient_receive, which are intended
+ * for single threaded environments only.
+ *
+ * @endcond
+ * @cond MQTTClient_main
+ * @mainpage MQTT Client library for C (MQTTClient)
+ * © Copyright 2009, 2023 IBM Corp., Ian Craggs and others
+ *
+ * @brief An MQTT client library in C.
+ *
+ * These pages describe the original more synchronous API which might be
+ * considered easier to use. Some of the calls will block. For the new
+ * totally asynchronous API where no calls block, which is especially suitable
+ * for use in windowed environments, see the
+ * <a href="../../MQTTAsync/html/index.html">MQTT C Client Asynchronous API Documentation</a>.
+ * The MQTTClient API is not thread safe, whereas the MQTTAsync API is.
+ *
+ * An MQTT client application connects to MQTT-capable servers.
+ * A typical client is responsible for collecting information from a telemetry
+ * device and publishing the information to the server. It can also subscribe
+ * to topics, receive messages, and use this information to control the
+ * telemetry device.
+ *
+ * MQTT clients implement the published MQTT v3 protocol. You can write your own
+ * API to the MQTT protocol using the programming language and platform of your
+ * choice. This can be time-consuming and error-prone.
+ *
+ * To simplify writing MQTT client applications, this library encapsulates
+ * the MQTT v3 protocol for you. Using this library enables a fully functional
+ * MQTT client application to be written in a few lines of code.
+ * The information presented here documents the API provided
+ * by the MQTT Client library for C.
+ *
+ * <b>Using the client</b><br>
+ * Applications that use the client library typically use a similar structure:
+ * <ul>
+ * <li>Create a client object</li>
+ * <li>Set the options to connect to an MQTT server</li>
+ * <li>Set up callback functions if multi-threaded (asynchronous mode)
+ * operation is being used (see @ref async).</li>
+ * <li>Subscribe to any topics the client needs to receive</li>
+ * <li>Repeat until finished:</li>
+ * <ul>
+ * <li>Publish any messages the client needs to</li>
+ * <li>Handle any incoming messages</li>
+ * </ul>
+ * <li>Disconnect the client</li>
+ * <li>Free any memory being used by the client</li>
+ * </ul>
+ * Some simple examples are shown here:
+ * <ul>
+ * <li>@ref pubsync</li>
+ * <li>@ref pubasync</li>
+ * <li>@ref subasync</li>
+ * </ul>
+ * Additional information about important concepts is provided here:
+ * <ul>
+ * <li>@ref async</li>
+ * <li>@ref callbacks</li>
+ * <li>@ref wildcard</li>
+ * <li>@ref qos</li>
+ * <li>@ref tracing</li>
+ * </ul>
+ * @endcond
+ */
+
+/*
+/// @cond EXCLUDE
+*/
+#if !defined(MQTTCLIENT_H)
+#define MQTTCLIENT_H
+
+#if defined(__cplusplus)
+ extern "C" {
+#endif
+
+#include <stdio.h>
+/*
+/// @endcond
+*/
+
+#include "MQTTExportDeclarations.h"
+
+#include "MQTTProperties.h"
+#include "MQTTReasonCodes.h"
+#include "MQTTSubscribeOpts.h"
+#if !defined(NO_PERSISTENCE)
+#include "MQTTClientPersistence.h"
+#endif
+
+/**
+ * Return code: No error. Indicates successful completion of an MQTT client
+ * operation.
+ */
+#define MQTTCLIENT_SUCCESS 0
+/**
+ * Return code: A generic error code indicating the failure of an MQTT client
+ * operation.
+ */
+#define MQTTCLIENT_FAILURE -1
+
+/* error code -2 is MQTTCLIENT_PERSISTENCE_ERROR */
+
+/**
+ * Return code: The client is disconnected.
+ */
+#define MQTTCLIENT_DISCONNECTED -3
+/**
+ * Return code: The maximum number of messages allowed to be simultaneously
+ * in-flight has been reached.
+ */
+#define MQTTCLIENT_MAX_MESSAGES_INFLIGHT -4
+/**
+ * Return code: An invalid UTF-8 string has been detected.
+ */
+#define MQTTCLIENT_BAD_UTF8_STRING -5
+/**
+ * Return code: A NULL parameter has been supplied when this is invalid.
+ */
+#define MQTTCLIENT_NULL_PARAMETER -6
+/**
+ * Return code: The topic has been truncated (the topic string includes
+ * embedded NULL characters). String functions will not access the full topic.
+ * Use the topic length value to access the full topic.
+ */
+#define MQTTCLIENT_TOPICNAME_TRUNCATED -7
+/**
+ * Return code: A structure parameter does not have the correct eyecatcher
+ * and version number.
+ */
+#define MQTTCLIENT_BAD_STRUCTURE -8
+/**
+ * Return code: A QoS value that falls outside of the acceptable range (0,1,2)
+ */
+#define MQTTCLIENT_BAD_QOS -9
+/**
+ * Return code: Attempting SSL connection using non-SSL version of library
+ */
+#define MQTTCLIENT_SSL_NOT_SUPPORTED -10
+ /**
+ * Return code: unrecognized MQTT version
+ */
+ #define MQTTCLIENT_BAD_MQTT_VERSION -11
+/**
+ * Return code: protocol prefix in serverURI should be:
+ * @li @em tcp:// or @em mqtt:// - Insecure TCP
+ * @li @em ssl:// or @em mqtts:// - Encrypted SSL/TLS
+ * @li @em ws:// - Insecure websockets
+ * @li @em wss:// - Secure web sockets
+ * The TLS enabled prefixes (ssl, mqtts, wss) are only valid if a TLS
+ * version of the library is linked with.
+ */
+#define MQTTCLIENT_BAD_PROTOCOL -14
+ /**
+ * Return code: option not applicable to the requested version of MQTT
+ */
+ #define MQTTCLIENT_BAD_MQTT_OPTION -15
+ /**
+ * Return code: call not applicable to the requested version of MQTT
+ */
+ #define MQTTCLIENT_WRONG_MQTT_VERSION -16
+ /**
+ * Return code: 0 length will topic on connect
+ */
+ #define MQTTCLIENT_0_LEN_WILL_TOPIC -17
+
+
+/**
+ * Default MQTT version to connect with. Use 3.1.1 then fall back to 3.1
+ */
+#define MQTTVERSION_DEFAULT 0
+/**
+ * MQTT version to connect with: 3.1
+ */
+#define MQTTVERSION_3_1 3
+/**
+ * MQTT version to connect with: 3.1.1
+ */
+#define MQTTVERSION_3_1_1 4
+ /**
+ * MQTT version to connect with: 5
+ */
+ #define MQTTVERSION_5 5
+/**
+ * Bad return code from subscribe, as defined in the 3.1.1 specification
+ */
+#define MQTT_BAD_SUBSCRIBE 0x80
+
+/**
+ * Initialization options
+ */
+typedef struct
+{
+ /** The eyecatcher for this structure. Must be MQTG. */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0 */
+ int struct_version;
+ /** 1 = we do openssl init, 0 = leave it to the application */
+ int do_openssl_init;
+} MQTTClient_init_options;
+
+#define MQTTClient_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
+
+/**
+ * Global init of mqtt library. Call once on program start to set global behaviour.
+ * do_openssl_init - if mqtt library should initialize OpenSSL (1) or rely on the caller to do it before using the library (0)
+ */
+LIBMQTT_API void MQTTClient_global_init(MQTTClient_init_options* inits);
+
+/**
+ * A handle representing an MQTT client. A valid client handle is available
+ * following a successful call to MQTTClient_create().
+ */
+typedef void* MQTTClient;
+/**
+ * A value representing an MQTT message. A delivery token is returned to the
+ * client application when a message is published. The token can then be used to
+ * check that the message was successfully delivered to its destination (see
+ * MQTTClient_publish(),
+ * MQTTClient_publishMessage(),
+ * MQTTClient_deliveryComplete(),
+ * MQTTClient_waitForCompletion() and
+ * MQTTClient_getPendingDeliveryTokens()).
+ */
+typedef int MQTTClient_deliveryToken;
+typedef int MQTTClient_token;
+
+/**
+ * A structure representing the payload and attributes of an MQTT message. The
+ * message topic is not part of this structure (see MQTTClient_publishMessage(),
+ * MQTTClient_publish(), MQTTClient_receive(), MQTTClient_freeMessage()
+ * and MQTTClient_messageArrived()).
+ */
+typedef struct
+{
+ /** The eyecatcher for this structure. must be MQTM. */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0 or 1
+ * 0 indicates no message properties */
+ int struct_version;
+ /** The length of the MQTT message payload in bytes. */
+ int payloadlen;
+ /** A pointer to the payload of the MQTT message. */
+ void* payload;
+ /**
+ * The quality of service (QoS) assigned to the message.
+ * There are three levels of QoS:
+ * <DL>
+ * <DT><B>QoS0</B></DT>
+ * <DD>Fire and forget - the message may not be delivered</DD>
+ * <DT><B>QoS1</B></DT>
+ * <DD>At least once - the message will be delivered, but may be
+ * delivered more than once in some circumstances.</DD>
+ * <DT><B>QoS2</B></DT>
+ * <DD>Once and one only - the message will be delivered exactly once.</DD>
+ * </DL>
+ */
+ int qos;
+ /**
+ * The retained flag serves two purposes depending on whether the message
+ * it is associated with is being published or received.
+ *
+ * <b>retained = true</b><br>
+ * For messages being published, a true setting indicates that the MQTT
+ * server should retain a copy of the message. The message will then be
+ * transmitted to new subscribers to a topic that matches the message topic.
+ * For subscribers registering a new subscription, the flag being true
+ * indicates that the received message is not a new one, but one that has
+ * been retained by the MQTT server.
+ *
+ * <b>retained = false</b> <br>
+ * For publishers, this indicates that this message should not be retained
+ * by the MQTT server. For subscribers, a false setting indicates this is
+ * a normal message, received as a result of it being published to the
+ * server.
+ */
+ int retained;
+ /**
+ * The dup flag indicates whether or not this message is a duplicate.
+ * It is only meaningful when receiving QoS1 messages. When true, the
+ * client application should take appropriate action to deal with the
+ * duplicate message.
+ */
+ int dup;
+ /** The message identifier is normally reserved for internal use by the
+ * MQTT client and server.
+ */
+ int msgid;
+ /**
+ * The MQTT V5 properties associated with the message.
+ */
+ MQTTProperties properties;
+} MQTTClient_message;
+
+#define MQTTClient_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer }
+
+/**
+ * This is a callback function. The client application
+ * must provide an implementation of this function to enable asynchronous
+ * receipt of messages. The function is registered with the client library by
+ * passing it as an argument to MQTTClient_setCallbacks(). It is
+ * called by the client library when a new message that matches a client
+ * subscription has been received from the server. This function is executed on
+ * a separate thread to the one on which the client application is running.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * MQTTClient_setCallbacks(), which contains any application-specific context.
+ * @param topicName The topic associated with the received message.
+ * @param topicLen The length of the topic if there are one
+ * more NULL characters embedded in <i>topicName</i>, otherwise <i>topicLen</i>
+ * is 0. If <i>topicLen</i> is 0, the value returned by <i>strlen(topicName)</i>
+ * can be trusted. If <i>topicLen</i> is greater than 0, the full topic name
+ * can be retrieved by accessing <i>topicName</i> as a byte array of length
+ * <i>topicLen</i>.
+ * @param message The MQTTClient_message structure for the received message.
+ * This structure contains the message payload and attributes.
+ * @return This function must return 0 or 1 indicating whether or not
+ * the message has been safely received by the client application. <br>
+ * Returning 1 indicates that the message has been successfully handled.
+ * To free the message storage, ::MQTTClient_freeMessage must be called.
+ * To free the topic name storage, ::MQTTClient_free must be called.<br>
+ * Returning 0 indicates that there was a problem. In this
+ * case, the client library will reinvoke MQTTClient_messageArrived() to
+ * attempt to deliver the message to the application again.
+ * Do not free the message and topic storage when returning 0, otherwise
+ * the redelivery will fail.
+ */
+typedef int MQTTClient_messageArrived(void* context, char* topicName, int topicLen, MQTTClient_message* message);
+
+/**
+ * This is a callback function. The client application
+ * must provide an implementation of this function to enable asynchronous
+ * notification of delivery of messages. The function is registered with the
+ * client library by passing it as an argument to MQTTClient_setCallbacks().
+ * It is called by the client library after the client application has
+ * published a message to the server. It indicates that the necessary
+ * handshaking and acknowledgements for the requested quality of service (see
+ * MQTTClient_message.qos) have been completed. This function is executed on a
+ * separate thread to the one on which the client application is running.
+ * <b>Note:</b>MQTTClient_deliveryComplete() is not called when messages are
+ * published at QoS0.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * MQTTClient_setCallbacks(), which contains any application-specific context.
+ * @param dt The ::MQTTClient_deliveryToken associated with
+ * the published message. Applications can check that all messages have been
+ * correctly published by matching the delivery tokens returned from calls to
+ * MQTTClient_publish() and MQTTClient_publishMessage() with the tokens passed
+ * to this callback.
+ */
+typedef void MQTTClient_deliveryComplete(void* context, MQTTClient_deliveryToken dt);
+
+/**
+ * This is a callback function. The client application
+ * must provide an implementation of this function to enable asynchronous
+ * notification of the loss of connection to the server. The function is
+ * registered with the client library by passing it as an argument to
+ * MQTTClient_setCallbacks(). It is called by the client library if the client
+ * loses its connection to the server. The client application must take
+ * appropriate action, such as trying to reconnect or reporting the problem.
+ * This function is executed on a separate thread to the one on which the
+ * client application is running.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * MQTTClient_setCallbacks(), which contains any application-specific context.
+ * @param cause The reason for the disconnection.
+ * Currently, <i>cause</i> is always set to NULL.
+ */
+typedef void MQTTClient_connectionLost(void* context, char* cause);
+
+/**
+ * This function sets the callback functions for a specific client.
+ * If your client application doesn't use a particular callback, set the
+ * relevant parameter to NULL. Calling MQTTClient_setCallbacks() puts the
+ * client into multi-threaded mode. Any necessary message acknowledgements and
+ * status communications are handled in the background without any intervention
+ * from the client application. See @ref async for more information.
+ *
+ * <b>Note:</b> The MQTT client must be disconnected when this function is
+ * called.
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param context A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to each of the callback functions to
+ * provide access to the context information in the callback.
+ * @param cl A pointer to an MQTTClient_connectionLost() callback
+ * function. You can set this to NULL if your application doesn't handle
+ * disconnections.
+ * @param ma A pointer to an MQTTClient_messageArrived() callback
+ * function. This callback function must be set when you call
+ * MQTTClient_setCallbacks(), as otherwise there would be nowhere to deliver
+ * any incoming messages.
+ * @param dc A pointer to an MQTTClient_deliveryComplete() callback
+ * function. You can set this to NULL if your application publishes
+ * synchronously or if you do not want to check for successful delivery.
+ * @return ::MQTTCLIENT_SUCCESS if the callbacks were correctly set,
+ * ::MQTTCLIENT_FAILURE if an error occurred.
+ */
+LIBMQTT_API int MQTTClient_setCallbacks(MQTTClient handle, void* context, MQTTClient_connectionLost* cl,
+ MQTTClient_messageArrived* ma, MQTTClient_deliveryComplete* dc);
+
+
+/**
+ * This is a callback function, which will be called when the a disconnect
+ * packet is received from the server. This applies to MQTT V5 and above only.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * ::MQTTClient_setDisconnected(), which contains any application-specific context.
+ * @param properties The MQTT V5 properties received with the disconnect, if any.
+ * @param reasonCode The MQTT V5 reason code received with the disconnect.
+ * Currently, <i>cause</i> is always set to NULL.
+ */
+typedef void MQTTClient_disconnected(void* context, MQTTProperties* properties,
+ enum MQTTReasonCodes reasonCode);
+
+/**
+ * Sets the MQTTClient_disconnected() callback function for a client. This will be called
+ * if a disconnect packet is received from the server. Only valid for MQTT V5 and above.
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param context A pointer to any application-specific context. The
+ * the <i>context</i> pointer is passed to each of the callback functions to
+ * provide access to the context information in the callback.
+ * @param co A pointer to an MQTTClient_disconnected() callback
+ * function. NULL removes the callback setting.
+ * @return ::MQTTCLIENT_SUCCESS if the callbacks were correctly set,
+ * ::MQTTCLIENT_FAILURE if an error occurred.
+ */
+LIBMQTT_API int MQTTClient_setDisconnected(MQTTClient handle, void* context, MQTTClient_disconnected* co);
+
+/**
+ * This is a callback function, the MQTT V5 version of MQTTClient_deliveryComplete().
+ * The client application
+ * must provide an implementation of this function to enable asynchronous
+ * notification of the completed delivery of messages.
+ * It is called by the client library after the client application has
+ * published a message to the server. It indicates that the necessary
+ * handshaking and acknowledgements for the requested quality of service (see
+ * MQTTClient_message.qos) have been completed. This function is executed on a
+ * separate thread to the one on which the client application is running.
+ * <b>Note:</b> It is not called when messages are published at QoS0.
+ * @param context A pointer to the <i>context</i> value originally passed to
+ * MQTTClient_setCallbacks(), which contains any application-specific context.
+ * @param dt The ::MQTTClient_deliveryToken associated with
+ * the published message. Applications can check that all messages have been
+ * correctly published by matching the delivery tokens returned from calls to
+ * MQTTClient_publish() and MQTTClient_publishMessage() with the tokens passed
+ * to this callback.
+ * @param packet_type the last received packet type for this completion. For QoS 1
+ * always PUBACK. For QoS 2 could be PUBREC or PUBCOMP.
+ * @param properties the MQTT V5 properties returned with the last packet from the server
+ * @param reasonCode the reason code returned from the server
+ */
+typedef void MQTTClient_published(void* context, int dt, int packet_type, MQTTProperties* properties,
+ enum MQTTReasonCodes reasonCode);
+
+LIBMQTT_API int MQTTClient_setPublished(MQTTClient handle, void* context, MQTTClient_published* co);
+
+/**
+ * This function creates an MQTT client ready for connection to the
+ * specified server and using the specified persistent storage (see
+ * MQTTClient_persistence). See also MQTTClient_destroy().
+ * @param handle A pointer to an ::MQTTClient handle. The handle is
+ * populated with a valid client reference following a successful return from
+ * this function.
+ * @param serverURI A null-terminated string specifying the server to
+ * which the client will connect. It takes the form <i>protocol://host:port</i>.
+ * Currently, <i>protocol</i> must be:
+ * <br>
+ * @em tcp:// or @em mqtt:// - Insecure TCP
+ * <br>
+ * @em ssl:// or @em mqtts:// - Encrypted SSL/TLS
+ * <br>
+ * @em ws:// - Insecure websockets
+ * <br>
+ * @em wss:// - Secure web sockets
+ * <br>
+ * The TLS enabled prefixes (ssl, mqtts, wss) are only valid if a TLS
+ * version of the library is linked with.
+ * For <i>host</i>, you can specify either an IP address or a host name. For
+ * instance, to connect to a server running on the local machines with the
+ * default MQTT port, specify <i>tcp://localhost:1883</i>.
+ * @param clientId The client identifier passed to the server when the
+ * client connects to it. It is a null-terminated UTF-8 encoded string.
+ * @param persistence_type The type of persistence to be used by the client:
+ * <br>
+ * ::MQTTCLIENT_PERSISTENCE_NONE: Use in-memory persistence. If the device or
+ * system on which the client is running fails or is switched off, the current
+ * state of any in-flight messages is lost and some messages may not be
+ * delivered even at QoS1 and QoS2.
+ * <br>
+ * ::MQTTCLIENT_PERSISTENCE_DEFAULT: Use the default (file system-based)
+ * persistence mechanism. Status about in-flight messages is held in persistent
+ * storage and provides some protection against message loss in the case of
+ * unexpected failure.
+ * <br>
+ * ::MQTTCLIENT_PERSISTENCE_USER: Use an application-specific persistence
+ * implementation. Using this type of persistence gives control of the
+ * persistence mechanism to the application. The application has to implement
+ * the MQTTClient_persistence interface.
+ * @param persistence_context If the application uses
+ * ::MQTTCLIENT_PERSISTENCE_NONE persistence, this argument is unused and should
+ * be set to NULL. For ::MQTTCLIENT_PERSISTENCE_DEFAULT persistence, it
+ * should be set to the location of the persistence directory (if set
+ * to NULL, the persistence directory used is the working directory).
+ * Applications that use ::MQTTCLIENT_PERSISTENCE_USER persistence set this
+ * argument to point to a valid MQTTClient_persistence structure.
+ * @return ::MQTTCLIENT_SUCCESS if the client is successfully created, otherwise
+ * an error code is returned.
+ */
+LIBMQTT_API int MQTTClient_create(MQTTClient* handle, const char* serverURI, const char* clientId,
+ int persistence_type, void* persistence_context);
+
+/** Options for the ::MQTTClient_createWithOptions call */
+typedef struct
+{
+ /** The eyecatcher for this structure. must be MQCO. */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0 */
+ int struct_version;
+ /** Whether the MQTT version is 3.1, 3.1.1, or 5. To use V5, this must be set.
+ * MQTT V5 has to be chosen here, because during the create call the message persistence
+ * is initialized, and we want to know whether the format of any persisted messages
+ * is appropriate for the MQTT version we are going to connect with. Selecting 3.1 or
+ * 3.1.1 and attempting to read 5.0 persisted messages will result in an error on create. */
+ int MQTTVersion;
+} MQTTClient_createOptions;
+
+#define MQTTClient_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 0, MQTTVERSION_DEFAULT }
+
+/**
+ * A version of :MQTTClient_create() with additional options.
+ * This function creates an MQTT client ready for connection to the
+ * specified server and using the specified persistent storage (see
+ * MQTTClient_persistence). See also MQTTClient_destroy().
+ * @param handle A pointer to an ::MQTTClient handle. The handle is
+ * populated with a valid client reference following a successful return from
+ * this function.
+ * @param serverURI A null-terminated string specifying the server to
+ * which the client will connect. It takes the form <i>protocol://host:port</i>.
+ * Currently, <i>protocol</i> must be <i>tcp</i> or <i>ssl</i>.
+ * For <i>host</i>, you can
+ * specify either an IP address or a host name. For instance, to connect to
+ * a server running on the local machines with the default MQTT port, specify
+ * <i>tcp://localhost:1883</i>.
+ * @param clientId The client identifier passed to the server when the
+ * client connects to it. It is a null-terminated UTF-8 encoded string.
+ * @param persistence_type The type of persistence to be used by the client:
+ * <br>
+ * ::MQTTCLIENT_PERSISTENCE_NONE: Use in-memory persistence. If the device or
+ * system on which the client is running fails or is switched off, the current
+ * state of any in-flight messages is lost and some messages may not be
+ * delivered even at QoS1 and QoS2.
+ * <br>
+ * ::MQTTCLIENT_PERSISTENCE_DEFAULT: Use the default (file system-based)
+ * persistence mechanism. Status about in-flight messages is held in persistent
+ * storage and provides some protection against message loss in the case of
+ * unexpected failure.
+ * <br>
+ * ::MQTTCLIENT_PERSISTENCE_USER: Use an application-specific persistence
+ * implementation. Using this type of persistence gives control of the
+ * persistence mechanism to the application. The application has to implement
+ * the MQTTClient_persistence interface.
+ * @param persistence_context If the application uses
+ * ::MQTTCLIENT_PERSISTENCE_NONE persistence, this argument is unused and should
+ * be set to NULL. For ::MQTTCLIENT_PERSISTENCE_DEFAULT persistence, it
+ * should be set to the location of the persistence directory (if set
+ * to NULL, the persistence directory used is the working directory).
+ * Applications that use ::MQTTCLIENT_PERSISTENCE_USER persistence set this
+ * argument to point to a valid MQTTClient_persistence structure.
+ * @param options additional options for the create.
+ * @return ::MQTTCLIENT_SUCCESS if the client is successfully created, otherwise
+ * an error code is returned.
+ */
+LIBMQTT_API int MQTTClient_createWithOptions(MQTTClient* handle, const char* serverURI, const char* clientId,
+ int persistence_type, void* persistence_context, MQTTClient_createOptions* options);
+
+/**
+ * MQTTClient_willOptions defines the MQTT "Last Will and Testament" (LWT) settings for
+ * the client. In the event that a client unexpectedly loses its connection to
+ * the server, the server publishes the LWT message to the LWT topic on
+ * behalf of the client. This allows other clients (subscribed to the LWT topic)
+ * to be made aware that the client has disconnected. To enable the LWT
+ * function for a specific client, a valid pointer to an MQTTClient_willOptions
+ * structure is passed in the MQTTClient_connectOptions structure used in the
+ * MQTTClient_connect() call that connects the client to the server. The pointer
+ * to MQTTClient_willOptions can be set to NULL if the LWT function is not
+ * required.
+ */
+typedef struct
+{
+ /** The eyecatcher for this structure. must be MQTW. */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0 or 1
+ 0 means there is no binary payload option
+ */
+ int struct_version;
+ /** The LWT topic to which the LWT message will be published. */
+ const char* topicName;
+ /** The LWT payload in string form. */
+ const char* message;
+ /**
+ * The retained flag for the LWT message (see MQTTClient_message.retained).
+ */
+ int retained;
+ /**
+ * The quality of service setting for the LWT message (see
+ * MQTTClient_message.qos and @ref qos).
+ */
+ int qos;
+ /** The LWT payload in binary form. This is only checked and used if the message option is NULL */
+ struct
+ {
+ int len; /**< binary payload length */
+ const void* data; /**< binary payload data */
+ } payload;
+} MQTTClient_willOptions;
+
+#define MQTTClient_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, {0, NULL} }
+
+#define MQTT_SSL_VERSION_DEFAULT 0
+#define MQTT_SSL_VERSION_TLS_1_0 1
+#define MQTT_SSL_VERSION_TLS_1_1 2
+#define MQTT_SSL_VERSION_TLS_1_2 3
+
+/**
+* MQTTClient_sslProperties defines the settings to establish an SSL/TLS connection using the
+* OpenSSL library. It covers the following scenarios:
+* - Server authentication: The client needs the digital certificate of the server. It is included
+* in a store containting trusted material (also known as "trust store").
+* - Mutual authentication: Both client and server are authenticated during the SSL handshake. In
+* addition to the digital certificate of the server in a trust store, the client will need its own
+* digital certificate and the private key used to sign its digital certificate stored in a "key store".
+* - Anonymous connection: Both client and server do not get authenticated and no credentials are needed
+* to establish an SSL connection. Note that this scenario is not fully secure since it is subject to
+* man-in-the-middle attacks.
+*/
+typedef struct
+{
+ /** The eyecatcher for this structure. Must be MQTS */
+ char struct_id[4];
+
+ /** The version number of this structure. Must be 0, 1, 2, 3, 4 or 5.
+ * 0 means no sslVersion
+ * 1 means no verify, CApath
+ * 2 means no ssl_error_context, ssl_error_cb
+ * 3 means no ssl_psk_cb, ssl_psk_context, disableDefaultTrustStore
+ * 4 means no protos, protos_len
+ */
+ int struct_version;
+
+ /** The file in PEM format containing the public digital certificates trusted by the client. */
+ const char* trustStore;
+
+ /** The file in PEM format containing the public certificate chain of the client. It may also include
+ * the client's private key.
+ */
+ const char* keyStore;
+
+ /** If not included in the sslKeyStore, this setting points to the file in PEM format containing
+ * the client's private key.
+ */
+ const char* privateKey;
+
+ /** The password to load the client's privateKey if encrypted. */
+ const char* privateKeyPassword;
+
+ /**
+ * The list of cipher suites that the client will present to the server during the SSL handshake. For a
+ * full explanation of the cipher list format, please see the OpenSSL on-line documentation:
+ * http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT
+ * If this setting is ommitted, its default value will be "ALL", that is, all the cipher suites -excluding
+ * those offering no encryption- will be considered.
+ * This setting can be used to set an SSL anonymous connection ("aNULL" string value, for instance).
+ */
+ const char* enabledCipherSuites;
+
+ /** True/False option to enable verification of the server certificate **/
+ int enableServerCertAuth;
+
+ /** The SSL/TLS version to use. Specify one of MQTT_SSL_VERSION_DEFAULT (0),
+ * MQTT_SSL_VERSION_TLS_1_0 (1), MQTT_SSL_VERSION_TLS_1_1 (2) or MQTT_SSL_VERSION_TLS_1_2 (3).
+ * Only used if struct_version is >= 1.
+ */
+ int sslVersion;
+
+ /**
+ * Whether to carry out post-connect checks, including that a certificate
+ * matches the given host name.
+ * Exists only if struct_version >= 2
+ */
+ int verify;
+
+ /**
+ * From the OpenSSL documentation:
+ * If CApath is not NULL, it points to a directory containing CA certificates in PEM format.
+ * Exists only if struct_version >= 2
+ */
+ const char* CApath;
+
+ /**
+ * Callback function for OpenSSL error handler ERR_print_errors_cb
+ * Exists only if struct_version >= 3
+ */
+ int (*ssl_error_cb) (const char *str, size_t len, void *u);
+
+ /**
+ * Application-specific contex for OpenSSL error handler ERR_print_errors_cb
+ * Exists only if struct_version >= 3
+ */
+ void* ssl_error_context;
+
+ /**
+ * Callback function for setting TLS-PSK options. Parameters correspond to that of
+ * SSL_CTX_set_psk_client_callback, except for u which is the pointer ssl_psk_context.
+ * Exists only if struct_version >= 4
+ */
+ unsigned int (*ssl_psk_cb) (const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len, void *u);
+
+ /**
+ * Application-specific contex for ssl_psk_cb
+ * Exists only if struct_version >= 4
+ */
+ void* ssl_psk_context;
+
+ /**
+ * Don't load default SSL CA. Should be used together with PSK to make sure
+ * regular servers with certificate in place is not accepted.
+ * Exists only if struct_version >= 4
+ */
+ int disableDefaultTrustStore;
+
+ /**
+ * The protocol-lists must be in wire-format, which is defined as a vector of non-empty, 8-bit length-prefixed, byte strings.
+ * The length-prefix byte is not included in the length. Each string is limited to 255 bytes. A byte-string length of 0 is invalid.
+ * A truncated byte-string is invalid.
+ * Check documentation for SSL_CTX_set_alpn_protos
+ * Exists only if struct_version >= 5
+ */
+ const unsigned char *protos;
+
+ /**
+ * The length of the vector protos vector
+ * Exists only if struct_version >= 5
+ */
+ unsigned int protos_len;
+} MQTTClient_SSLOptions;
+
+#define MQTTClient_SSLOptions_initializer { {'M', 'Q', 'T', 'S'}, 5, NULL, NULL, NULL, NULL, NULL, 1, MQTT_SSL_VERSION_DEFAULT, 0, NULL, NULL, NULL, NULL, NULL, 0, NULL, 0 }
+
+/**
+ * MQTTClient_libraryInfo is used to store details relating to the currently used
+ * library such as the version in use, the time it was built and relevant openSSL
+ * options.
+ * There is one static instance of this struct in MQTTClient.c
+ */
+
+typedef struct
+{
+ const char* name;
+ const char* value;
+} MQTTClient_nameValue;
+
+/**
+ * This function returns version information about the library.
+ * no trace information will be returned.
+ * @return an array of strings describing the library. The last entry is a NULL pointer.
+ */
+LIBMQTT_API MQTTClient_nameValue* MQTTClient_getVersionInfo(void);
+
+/**
+ * MQTTClient_connectOptions defines several settings that control the way the
+ * client connects to an MQTT server.
+ *
+ * <b>Note:</b> Default values are not defined for members of
+ * MQTTClient_connectOptions so it is good practice to specify all settings.
+ * If the MQTTClient_connectOptions structure is defined as an automatic
+ * variable, all members are set to random values and thus must be set by the
+ * client application. If the MQTTClient_connectOptions structure is defined
+ * as a static variable, initialization (in compliant compilers) sets all
+ * values to 0 (NULL for pointers). A #keepAliveInterval setting of 0 prevents
+ * correct operation of the client and so you <b>must</b> at least set a value
+ * for #keepAliveInterval.
+ *
+ * Suitable default values are set in the following initializers:
+ * - MQTTClient_connectOptions_initializer: for MQTT 3.1.1 non-WebSockets
+ * - MQTTClient_connectOptions_initializer5: for MQTT 5.0 non-WebSockets
+ * - MQTTClient_connectOptions_initializer_ws: for MQTT 3.1.1 WebSockets
+ * - MQTTClient_connectOptions_initializer5_ws: for MQTT 5.0 WebSockets
+ */
+typedef struct
+{
+ /** The eyecatcher for this structure. must be MQTC. */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0, 1, 2, 3, 4, 5, 6, 7 or 8.
+ * 0 signifies no SSL options and no serverURIs
+ * 1 signifies no serverURIs
+ * 2 signifies no MQTTVersion
+ * 3 signifies no returned values
+ * 4 signifies no binary password option
+ * 5 signifies no maxInflightMessages and cleanstart
+ * 6 signifies no HTTP headers option
+ * 7 signifies no HTTP proxy and HTTPS proxy options
+ */
+ int struct_version;
+ /** The "keep alive" interval, measured in seconds, defines the maximum time
+ * that should pass without communication between the client and the server
+ * The client will ensure that at least one message travels across the
+ * network within each keep alive period. In the absence of a data-related
+ * message during the time period, the client sends a very small MQTT
+ * "ping" message, which the server will acknowledge. The keep alive
+ * interval enables the client to detect when the server is no longer
+ * available without having to wait for the long TCP/IP timeout.
+ */
+ int keepAliveInterval;
+ /**
+ * This is a boolean value. The cleansession setting controls the behaviour
+ * of both the client and the server at connection and disconnection time.
+ * The client and server both maintain session state information. This
+ * information is used to ensure "at least once" and "exactly once"
+ * delivery, and "exactly once" receipt of messages. Session state also
+ * includes subscriptions created by an MQTT client. You can choose to
+ * maintain or discard state information between sessions.
+ *
+ * When cleansession is true, the state information is discarded at
+ * connect and disconnect. Setting cleansession to false keeps the state
+ * information. When you connect an MQTT client application with
+ * MQTTClient_connect(), the client identifies the connection using the
+ * client identifier and the address of the server. The server checks
+ * whether session information for this client
+ * has been saved from a previous connection to the server. If a previous
+ * session still exists, and cleansession=true, then the previous session
+ * information at the client and server is cleared. If cleansession=false,
+ * the previous session is resumed. If no previous session exists, a new
+ * session is started.
+ */
+ int cleansession;
+ /**
+ * This is a boolean value that controls how many messages can be in-flight
+ * simultaneously. Setting <i>reliable</i> to true means that a published
+ * message must be completed (acknowledgements received) before another
+ * can be sent. Attempts to publish additional messages receive an
+ * ::MQTTCLIENT_MAX_MESSAGES_INFLIGHT return code. Setting this flag to
+ * false allows up to 10 messages to be in-flight. This can increase
+ * overall throughput in some circumstances.
+ */
+ int reliable;
+ /**
+ * This is a pointer to an MQTTClient_willOptions structure. If your
+ * application does not make use of the Last Will and Testament feature,
+ * set this pointer to NULL.
+ */
+ MQTTClient_willOptions* will;
+ /**
+ * MQTT servers that support the MQTT v3.1.1 protocol provide authentication
+ * and authorisation by user name and password. This is the user name
+ * parameter.
+ */
+ const char* username;
+ /**
+ * MQTT servers that support the MQTT v3.1.1 protocol provide authentication
+ * and authorisation by user name and password. This is the password
+ * parameter.
+ */
+ const char* password;
+ /**
+ * The time interval in seconds to allow a connect to complete.
+ */
+ int connectTimeout;
+ /**
+ * The time interval in seconds after which unacknowledged publish requests are
+ * retried during a TCP session. With MQTT 3.1.1 and later, retries are
+ * not required except on reconnect. 0 turns off in-session retries, and is the
+ * recommended setting. Adding retries to an already overloaded network only
+ * exacerbates the problem.
+ */
+ int retryInterval;
+ /**
+ * This is a pointer to an MQTTClient_SSLOptions structure. If your
+ * application does not make use of SSL, set this pointer to NULL.
+ */
+ MQTTClient_SSLOptions* ssl;
+ /**
+ * The number of entries in the optional serverURIs array. Defaults to 0.
+ */
+ int serverURIcount;
+ /**
+ * An optional array of null-terminated strings specifying the servers to
+ * which the client will connect. Each string takes the form <i>protocol://host:port</i>.
+ * <i>protocol</i> must be <i>tcp</i>, <i>ssl</i>, <i>ws</i> or <i>wss</i>.
+ * The TLS enabled prefixes (ssl, wss) are only valid if a TLS version of the library
+ * is linked with.
+ * For <i>host</i>, you can
+ * specify either an IP address or a host name. For instance, to connect to
+ * a server running on the local machines with the default MQTT port, specify
+ * <i>tcp://localhost:1883</i>.
+ * If this list is empty (the default), the server URI specified on MQTTClient_create()
+ * is used.
+ */
+ char* const* serverURIs;
+ /**
+ * Sets the version of MQTT to be used on the connect.
+ * MQTTVERSION_DEFAULT (0) = default: start with 3.1.1, and if that fails, fall back to 3.1
+ * MQTTVERSION_3_1 (3) = only try version 3.1
+ * MQTTVERSION_3_1_1 (4) = only try version 3.1.1
+ * MQTTVERSION_5 (5) = only try version 5.0
+ */
+ int MQTTVersion;
+ /**
+ * Returned from the connect when the MQTT version used to connect is 3.1.1
+ */
+ struct
+ {
+ const char* serverURI; /**< the serverURI connected to */
+ int MQTTVersion; /**< the MQTT version used to connect with */
+ int sessionPresent; /**< if the MQTT version is 3.1.1, the value of sessionPresent returned in the connack */
+ } returned;
+ /**
+ * Optional binary password. Only checked and used if the password option is NULL
+ */
+ struct
+ {
+ int len; /**< binary password length */
+ const void* data; /**< binary password data */
+ } binarypwd;
+ /**
+ * The maximum number of messages in flight
+ */
+ int maxInflightMessages;
+ /*
+ * MQTT V5 clean start flag. Only clears state at the beginning of the session.
+ */
+ int cleanstart;
+ /**
+ * HTTP headers for websockets
+ */
+ const MQTTClient_nameValue* httpHeaders;
+ /**
+ * HTTP proxy
+ */
+ const char* httpProxy;
+ /**
+ * HTTPS proxy
+ */
+ const char* httpsProxy;
+} MQTTClient_connectOptions;
+
+/** Initializer for connect options for MQTT 3.1.1 non-WebSocket connections */
+#define MQTTClient_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 8, 60, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\
+0, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL}
+
+/** Initializer for connect options for MQTT 5.0 non-WebSocket connections */
+#define MQTTClient_connectOptions_initializer5 { {'M', 'Q', 'T', 'C'}, 8, 60, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\
+0, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL}
+
+/** Initializer for connect options for MQTT 3.1.1 WebSockets connections.
+ * The keepalive interval is set to 45 seconds to avoid webserver 60 second inactivity timeouts.
+ */
+#define MQTTClient_connectOptions_initializer_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\
+0, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL}
+
+/** Initializer for connect options for MQTT 5.0 WebSockets connections.
+ * The keepalive interval is set to 45 seconds to avoid webserver 60 second inactivity timeouts.
+ */
+#define MQTTClient_connectOptions_initializer5_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\
+0, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL}
+
+/**
+ * This function attempts to connect a previously-created client (see
+ * MQTTClient_create()) to an MQTT server using the specified options. If you
+ * want to enable asynchronous message and status notifications, you must call
+ * MQTTClient_setCallbacks() prior to MQTTClient_connect().
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param options A pointer to a valid MQTTClient_connectOptions
+ * structure.
+ * @return ::MQTTCLIENT_SUCCESS if the client successfully connects to the
+ * server. An error code is returned if the client was unable to connect to
+ * the server.
+ * Error codes greater than 0 are returned by the MQTT protocol:<br><br>
+ * <b>1</b>: Connection refused: Unacceptable protocol version<br>
+ * <b>2</b>: Connection refused: Identifier rejected<br>
+ * <b>3</b>: Connection refused: Server unavailable<br>
+ * <b>4</b>: Connection refused: Bad user name or password<br>
+ * <b>5</b>: Connection refused: Not authorized<br>
+ * <b>6-255</b>: Reserved for future use<br>
+ */
+LIBMQTT_API int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions* options);
+
+/** MQTT version 5.0 response information */
+typedef struct MQTTResponse
+{
+ int version; /* the version number of this structure */
+ enum MQTTReasonCodes reasonCode; /* the MQTT 5.0 reason code returned */
+ int reasonCodeCount; /* the number of reason codes. Used for subscribeMany5 and unsubscribeMany5 */
+ enum MQTTReasonCodes* reasonCodes; /* a list of reason codes. Used for subscribeMany5 and unsubscribeMany5 */
+ MQTTProperties* properties; /* optionally, the MQTT 5.0 properties returned */
+} MQTTResponse;
+
+#define MQTTResponse_initializer {1, MQTTREASONCODE_SUCCESS, 0, NULL, NULL}
+
+/**
+ * Frees the storage associated with the MQTT response.
+ * @param response the response structure to be freed
+ */
+LIBMQTT_API void MQTTResponse_free(MQTTResponse response);
+
+/**
+ * Attempts to connect a previously-created client (see
+ * MQTTClient_create()) to an MQTT server using MQTT version 5.0 and the specified options. If you
+ * want to enable asynchronous message and status notifications, you must call
+ * MQTTClient_setCallbacks() prior to MQTTClient_connect().
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param options A pointer to a valid MQTTClient_connectOptions
+ * structure.
+ * @param connectProperties the MQTT 5.0 connect properties to use
+ * @param willProperties the MQTT 5.0 properties to set on the will message
+ * @return the MQTT 5.0 response information: error codes and properties.
+ */
+LIBMQTT_API MQTTResponse MQTTClient_connect5(MQTTClient handle, MQTTClient_connectOptions* options,
+ MQTTProperties* connectProperties, MQTTProperties* willProperties);
+
+/**
+ * This function attempts to disconnect the client from the MQTT
+ * server. In order to allow the client time to complete handling of messages
+ * that are in-flight when this function is called, a timeout period is
+ * specified. When the timeout period has expired, the client disconnects even
+ * if there are still outstanding message acknowledgements.
+ * The next time the client connects to the same server, any QoS 1 or 2
+ * messages which have not completed will be retried depending on the
+ * cleansession settings for both the previous and the new connection (see
+ * MQTTClient_connectOptions.cleansession and MQTTClient_connect()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param timeout The client delays disconnection for up to this time (in
+ * milliseconds) in order to allow in-flight message transfers to complete.
+ * @return ::MQTTCLIENT_SUCCESS if the client successfully disconnects from
+ * the server. An error code is returned if the client was unable to disconnect
+ * from the server
+ */
+LIBMQTT_API int MQTTClient_disconnect(MQTTClient handle, int timeout);
+
+LIBMQTT_API int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties* props);
+
+/**
+ * This function allows the client application to test whether or not a
+ * client is currently connected to the MQTT server.
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @return Boolean true if the client is connected, otherwise false.
+ */
+LIBMQTT_API int MQTTClient_isConnected(MQTTClient handle);
+
+
+/* Subscribe is synchronous. QoS list parameter is changed on return to granted QoSs.
+ Returns return code, MQTTCLIENT_SUCCESS == success, non-zero some sort of error (TBD) */
+
+/**
+ * This function attempts to subscribe a client to a single topic, which may
+ * contain wildcards (see @ref wildcard). This call also specifies the
+ * @ref qos requested for the subscription
+ * (see also MQTTClient_subscribeMany()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param topic The subscription topic, which may include wildcards.
+ * @param qos The requested quality of service for the subscription.
+ * @return ::MQTTCLIENT_SUCCESS if the subscription request is successful.
+ * An error code is returned if there was a problem registering the
+ * subscription.
+ */
+LIBMQTT_API int MQTTClient_subscribe(MQTTClient handle, const char* topic, int qos);
+
+/**
+ * This function attempts to subscribe an MQTT version 5.0 client to a single topic, which may
+ * contain wildcards (see @ref wildcard). This call also specifies the
+ * @ref qos requested for the subscription
+ * (see also MQTTClient_subscribeMany()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param topic The subscription topic, which may include wildcards.
+ * @param qos The requested quality of service for the subscription.
+ * @param opts the MQTT 5.0 subscribe options to be used
+ * @param props the MQTT 5.0 properties to be used
+ * @return the MQTT 5.0 response information: error codes and properties.
+ */
+LIBMQTT_API MQTTResponse MQTTClient_subscribe5(MQTTClient handle, const char* topic, int qos,
+ MQTTSubscribe_options* opts, MQTTProperties* props);
+
+/**
+ * This function attempts to subscribe a client to a list of topics, which may
+ * contain wildcards (see @ref wildcard). This call also specifies the
+ * @ref qos requested for each topic (see also MQTTClient_subscribe()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param count The number of topics for which the client is requesting
+ * subscriptions.
+ * @param topic An array (of length <i>count</i>) of pointers to
+ * topics, each of which may include wildcards.
+ * @param qos An array (of length <i>count</i>) of @ref qos
+ * values. qos[n] is the requested QoS for topic[n].
+ * @return ::MQTTCLIENT_SUCCESS if the subscription request is successful.
+ * An error code is returned if there was a problem registering the
+ * subscriptions.
+ */
+LIBMQTT_API int MQTTClient_subscribeMany(MQTTClient handle, int count, char* const* topic, int* qos);
+
+/**
+ * This function attempts to subscribe an MQTT version 5.0 client to a list of topics, which may
+ * contain wildcards (see @ref wildcard). This call also specifies the
+ * @ref qos requested for each topic (see also MQTTClient_subscribe()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param count The number of topics for which the client is requesting
+ * subscriptions.
+ * @param topic An array (of length <i>count</i>) of pointers to
+ * topics, each of which may include wildcards.
+ * @param qos An array (of length <i>count</i>) of @ref qos
+ * values. qos[n] is the requested QoS for topic[n].
+ * @param opts the MQTT 5.0 subscribe options to be used
+ * @param props the MQTT 5.0 properties to be used
+ * @return the MQTT 5.0 response information: error codes and properties.
+ */
+LIBMQTT_API MQTTResponse MQTTClient_subscribeMany5(MQTTClient handle, int count, char* const* topic,
+ int* qos, MQTTSubscribe_options* opts, MQTTProperties* props);
+
+/**
+ * This function attempts to remove an existing subscription made by the
+ * specified client.
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param topic The topic for the subscription to be removed, which may
+ * include wildcards (see @ref wildcard).
+ * @return ::MQTTCLIENT_SUCCESS if the subscription is removed.
+ * An error code is returned if there was a problem removing the
+ * subscription.
+ */
+LIBMQTT_API int MQTTClient_unsubscribe(MQTTClient handle, const char* topic);
+
+/**
+ * This function attempts to remove an existing subscription made by the
+ * specified client using MQTT 5.0.
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param topic The topic for the subscription to be removed, which may
+ * include wildcards (see @ref wildcard).
+ * @param props the MQTT 5.0 properties to be used
+ * @return the MQTT 5.0 response information: error codes and properties.
+ */
+LIBMQTT_API MQTTResponse MQTTClient_unsubscribe5(MQTTClient handle, const char* topic, MQTTProperties* props);
+
+/**
+ * This function attempts to remove existing subscriptions to a list of topics
+ * made by the specified client.
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param count The number subscriptions to be removed.
+ * @param topic An array (of length <i>count</i>) of pointers to the topics of
+ * the subscriptions to be removed, each of which may include wildcards.
+ * @return ::MQTTCLIENT_SUCCESS if the subscriptions are removed.
+ * An error code is returned if there was a problem removing the subscriptions.
+ */
+LIBMQTT_API int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char* const* topic);
+
+/**
+ * This function attempts to remove existing subscriptions to a list of topics
+ * made by the specified client using MQTT version 5.0.
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param count The number subscriptions to be removed.
+ * @param topic An array (of length <i>count</i>) of pointers to the topics of
+ * the subscriptions to be removed, each of which may include wildcards.
+ * @param props the MQTT 5.0 properties to be used
+ * @return the MQTT 5.0 response information: error codes and properties.
+ */
+LIBMQTT_API MQTTResponse MQTTClient_unsubscribeMany5(MQTTClient handle, int count, char* const* topic, MQTTProperties* props);
+
+/**
+ * This function attempts to publish a message to a given topic (see also
+ * MQTTClient_publishMessage()). An ::MQTTClient_deliveryToken is issued when
+ * this function returns successfully. If the client application needs to
+ * test for succesful delivery of QoS1 and QoS2 messages, this can be done
+ * either asynchronously or synchronously (see @ref async,
+ * ::MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param topicName The topic associated with this message.
+ * @param payloadlen The length of the payload in bytes.
+ * @param payload A pointer to the byte array payload of the message.
+ * @param qos The @ref qos of the message.
+ * @param retained The retained flag for the message.
+ * @param dt A pointer to an ::MQTTClient_deliveryToken. This is populated
+ * with a token representing the message when the function returns
+ * successfully. If your application does not use delivery tokens, set this
+ * argument to NULL.
+ * @return ::MQTTCLIENT_SUCCESS if the message is accepted for publication.
+ * An error code is returned if there was a problem accepting the message.
+ */
+LIBMQTT_API int MQTTClient_publish(MQTTClient handle, const char* topicName, int payloadlen, const void* payload, int qos, int retained,
+ MQTTClient_deliveryToken* dt);
+
+/**
+ * Attempts to publish a message to a given topic using MQTT version 5.0 (see also
+ * MQTTClient_publishMessage5()). An ::MQTTClient_deliveryToken is issued when
+ * this function returns successfully. If the client application needs to
+ * test for succesful delivery of QoS1 and QoS2 messages, this can be done
+ * either asynchronously or synchronously (see @ref async,
+ * ::MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param topicName The topic associated with this message.
+ * @param payloadlen The length of the payload in bytes.
+ * @param payload A pointer to the byte array payload of the message.
+ * @param qos The @ref qos of the message.
+ * @param retained The retained flag for the message.
+ * @param properties the MQTT 5.0 properties to be used
+ * @param dt A pointer to an ::MQTTClient_deliveryToken. This is populated
+ * with a token representing the message when the function returns
+ * successfully. If your application does not use delivery tokens, set this
+ * argument to NULL.
+ * @return the MQTT 5.0 response information: error codes and properties.
+ */
+LIBMQTT_API MQTTResponse MQTTClient_publish5(MQTTClient handle, const char* topicName, int payloadlen, const void* payload,
+ int qos, int retained, MQTTProperties* properties, MQTTClient_deliveryToken* dt);
+/**
+ * This function attempts to publish a message to a given topic (see also
+ * MQTTClient_publish()). An ::MQTTClient_deliveryToken is issued when
+ * this function returns successfully. If the client application needs to
+ * test for succesful delivery of QoS1 and QoS2 messages, this can be done
+ * either asynchronously or synchronously (see @ref async,
+ * ::MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param topicName The topic associated with this message.
+ * @param msg A pointer to a valid MQTTClient_message structure containing
+ * the payload and attributes of the message to be published.
+ * @param dt A pointer to an ::MQTTClient_deliveryToken. This is populated
+ * with a token representing the message when the function returns
+ * successfully. If your application does not use delivery tokens, set this
+ * argument to NULL.
+ * @return ::MQTTCLIENT_SUCCESS if the message is accepted for publication.
+ * An error code is returned if there was a problem accepting the message.
+ */
+LIBMQTT_API int MQTTClient_publishMessage(MQTTClient handle, const char* topicName, MQTTClient_message* msg, MQTTClient_deliveryToken* dt);
+
+
+/**
+ * Attempts to publish a message to the given topic using MQTT version 5.0
+ * (see also
+ * MQTTClient_publish5()). An ::MQTTClient_deliveryToken is issued when
+ * this function returns successfully. If the client application needs to
+ * test for succesful delivery of QoS1 and QoS2 messages, this can be done
+ * either asynchronously or synchronously (see @ref async,
+ * ::MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param topicName The topic associated with this message.
+ * @param msg A pointer to a valid MQTTClient_message structure containing
+ * the payload and attributes of the message to be published.
+ * @param dt A pointer to an ::MQTTClient_deliveryToken. This is populated
+ * with a token representing the message when the function returns
+ * successfully. If your application does not use delivery tokens, set this
+ * argument to NULL.
+ * @return the MQTT 5.0 response information: error codes and properties.
+ */
+LIBMQTT_API MQTTResponse MQTTClient_publishMessage5(MQTTClient handle, const char* topicName, MQTTClient_message* msg,
+ MQTTClient_deliveryToken* dt);
+
+/**
+ * This function is called by the client application to synchronize execution
+ * of the main thread with completed publication of a message. When called,
+ * MQTTClient_waitForCompletion() blocks execution until the message has been
+ * successful delivered or the specified timeout has expired. See @ref async.
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param dt The ::MQTTClient_deliveryToken that represents the message being
+ * tested for successful delivery. Delivery tokens are issued by the
+ * publishing functions MQTTClient_publish() and MQTTClient_publishMessage().
+ * @param timeout The maximum time to wait in milliseconds.
+ * @return ::MQTTCLIENT_SUCCESS if the message was successfully delivered.
+ * An error code is returned if the timeout expires or there was a problem
+ * checking the token.
+ */
+LIBMQTT_API int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout);
+
+
+/**
+ * This function sets a pointer to an array of delivery tokens for
+ * messages that are currently in-flight (pending completion).
+ *
+ * <b>Important note:</b> The memory used to hold the array of tokens is
+ * malloc()'d in this function. The client application is responsible for
+ * freeing this memory when it is no longer required.
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param tokens The address of a pointer to an ::MQTTClient_deliveryToken.
+ * When the function returns successfully, the pointer is set to point to an
+ * array of tokens representing messages pending completion. The last member of
+ * the array is set to -1 to indicate there are no more tokens. If no tokens
+ * are pending, the pointer is set to NULL.
+ * @return ::MQTTCLIENT_SUCCESS if the function returns successfully.
+ * An error code is returned if there was a problem obtaining the list of
+ * pending tokens.
+ */
+LIBMQTT_API int MQTTClient_getPendingDeliveryTokens(MQTTClient handle, MQTTClient_deliveryToken **tokens);
+
+/**
+ * When implementing a single-threaded client, call this function periodically
+ * to allow processing of message retries and to send MQTT keepalive pings.
+ * If the application is calling MQTTClient_receive() regularly, then it is
+ * not necessary to call this function.
+ */
+LIBMQTT_API void MQTTClient_yield(void);
+
+/**
+ * This function performs a synchronous receive of incoming messages. It should
+ * be used only when the client application has not set callback methods to
+ * support asynchronous receipt of messages (see @ref async and
+ * MQTTClient_setCallbacks()). Using this function allows a single-threaded
+ * client subscriber application to be written. When called, this function
+ * blocks until the next message arrives or the specified timeout expires
+ *(see also MQTTClient_yield()).
+ *
+ * <b>Important note:</b> The application must free() the memory allocated
+ * to the topic and the message when processing is complete (see
+ * MQTTClient_freeMessage()).
+ * @param handle A valid client handle from a successful call to
+ * MQTTClient_create().
+ * @param topicName The address of a pointer to a topic. This function
+ * allocates the memory for the topic and returns it to the application
+ * by setting <i>topicName</i> to point to the topic.
+ * @param topicLen The length of the topic. If the return code from this
+ * function is ::MQTTCLIENT_TOPICNAME_TRUNCATED, the topic contains embedded
+ * NULL characters and the full topic should be retrieved by using
+ * <i>topicLen</i>.
+ * @param message The address of a pointer to the received message. This
+ * function allocates the memory for the message and returns it to the
+ * application by setting <i>message</i> to point to the received message.
+ * The pointer is set to NULL if the timeout expires.
+ * @param timeout The length of time to wait for a message in milliseconds.
+ * @return ::MQTTCLIENT_SUCCESS or ::MQTTCLIENT_TOPICNAME_TRUNCATED if a
+ * message is received. ::MQTTCLIENT_SUCCESS can also indicate that the
+ * timeout expired, in which case <i>message</i> is NULL. An error code is
+ * returned if there was a problem trying to receive a message.
+ */
+LIBMQTT_API int MQTTClient_receive(MQTTClient handle, char** topicName, int* topicLen, MQTTClient_message** message,
+ unsigned long timeout);
+
+/**
+ * This function frees memory allocated to an MQTT message, including the
+ * additional memory allocated to the message payload. The client application
+ * calls this function when the message has been fully processed. <b>Important
+ * note:</b> This function does not free the memory allocated to a message
+ * topic string. It is the responsibility of the client application to free
+ * this memory using the MQTTClient_free() library function.
+ * @param msg The address of a pointer to the ::MQTTClient_message structure
+ * to be freed.
+ */
+LIBMQTT_API void MQTTClient_freeMessage(MQTTClient_message** msg);
+
+/**
+ * This function frees memory allocated by the MQTT C client library, especially the
+ * topic name. This is needed on Windows when the client libary and application
+ * program have been compiled with different versions of the C compiler. It is
+ * thus good policy to always use this function when freeing any MQTT C client-
+ * allocated memory.
+ * @param ptr The pointer to the client library storage to be freed.
+ */
+LIBMQTT_API void MQTTClient_free(void* ptr);
+
+/**
+ * This function is used to allocate memory to be used or freed by the MQTT C client library,
+ * especially the data in user persistence. This is needed on Windows when the client library
+ * and application program have been compiled with different versions of the C compiler.
+ * @param size The size of the memory to be allocated.
+ */
+LIBMQTT_API void* MQTTClient_malloc(size_t size);
+
+/**
+ * This function frees the memory allocated to an MQTT client (see
+ * MQTTClient_create()). It should be called when the client is no longer
+ * required.
+ * @param handle A pointer to the handle referring to the ::MQTTClient
+ * structure to be freed.
+ */
+LIBMQTT_API void MQTTClient_destroy(MQTTClient* handle);
+
+
+enum MQTTCLIENT_TRACE_LEVELS
+{
+ MQTTCLIENT_TRACE_MAXIMUM = 1,
+ MQTTCLIENT_TRACE_MEDIUM,
+ MQTTCLIENT_TRACE_MINIMUM,
+ MQTTCLIENT_TRACE_PROTOCOL,
+ MQTTCLIENT_TRACE_ERROR,
+ MQTTCLIENT_TRACE_SEVERE,
+ MQTTCLIENT_TRACE_FATAL,
+};
+
+
+/**
+ * This function sets the level of trace information which will be
+ * returned in the trace callback.
+ * @param level the trace level required
+ */
+LIBMQTT_API void MQTTClient_setTraceLevel(enum MQTTCLIENT_TRACE_LEVELS level);
+
+
+/**
+ * This is a callback function prototype which must be implemented if you want
+ * to receive trace information. Do not invoke any other Paho API calls in this
+ * callback function - unpredictable behavior may result.
+ * @param level the trace level of the message returned
+ * @param message the trace message. This is a pointer to a static buffer which
+ * will be overwritten on each call. You must copy the data if you want to keep
+ * it for later.
+ */
+typedef void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char* message);
+
+/**
+ * This function sets the trace callback if needed. If set to NULL,
+ * no trace information will be returned. The default trace level is
+ * MQTTASYNC_TRACE_MINIMUM.
+ * @param callback a pointer to the function which will handle the trace information
+ */
+LIBMQTT_API void MQTTClient_setTraceCallback(MQTTClient_traceCallback* callback);
+
+/**
+ * Sets the timeout value for un/subscribe commands when waiting for the un/suback response from
+ * the server. Values less than 5000 are not allowed.
+ * @param handle A valid client handle from a successful call to MQTTClient_create().
+ * @param milliSeconds the maximum number of milliseconds to wait
+ * @return MQTTCLIENT_SUCCESS or MQTTCLIENT_FAILURE
+ */
+LIBMQTT_API int MQTTClient_setCommandTimeout(MQTTClient handle, unsigned long milliSeconds);
+
+/**
+ * Returns a pointer to the string representation of the error or NULL.
+ *
+ * Do not free after use. Returns NULL if the error code is unknown.
+ */
+LIBMQTT_API const char* MQTTClient_strerror(int code);
+
+#if defined(__cplusplus)
+ }
+#endif
+
+#endif
+
+/*!
+ * @cond MQTTClient_main
+ * @page async Asynchronous vs synchronous client applications
+ * This client library supports two modes of operation. These are referred to
+ * as <b>synchronous</b> and <b>asynchronous</b> modes. If your application
+ * calls MQTTClient_setCallbacks(), this puts the client into asynchronous
+ * mode, otherwise it operates in synchronous mode.
+ *
+ * In synchronous mode, the client application runs on a single thread.
+ * Messages are published using the MQTTClient_publish() and
+ * MQTTClient_publishMessage() functions. To determine that a QoS1 or QoS2
+ * (see @ref qos) message has been successfully delivered, the application
+ * must call the MQTTClient_waitForCompletion() function. An example showing
+ * synchronous publication is shown in @ref pubsync. Receiving messages in
+ * synchronous mode uses the MQTTClient_receive() function. Client applications
+ * must call either MQTTClient_receive() or MQTTClient_yield() relatively
+ * frequently in order to allow processing of acknowledgements and the MQTT
+ * "pings" that keep the network connection to the server alive.
+ *
+ * In asynchronous mode, the client application runs on several threads. The
+ * main program calls functions in the client library to publish and subscribe,
+ * just as for the synchronous mode. Processing of handshaking and maintaining
+ * the network connection is performed in the background, however.
+ * Notifications of status and message reception are provided to the client
+ * application using callbacks registered with the library by the call to
+ * MQTTClient_setCallbacks() (see MQTTClient_messageArrived(),
+ * MQTTClient_connectionLost() and MQTTClient_deliveryComplete()).
+ * This API is not thread safe however - it is not possible to call it from multiple
+ * threads without synchronization. You can use the MQTTAsync API for that.
+ *
+ * @page callbacks Callbacks
+ * You must not call a function from this API from within a callback otherwise
+ * a deadlock might result. The only exception to this is the ability to call
+ * connect within the connection lost callback, to allow a reconnect.
+ *
+ * When using MQTT 5.0, you can also call connect from within the disconnected
+ * callback, which is invoked when the MQTT server sends a disconnect packet.
+ * This server behaviour is allowed in MQTT 5.0, but not in MQTT 3.1.1, so the
+ * disconnected callback will never be invoked if you use MQTT 3.1.1.
+ *
+ * In particular, you must make a publish call within the message arrived callback.
+ * These restrictions are all lifted in the
+ * <a href="../../MQTTAsync/html/index.html">MQTTAsync API</a>.
+ *
+ * If no callbacks are assigned, this will include the message arrived callback.
+ * This could be done if the application is a pure publisher, and does
+ * not subscribe to any topics. If however messages are received, and no message
+ * arrived callback is set, or receive not called, then those messages will accumulate
+ * and take up memory, as there is no place for them to be delivered.
+ * It is up to the application to protect against this situation.
+ *
+ * @page wildcard Subscription wildcards
+ * Every MQTT message includes a topic that classifies it. MQTT servers use
+ * topics to determine which subscribers should receive messages published to
+ * the server.
+ *
+ * Consider the server receiving messages from several environmental sensors.
+ * Each sensor publishes its measurement data as a message with an associated
+ * topic. Subscribing applications need to know which sensor originally
+ * published each received message. A unique topic is thus used to identify
+ * each sensor and measurement type. Topics such as SENSOR1TEMP,
+ * SENSOR1HUMIDITY, SENSOR2TEMP and so on achieve this but are not very
+ * flexible. If additional sensors are added to the system at a later date,
+ * subscribing applications must be modified to receive them.
+ *
+ * To provide more flexibility, MQTT supports a hierarchical topic namespace.
+ * This allows application designers to organize topics to simplify their
+ * management. Levels in the hierarchy are delimited by the '/' character,
+ * such as SENSOR/1/HUMIDITY. Publishers and subscribers use these
+ * hierarchical topics as already described.
+ *
+ * For subscriptions, two wildcard characters are supported:
+ * <ul>
+ * <li>A '#' character represents a complete sub-tree of the hierarchy and
+ * thus must be the last character in a subscription topic string, such as
+ * SENSOR/#. This will match any topic starting with SENSOR/, such as
+ * SENSOR/1/TEMP and SENSOR/2/HUMIDITY.</li>
+ * <li> A '+' character represents a single level of the hierarchy and is
+ * used between delimiters. For example, SENSOR/+/TEMP will match
+ * SENSOR/1/TEMP and SENSOR/2/TEMP.</li>
+ * </ul>
+ * Publishers are not allowed to use the wildcard characters in their topic
+ * names.
+ *
+ * Deciding on your topic hierarchy is an important step in your system design.
+ *
+ * @page qos Quality of service
+ * The MQTT protocol provides three qualities of service for delivering
+ * messages between clients and servers: "at most once", "at least once" and
+ * "exactly once".
+ *
+ * Quality of service (QoS) is an attribute of an individual message being
+ * published. An application sets the QoS for a specific message by setting the
+ * MQTTClient_message.qos field to the required value.
+ *
+ * A subscribing client can set the maximum quality of service a server uses
+ * to send messages that match the client subscriptions. The
+ * MQTTClient_subscribe() and MQTTClient_subscribeMany() functions set this
+ * maximum. The QoS of a message forwarded to a subscriber thus might be
+ * different to the QoS given to the message by the original publisher.
+ * The lower of the two values is used to forward a message.
+ *
+ * The three levels are:
+ *
+ * <b>QoS0, At most once:</b> The message is delivered at most once, or it
+ * may not be delivered at all. Its delivery across the network is not
+ * acknowledged. The message is not stored. The message could be lost if the
+ * client is disconnected, or if the server fails. QoS0 is the fastest mode of
+ * transfer. It is sometimes called "fire and forget".
+ *
+ * The MQTT protocol does not require servers to forward publications at QoS0
+ * to a client. If the client is disconnected at the time the server receives
+ * the publication, the publication might be discarded, depending on the
+ * server implementation.
+ *
+ * <b>QoS1, At least once:</b> The message is always delivered at least once.
+ * It might be delivered multiple times if there is a failure before an
+ * acknowledgment is received by the sender. The message must be stored
+ * locally at the sender, until the sender receives confirmation that the
+ * message has been published by the receiver. The message is stored in case
+ * the message must be sent again.
+ *
+ * <b>QoS2, Exactly once:</b> The message is always delivered exactly once.
+ * The message must be stored locally at the sender, until the sender receives
+ * confirmation that the message has been published by the receiver. The
+ * message is stored in case the message must be sent again. QoS2 is the
+ * safest, but slowest mode of transfer. A more sophisticated handshaking
+ * and acknowledgement sequence is used than for QoS1 to ensure no duplication
+ * of messages occurs.
+ * @page pubsync Synchronous publication example
+@code
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "MQTTClient.h"
+
+#define ADDRESS "tcp://mqtt.eclipseprojects.io:1883"
+#define CLIENTID "ExampleClientPub"
+#define TOPIC "MQTT Examples"
+#define PAYLOAD "Hello World!"
+#define QOS 1
+#define TIMEOUT 10000L
+
+int main(int argc, char* argv[])
+{
+ MQTTClient client;
+ MQTTClient_connectOptions conn_opts = MQTTClient_connectOptions_initializer;
+ MQTTClient_message pubmsg = MQTTClient_message_initializer;
+ MQTTClient_deliveryToken token;
+ int rc;
+
+ if ((rc = MQTTClient_create(&client, ADDRESS, CLIENTID,
+ MQTTCLIENT_PERSISTENCE_NONE, NULL)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to create client, return code %d\n", rc);
+ exit(EXIT_FAILURE);
+ }
+
+ conn_opts.keepAliveInterval = 20;
+ conn_opts.cleansession = 1;
+ if ((rc = MQTTClient_connect(client, &conn_opts)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to connect, return code %d\n", rc);
+ exit(EXIT_FAILURE);
+ }
+
+ pubmsg.payload = PAYLOAD;
+ pubmsg.payloadlen = (int)strlen(PAYLOAD);
+ pubmsg.qos = QOS;
+ pubmsg.retained = 0;
+ if ((rc = MQTTClient_publishMessage(client, TOPIC, &pubmsg, &token)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to publish message, return code %d\n", rc);
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Waiting for up to %d seconds for publication of %s\n"
+ "on topic %s for client with ClientID: %s\n",
+ (int)(TIMEOUT/1000), PAYLOAD, TOPIC, CLIENTID);
+ rc = MQTTClient_waitForCompletion(client, token, TIMEOUT);
+ printf("Message with delivery token %d delivered\n", token);
+
+ if ((rc = MQTTClient_disconnect(client, 10000)) != MQTTCLIENT_SUCCESS)
+ printf("Failed to disconnect, return code %d\n", rc);
+ MQTTClient_destroy(&client);
+ return rc;
+}
+
+ * @endcode
+ *
+ * @page pubasync Asynchronous publication example
+@code{.c}
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "MQTTClient.h"
+
+#if !defined(_WIN32)
+#include <unistd.h>
+#else
+#include <windows.h>
+#endif
+
+#define ADDRESS "tcp://mqtt.eclipseprojects.io:1883"
+#define CLIENTID "ExampleClientPub"
+#define TOPIC "MQTT Examples"
+#define PAYLOAD "Hello World!"
+#define QOS 1
+#define TIMEOUT 10000L
+
+MQTTClient_deliveryToken deliveredtoken;
+
+void delivered(void *context, MQTTClient_deliveryToken dt)
+{
+ printf("Message with token value %d delivery confirmed\n", dt);
+ deliveredtoken = dt;
+}
+
+int msgarrvd(void *context, char *topicName, int topicLen, MQTTClient_message *message)
+{
+ printf("Message arrived\n");
+ printf(" topic: %s\n", topicName);
+ printf(" message: %.*s\n", message->payloadlen, (char*)message->payload);
+ MQTTClient_freeMessage(&message);
+ MQTTClient_free(topicName);
+ return 1;
+}
+
+void connlost(void *context, char *cause)
+{
+ printf("\nConnection lost\n");
+ printf(" cause: %s\n", cause);
+}
+
+int main(int argc, char* argv[])
+{
+ MQTTClient client;
+ MQTTClient_connectOptions conn_opts = MQTTClient_connectOptions_initializer;
+ MQTTClient_message pubmsg = MQTTClient_message_initializer;
+ MQTTClient_deliveryToken token;
+ int rc;
+
+ if ((rc = MQTTClient_create(&client, ADDRESS, CLIENTID,
+ MQTTCLIENT_PERSISTENCE_NONE, NULL)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to create client, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ goto exit;
+ }
+
+ if ((rc = MQTTClient_setCallbacks(client, NULL, connlost, msgarrvd, delivered)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to set callbacks, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ goto destroy_exit;
+ }
+
+ conn_opts.keepAliveInterval = 20;
+ conn_opts.cleansession = 1;
+ if ((rc = MQTTClient_connect(client, &conn_opts)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to connect, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ goto destroy_exit;
+ }
+
+ pubmsg.payload = PAYLOAD;
+ pubmsg.payloadlen = (int)strlen(PAYLOAD);
+ pubmsg.qos = QOS;
+ pubmsg.retained = 0;
+ deliveredtoken = 0;
+ if ((rc = MQTTClient_publishMessage(client, TOPIC, &pubmsg, &token)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to publish message, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ }
+ else
+ {
+ printf("Waiting for publication of %s\n"
+ "on topic %s for client with ClientID: %s\n",
+ PAYLOAD, TOPIC, CLIENTID);
+ while (deliveredtoken != token)
+ {
+ #if defined(_WIN32)
+ Sleep(100);
+ #else
+ usleep(10000L);
+ #endif
+ }
+ }
+
+ if ((rc = MQTTClient_disconnect(client, 10000)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to disconnect, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ }
+
+destroy_exit:
+ MQTTClient_destroy(&client);
+
+exit:
+ return rc;
+}
+
+ * @endcode
+ * @page subasync Asynchronous subscription example
+@code
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "MQTTClient.h"
+
+#define ADDRESS "tcp://mqtt.eclipseprojects.io:1883"
+#define CLIENTID "ExampleClientSub"
+#define TOPIC "MQTT Examples"
+#define PAYLOAD "Hello World!"
+#define QOS 1
+#define TIMEOUT 10000L
+
+volatile MQTTClient_deliveryToken deliveredtoken;
+
+void delivered(void *context, MQTTClient_deliveryToken dt)
+{
+ printf("Message with token value %d delivery confirmed\n", dt);
+ deliveredtoken = dt;
+}
+
+int msgarrvd(void *context, char *topicName, int topicLen, MQTTClient_message *message)
+{
+ printf("Message arrived\n");
+ printf(" topic: %s\n", topicName);
+ printf(" message: %.*s\n", message->payloadlen, (char*)message->payload);
+ MQTTClient_freeMessage(&message);
+ MQTTClient_free(topicName);
+ return 1;
+}
+
+void connlost(void *context, char *cause)
+{
+ printf("\nConnection lost\n");
+ printf(" cause: %s\n", cause);
+}
+
+int main(int argc, char* argv[])
+{
+ MQTTClient client;
+ MQTTClient_connectOptions conn_opts = MQTTClient_connectOptions_initializer;
+ int rc;
+
+ if ((rc = MQTTClient_create(&client, ADDRESS, CLIENTID,
+ MQTTCLIENT_PERSISTENCE_NONE, NULL)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to create client, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ goto exit;
+ }
+
+ if ((rc = MQTTClient_setCallbacks(client, NULL, connlost, msgarrvd, delivered)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to set callbacks, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ goto destroy_exit;
+ }
+
+ conn_opts.keepAliveInterval = 20;
+ conn_opts.cleansession = 1;
+ if ((rc = MQTTClient_connect(client, &conn_opts)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to connect, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ goto destroy_exit;
+ }
+
+ printf("Subscribing to topic %s\nfor client %s using QoS%d\n\n"
+ "Press Q<Enter> to quit\n\n", TOPIC, CLIENTID, QOS);
+ if ((rc = MQTTClient_subscribe(client, TOPIC, QOS)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to subscribe, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ }
+ else
+ {
+ int ch;
+ do
+ {
+ ch = getchar();
+ } while (ch!='Q' && ch != 'q');
+
+ if ((rc = MQTTClient_unsubscribe(client, TOPIC)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to unsubscribe, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ }
+ }
+
+ if ((rc = MQTTClient_disconnect(client, 10000)) != MQTTCLIENT_SUCCESS)
+ {
+ printf("Failed to disconnect, return code %d\n", rc);
+ rc = EXIT_FAILURE;
+ }
+destroy_exit:
+ MQTTClient_destroy(&client);
+exit:
+ return rc;
+}
+
+ * @endcode
+ * @page tracing Tracing
+ *
+ * Runtime tracing is controlled by environment variables.
+ *
+ * Tracing is switched on by setting MQTT_C_CLIENT_TRACE. A value of ON, or stdout, prints to
+ * stdout, any other value is interpreted as a file name to use.
+ *
+ * The amount of trace detail is controlled with the MQTT_C_CLIENT_TRACE_LEVEL environment
+ * variable - valid values are ERROR, PROTOCOL, MINIMUM, MEDIUM and MAXIMUM
+ * (from least to most verbose).
+ *
+ * The variable MQTT_C_CLIENT_TRACE_MAX_LINES limits the number of lines of trace that are output
+ * to a file. Two files are used at most, when they are full, the last one is overwritten with the
+ * new trace entries. The default size is 1000 lines.
+ *
+ * ### MQTT Packet Tracing
+ *
+ * A feature that can be very useful is printing the MQTT packets that are sent and received. To
+ * achieve this, use the following environment variable settings:
+ * @code
+ MQTT_C_CLIENT_TRACE=ON
+ MQTT_C_CLIENT_TRACE_LEVEL=PROTOCOL
+ * @endcode
+ * The output you should see looks like this:
+ * @code
+ 20130528 155936.813 3 stdout-subscriber -> CONNECT cleansession: 1 (0)
+ 20130528 155936.813 3 stdout-subscriber <- CONNACK rc: 0
+ 20130528 155936.813 3 stdout-subscriber -> SUBSCRIBE msgid: 1 (0)
+ 20130528 155936.813 3 stdout-subscriber <- SUBACK msgid: 1
+ 20130528 155941.818 3 stdout-subscriber -> DISCONNECT (0)
+ * @endcode
+ * where the fields are:
+ * 1. date
+ * 2. time
+ * 3. socket number
+ * 4. client id
+ * 5. direction (-> from client to server, <- from server to client)
+ * 6. packet details
+ *
+ * ### Default Level Tracing
+ *
+ * This is an extract of a default level trace of a call to connect:
+ * @code
+ 19700101 010000.000 (1152206656) (0)> MQTTClient_connect:893
+ 19700101 010000.000 (1152206656) (1)> MQTTClient_connectURI:716
+ 20130528 160447.479 Connecting to serverURI localhost:1883
+ 20130528 160447.479 (1152206656) (2)> MQTTProtocol_connect:98
+ 20130528 160447.479 (1152206656) (3)> MQTTProtocol_addressPort:48
+ 20130528 160447.479 (1152206656) (3)< MQTTProtocol_addressPort:73
+ 20130528 160447.479 (1152206656) (3)> Socket_new:599
+ 20130528 160447.479 New socket 4 for localhost, port 1883
+ 20130528 160447.479 (1152206656) (4)> Socket_addSocket:163
+ 20130528 160447.479 (1152206656) (5)> Socket_setnonblocking:73
+ 20130528 160447.479 (1152206656) (5)< Socket_setnonblocking:78 (0)
+ 20130528 160447.479 (1152206656) (4)< Socket_addSocket:176 (0)
+ 20130528 160447.479 (1152206656) (4)> Socket_error:95
+ 20130528 160447.479 (1152206656) (4)< Socket_error:104 (115)
+ 20130528 160447.479 Connect pending
+ 20130528 160447.479 (1152206656) (3)< Socket_new:683 (115)
+ 20130528 160447.479 (1152206656) (2)< MQTTProtocol_connect:131 (115)
+ * @endcode
+ * where the fields are:
+ * 1. date
+ * 2. time
+ * 3. thread id
+ * 4. function nesting level
+ * 5. function entry (>) or exit (<)
+ * 6. function name : line of source code file
+ * 7. return value (if there is one)
+ *
+ * ### Memory Allocation Tracing
+ *
+ * Setting the trace level to maximum causes memory allocations and frees to be traced along with
+ * the default trace entries, with messages like the following:
+ * @code
+ 20130528 161819.657 Allocating 16 bytes in heap at file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c line 177 ptr 0x179f930
+
+ 20130528 161819.657 Freeing 16 bytes in heap at file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c line 201, heap use now 896 bytes
+ * @endcode
+ * When the last MQTT client object is destroyed, if the trace is being recorded
+ * and all memory allocated by the client library has not been freed, an error message will be
+ * written to the trace. This can help with fixing memory leaks. The message will look like this:
+ * @code
+ 20130528 163909.208 Some memory not freed at shutdown, possible memory leak
+ 20130528 163909.208 Heap scan start, total 880 bytes
+ 20130528 163909.208 Heap element size 32, line 354, file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c, ptr 0x260cb00
+ 20130528 163909.208 Content
+ 20130528 163909.209 Heap scan end
+ * @endcode
+ * @endcond
+ */
diff --git a/lib/libpaho-mqtt/include/MQTTClientPersistence.h b/lib/libpaho-mqtt/include/MQTTClientPersistence.h
new file mode 100644
index 0000000..d3caae4
--- /dev/null
+++ b/lib/libpaho-mqtt/include/MQTTClientPersistence.h
@@ -0,0 +1,277 @@
+/*******************************************************************************
+ * Copyright (c) 2009, 2020 IBM Corp.
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v2.0
+ * and Eclipse Distribution License v1.0 which accompany this distribution.
+ *
+ * The Eclipse Public License is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * Contributors:
+ * Ian Craggs - initial API and implementation and/or initial documentation
+ *******************************************************************************/
+
+/**
+ * @file
+ * \brief This structure represents a persistent data store, used to store
+ * outbound and inbound messages, in order to achieve reliable messaging.
+ *
+ * The MQTT Client persists QoS1 and QoS2 messages in order to meet the
+ * assurances of delivery associated with these @ref qos levels. The messages
+ * are saved in persistent storage
+ * The type and context of the persistence implementation are specified when
+ * the MQTT client is created (see MQTTClient_create()). The default
+ * persistence type (::MQTTCLIENT_PERSISTENCE_DEFAULT) uses a file system-based
+ * persistence mechanism. The <i>persistence_context</i> argument passed to
+ * MQTTClient_create() when using the default peristence is a string
+ * representing the location of the persistence directory. If the context
+ * argument is NULL, the working directory will be used.
+ *
+ * To use memory-based persistence, an application passes
+ * ::MQTTCLIENT_PERSISTENCE_NONE as the <i>persistence_type</i> to
+ * MQTTClient_create(). This can lead to message loss in certain situations,
+ * but can be appropriate in some cases (see @ref qos).
+ *
+ * Client applications can provide their own persistence mechanism by passing
+ * ::MQTTCLIENT_PERSISTENCE_USER as the <i>persistence_type</i>. To implement a
+ * custom persistence mechanism, the application must pass an initialized
+ * ::MQTTClient_persistence structure as the <i>persistence_context</i>
+ * argument to MQTTClient_create().
+ *
+ * If the functions defined return an ::MQTTCLIENT_PERSISTENCE_ERROR then the
+ * state of the persisted data should remain as it was prior to the function
+ * being called. For example, if Persistence_put() returns
+ * ::MQTTCLIENT_PERSISTENCE_ERROR, then it is assumed tha tthe persistent store
+ * does not contain the data that was passed to the function. Similarly, if
+ * Persistence_remove() returns ::MQTTCLIENT_PERSISTENCE_ERROR then it is
+ * assumed that the data to be removed is still held in the persistent store.
+ *
+ * It is up to the persistence implementation to log any error information that
+ * may be required to diagnose a persistence mechanism failure.
+ */
+
+/*
+/// @cond EXCLUDE
+*/
+#if !defined(MQTTCLIENTPERSISTENCE_H)
+#define MQTTCLIENTPERSISTENCE_H
+/*
+/// @endcond
+*/
+
+/**
+ * This <i>persistence_type</i> value specifies the default file system-based
+ * persistence mechanism (see MQTTClient_create()).
+ */
+#define MQTTCLIENT_PERSISTENCE_DEFAULT 0
+/**
+ * This <i>persistence_type</i> value specifies a memory-based
+ * persistence mechanism (see MQTTClient_create()).
+ */
+#define MQTTCLIENT_PERSISTENCE_NONE 1
+/**
+ * This <i>persistence_type</i> value specifies an application-specific
+ * persistence mechanism (see MQTTClient_create()).
+ */
+#define MQTTCLIENT_PERSISTENCE_USER 2
+
+/**
+ * Application-specific persistence functions must return this error code if
+ * there is a problem executing the function.
+ */
+#define MQTTCLIENT_PERSISTENCE_ERROR -2
+
+/**
+ * @brief Initialize the persistent store.
+ *
+ * Either open the existing persistent store for this client ID or create a new
+ * one if one doesn't exist. If the persistent store is already open, return
+ * without taking any action.
+ *
+ * An application can use the same client identifier to connect to many
+ * different servers. The <i>clientid</i> in conjunction with the
+ * <i>serverURI</i> uniquely identifies the persistence store required.
+ *
+ * @param handle The address of a pointer to a handle for this persistence
+ * implementation. This function must set handle to a valid reference to the
+ * persistence following a successful return.
+ * The handle pointer is passed as an argument to all the other
+ * persistence functions. It may include the context parameter and/or any other
+ * data for use by the persistence functions.
+ * @param clientID The client identifier for which the persistent store should
+ * be opened.
+ * @param serverURI The connection string specified when the MQTT client was
+ * created (see MQTTClient_create()).
+ * @param context A pointer to any data required to initialize the persistent
+ * store (see ::MQTTClient_persistence).
+ * @return Return 0 if the function completes successfully, otherwise return
+ * ::MQTTCLIENT_PERSISTENCE_ERROR.
+ */
+typedef int (*Persistence_open)(void** handle, const char* clientID, const char* serverURI, void* context);
+
+/**
+ * @brief Close the persistent store referred to by the handle.
+ *
+ * @param handle The handle pointer from a successful call to
+ * Persistence_open().
+ * @return Return 0 if the function completes successfully, otherwise return
+ * ::MQTTCLIENT_PERSISTENCE_ERROR.
+ */
+typedef int (*Persistence_close)(void* handle);
+
+/**
+ * @brief Put the specified data into the persistent store.
+ *
+ * @param handle The handle pointer from a successful call to
+ * Persistence_open().
+ * @param key A string used as the key for the data to be put in the store. The
+ * key is later used to retrieve data from the store with Persistence_get().
+ * @param bufcount The number of buffers to write to the persistence store.
+ * @param buffers An array of pointers to the data buffers associated with
+ * this <i>key</i>.
+ * @param buflens An array of lengths of the data buffers. <i>buflen[n]</i>
+ * gives the length of <i>buffer[n]</i>.
+ * @return Return 0 if the function completes successfully, otherwise return
+ * ::MQTTCLIENT_PERSISTENCE_ERROR.
+ */
+typedef int (*Persistence_put)(void* handle, char* key, int bufcount, char* buffers[], int buflens[]);
+
+/**
+ * @brief Retrieve the specified data from the persistent store.
+ *
+ * @param handle The handle pointer from a successful call to
+ * Persistence_open().
+ * @param key A string that is the key for the data to be retrieved. This is
+ * the same key used to save the data to the store with Persistence_put().
+ * @param buffer The address of a pointer to a buffer. This function sets the
+ * pointer to point at the retrieved data, if successful.
+ * @param buflen The address of an int that is set to the length of
+ * <i>buffer</i> by this function if successful.
+ * @return Return 0 if the function completes successfully, otherwise return
+ * ::MQTTCLIENT_PERSISTENCE_ERROR.
+ */
+typedef int (*Persistence_get)(void* handle, char* key, char** buffer, int* buflen);
+
+/**
+ * @brief Remove the data for the specified key from the store.
+ *
+ * @param handle The handle pointer from a successful call to
+ * Persistence_open().
+ * @param key A string that is the key for the data to be removed from the
+ * store. This is the same key used to save the data to the store with
+ * Persistence_put().
+ * @return Return 0 if the function completes successfully, otherwise return
+ * ::MQTTCLIENT_PERSISTENCE_ERROR.
+ */
+typedef int (*Persistence_remove)(void* handle, char* key);
+
+/**
+ * @brief Returns the keys in this persistent data store.
+ *
+ * @param handle The handle pointer from a successful call to
+ * Persistence_open().
+ * @param keys The address of a pointer to pointers to strings. Assuming
+ * successful execution, this function allocates memory to hold the returned
+ * keys (strings used to store the data with Persistence_put()). It also
+ * allocates memory to hold an array of pointers to these strings. <i>keys</i>
+ * is set to point to the array of pointers to strings.
+ * @param nkeys A pointer to the number of keys in this persistent data store.
+ * This function sets the number of keys, if successful.
+ * @return Return 0 if the function completes successfully, otherwise return
+ * ::MQTTCLIENT_PERSISTENCE_ERROR.
+ */
+typedef int (*Persistence_keys)(void* handle, char*** keys, int* nkeys);
+
+/**
+ * @brief Clears the persistence store, so that it no longer contains any
+ * persisted data.
+ *
+ * @param handle The handle pointer from a successful call to
+ * Persistence_open().
+ * @return Return 0 if the function completes successfully, otherwise return
+ * ::MQTTCLIENT_PERSISTENCE_ERROR.
+ */
+typedef int (*Persistence_clear)(void* handle);
+
+/**
+ * @brief Returns whether any data has been persisted using the specified key.
+ *
+ * @param handle The handle pointer from a successful call to
+ * Persistence_open().
+ * @param key The string to be tested for existence in the store.
+ * @return Return 0 if the key was found in the store, otherwise return
+ * ::MQTTCLIENT_PERSISTENCE_ERROR.
+ */
+typedef int (*Persistence_containskey)(void* handle, char* key);
+
+/**
+ * @brief A structure containing the function pointers to a persistence
+ * implementation and the context or state that will be shared across all
+ * the persistence functions.
+ */
+typedef struct {
+ /**
+ * A pointer to any data required to initialize the persistent store.
+ */
+ void* context;
+ /**
+ * A function pointer to an implementation of Persistence_open().
+ */
+ Persistence_open popen;
+ /**
+ * A function pointer to an implementation of Persistence_close().
+ */
+ Persistence_close pclose;
+ /**
+ * A function pointer to an implementation of Persistence_put().
+ */
+ Persistence_put pput;
+ /**
+ * A function pointer to an implementation of Persistence_get().
+ */
+ Persistence_get pget;
+ /**
+ * A function pointer to an implementation of Persistence_remove().
+ */
+ Persistence_remove premove;
+ /**
+ * A function pointer to an implementation of Persistence_keys().
+ */
+ Persistence_keys pkeys;
+ /**
+ * A function pointer to an implementation of Persistence_clear().
+ */
+ Persistence_clear pclear;
+ /**
+ * A function pointer to an implementation of Persistence_containskey().
+ */
+ Persistence_containskey pcontainskey;
+} MQTTClient_persistence;
+
+
+/**
+ * A callback which is invoked just before a write to persistence. This can be
+ * used to transform the data, for instance to encrypt it.
+ * @param context The context as set in ::MQTTAsync_setBeforePersistenceWrite
+ * @param bufcount The number of buffers to write to the persistence store.
+ * @param buffers An array of pointers to the data buffers.
+ * @param buflens An array of lengths of the data buffers.
+ * @return Return 0 if the function completes successfully, otherwise non 0.
+ */
+typedef int MQTTPersistence_beforeWrite(void* context, int bufcount, char* buffers[], int buflens[]);
+
+
+/**
+ * A callback which is invoked just after a read from persistence. This can be
+ * used to transform the data, for instance to decrypt it.
+ * @param context The context as set in ::MQTTAsync_setAfterPersistenceRead
+ * @param buffer The address of a pointer to a buffer.
+ * @param buflen The address of an int that is the length of the buffer.
+ * @return Return 0 if the function completes successfully, otherwise non 0.
+ */
+typedef int MQTTPersistence_afterRead(void* context, char** buffer, int* buflen);
+
+#endif
diff --git a/lib/libpaho-mqtt/include/MQTTExportDeclarations.h b/lib/libpaho-mqtt/include/MQTTExportDeclarations.h
new file mode 100644
index 0000000..d492ef1
--- /dev/null
+++ b/lib/libpaho-mqtt/include/MQTTExportDeclarations.h
@@ -0,0 +1,36 @@
+/*******************************************************************************
+ * Copyright (c) 2020, 2020 Andreas Walter
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v2.0
+ * and Eclipse Distribution License v1.0 which accompany this distribution.
+ *
+ * The Eclipse Public License is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * Contributors:
+ * Andreas Walter - initially moved export declarations into separate fle
+ *******************************************************************************/
+
+#if !defined(EXPORTDECLARATIONS_H)
+#define EXPORTDECLARATIONS_H
+
+#if defined(_WIN32) || defined(_WIN64)
+# if defined(PAHO_MQTT_EXPORTS)
+# define LIBMQTT_API __declspec(dllexport)
+# elif defined(PAHO_MQTT_IMPORTS)
+# define LIBMQTT_API __declspec(dllimport)
+# else
+# define LIBMQTT_API
+# endif
+#else
+# if defined(PAHO_MQTT_EXPORTS)
+# define LIBMQTT_API __attribute__ ((visibility ("default")))
+# else
+# define LIBMQTT_API extern
+# endif
+#endif
+
+#endif
diff --git a/lib/libpaho-mqtt/include/MQTTProperties.h b/lib/libpaho-mqtt/include/MQTTProperties.h
new file mode 100644
index 0000000..bbfd732
--- /dev/null
+++ b/lib/libpaho-mqtt/include/MQTTProperties.h
@@ -0,0 +1,222 @@
+/*******************************************************************************
+ * Copyright (c) 2017, 2023 IBM Corp. and others
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v2.0
+ * and Eclipse Distribution License v1.0 which accompany this distribution.
+ *
+ * The Eclipse Public License is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * Contributors:
+ * Ian Craggs - initial API and implementation and/or initial documentation
+ *******************************************************************************/
+
+#if !defined(MQTTPROPERTIES_H)
+#define MQTTPROPERTIES_H
+
+#include "MQTTExportDeclarations.h"
+
+#define MQTT_INVALID_PROPERTY_ID -2
+
+/** The one byte MQTT V5 property indicator */
+enum MQTTPropertyCodes {
+ MQTTPROPERTY_CODE_PAYLOAD_FORMAT_INDICATOR = 1, /**< The value is 1 */
+ MQTTPROPERTY_CODE_MESSAGE_EXPIRY_INTERVAL = 2, /**< The value is 2 */
+ MQTTPROPERTY_CODE_CONTENT_TYPE = 3, /**< The value is 3 */
+ MQTTPROPERTY_CODE_RESPONSE_TOPIC = 8, /**< The value is 8 */
+ MQTTPROPERTY_CODE_CORRELATION_DATA = 9, /**< The value is 9 */
+ MQTTPROPERTY_CODE_SUBSCRIPTION_IDENTIFIER = 11, /**< The value is 11 */
+ MQTTPROPERTY_CODE_SESSION_EXPIRY_INTERVAL = 17, /**< The value is 17 */
+ MQTTPROPERTY_CODE_ASSIGNED_CLIENT_IDENTIFER = 18,/**< The value is 18 */
+ MQTTPROPERTY_CODE_SERVER_KEEP_ALIVE = 19, /**< The value is 19 */
+ MQTTPROPERTY_CODE_AUTHENTICATION_METHOD = 21, /**< The value is 21 */
+ MQTTPROPERTY_CODE_AUTHENTICATION_DATA = 22, /**< The value is 22 */
+ MQTTPROPERTY_CODE_REQUEST_PROBLEM_INFORMATION = 23,/**< The value is 23 */
+ MQTTPROPERTY_CODE_WILL_DELAY_INTERVAL = 24, /**< The value is 24 */
+ MQTTPROPERTY_CODE_REQUEST_RESPONSE_INFORMATION = 25,/**< The value is 25 */
+ MQTTPROPERTY_CODE_RESPONSE_INFORMATION = 26, /**< The value is 26 */
+ MQTTPROPERTY_CODE_SERVER_REFERENCE = 28, /**< The value is 28 */
+ MQTTPROPERTY_CODE_REASON_STRING = 31, /**< The value is 31 */
+ MQTTPROPERTY_CODE_RECEIVE_MAXIMUM = 33, /**< The value is 33*/
+ MQTTPROPERTY_CODE_TOPIC_ALIAS_MAXIMUM = 34, /**< The value is 34 */
+ MQTTPROPERTY_CODE_TOPIC_ALIAS = 35, /**< The value is 35 */
+ MQTTPROPERTY_CODE_MAXIMUM_QOS = 36, /**< The value is 36 */
+ MQTTPROPERTY_CODE_RETAIN_AVAILABLE = 37, /**< The value is 37 */
+ MQTTPROPERTY_CODE_USER_PROPERTY = 38, /**< The value is 38 */
+ MQTTPROPERTY_CODE_MAXIMUM_PACKET_SIZE = 39, /**< The value is 39 */
+ MQTTPROPERTY_CODE_WILDCARD_SUBSCRIPTION_AVAILABLE = 40,/**< The value is 40 */
+ MQTTPROPERTY_CODE_SUBSCRIPTION_IDENTIFIERS_AVAILABLE = 41,/**< The value is 41 */
+ MQTTPROPERTY_CODE_SHARED_SUBSCRIPTION_AVAILABLE = 42/**< The value is 241 */
+};
+
+/**
+ * Returns a printable string description of an MQTT V5 property code.
+ * @param value an MQTT V5 property code.
+ * @return the printable string description of the input property code.
+ * NULL if the code was not found.
+ */
+LIBMQTT_API const char* MQTTPropertyName(enum MQTTPropertyCodes value);
+
+/** The one byte MQTT V5 property type */
+enum MQTTPropertyTypes {
+ MQTTPROPERTY_TYPE_BYTE,
+ MQTTPROPERTY_TYPE_TWO_BYTE_INTEGER,
+ MQTTPROPERTY_TYPE_FOUR_BYTE_INTEGER,
+ MQTTPROPERTY_TYPE_VARIABLE_BYTE_INTEGER,
+ MQTTPROPERTY_TYPE_BINARY_DATA,
+ MQTTPROPERTY_TYPE_UTF_8_ENCODED_STRING,
+ MQTTPROPERTY_TYPE_UTF_8_STRING_PAIR
+};
+
+/**
+ * Returns the MQTT V5 type code of an MQTT V5 property.
+ * @param value an MQTT V5 property code.
+ * @return the MQTT V5 type code of the input property. -1 if the code was not found.
+ */
+LIBMQTT_API int MQTTProperty_getType(enum MQTTPropertyCodes value);
+
+/**
+ * The data for a length delimited string
+ */
+typedef struct
+{
+ int len; /**< the length of the string */
+ char* data; /**< pointer to the string data */
+} MQTTLenString;
+
+
+/**
+ * Structure to hold an MQTT version 5 property of any type
+ */
+typedef struct
+{
+ enum MQTTPropertyCodes identifier; /**< The MQTT V5 property id. A multi-byte integer. */
+ /** The value of the property, as a union of the different possible types. */
+ union {
+ unsigned char byte; /**< holds the value of a byte property type */
+ unsigned short integer2; /**< holds the value of a 2 byte integer property type */
+ unsigned int integer4; /**< holds the value of a 4 byte integer property type */
+ struct {
+ MQTTLenString data; /**< The value of a string property, or the name of a user property. */
+ MQTTLenString value; /**< The value of a user property. */
+ };
+ } value;
+} MQTTProperty;
+
+/**
+ * MQTT version 5 property list
+ */
+typedef struct MQTTProperties
+{
+ int count; /**< number of property entries in the array */
+ int max_count; /**< max number of properties that the currently allocated array can store */
+ int length; /**< mbi: byte length of all properties */
+ MQTTProperty *array; /**< array of properties */
+} MQTTProperties;
+
+#define MQTTProperties_initializer {0, 0, 0, NULL}
+
+/**
+ * Returns the length of the properties structure when serialized ready for network transmission.
+ * @param props an MQTT V5 property structure.
+ * @return the length in bytes of the properties when serialized.
+ */
+int MQTTProperties_len(MQTTProperties* props);
+
+/**
+ * Add a property pointer to the property array. Memory is allocated in this function,
+ * so MQTTClient_create or MQTTAsync_create must be called first to initialize the
+ * internal heap tracking. Alternatively MQTTAsync_global_init() can be called first
+ * or build with the HIGH_PERFORMANCE option which disables the heap tracking.
+ * @param props The property list to add the property to.
+ * @param prop The property to add to the list.
+ * @return 0 on success, -1 on failure.
+ */
+LIBMQTT_API int MQTTProperties_add(MQTTProperties* props, const MQTTProperty* prop);
+
+/**
+ * Serialize the given property list to a character buffer, e.g. for writing to the network.
+ * @param pptr pointer to the buffer - move the pointer as we add data
+ * @param properties pointer to the property list, can be NULL
+ * @return whether the write succeeded or not: number of bytes written, or < 0 on failure.
+ */
+int MQTTProperties_write(char** pptr, const MQTTProperties* properties);
+
+/**
+ * Reads a property list from a character buffer into an array.
+ * @param properties pointer to the property list to be filled. Should be initalized but empty.
+ * @param pptr pointer to the character buffer.
+ * @param enddata pointer to the end of the character buffer so we don't read beyond.
+ * @return 1 if the properties were read successfully.
+ */
+int MQTTProperties_read(MQTTProperties* properties, char** pptr, char* enddata);
+
+/**
+ * Free all memory allocated to the property list, including any to individual properties.
+ * @param properties pointer to the property list.
+ */
+LIBMQTT_API void MQTTProperties_free(MQTTProperties* properties);
+
+/**
+ * Copy the contents of a property list, allocating additional memory if needed.
+ * @param props pointer to the property list.
+ * @return the duplicated property list.
+ */
+LIBMQTT_API MQTTProperties MQTTProperties_copy(const MQTTProperties* props);
+
+/**
+ * Checks if property list contains a specific property.
+ * @param props pointer to the property list.
+ * @param propid the property id to check for.
+ * @return 1 if found, 0 if not.
+ */
+LIBMQTT_API int MQTTProperties_hasProperty(MQTTProperties *props, enum MQTTPropertyCodes propid);
+
+/**
+ * Returns the number of instances of a property id. Most properties can exist only once.
+ * User properties and subscription ids can exist more than once.
+ * @param props pointer to the property list.
+ * @param propid the property id to check for.
+ * @return the number of times found. Can be 0.
+ */
+LIBMQTT_API int MQTTProperties_propertyCount(MQTTProperties *props, enum MQTTPropertyCodes propid);
+
+/**
+ * Returns the integer value of a specific property. The property given must be a numeric type.
+ * @param props pointer to the property list.
+ * @param propid the property id to check for.
+ * @return the integer value of the property. -9999999 on failure.
+ */
+LIBMQTT_API int MQTTProperties_getNumericValue(MQTTProperties *props, enum MQTTPropertyCodes propid);
+
+/**
+ * Returns the integer value of a specific property when it's not the only instance.
+ * The property given must be a numeric type.
+ * @param props pointer to the property list.
+ * @param propid the property id to check for.
+ * @param index the instance number, starting at 0.
+ * @return the integer value of the property. -9999999 on failure.
+ */
+LIBMQTT_API int MQTTProperties_getNumericValueAt(MQTTProperties *props, enum MQTTPropertyCodes propid, int index);
+
+/**
+ * Returns a pointer to the property structure for a specific property.
+ * @param props pointer to the property list.
+ * @param propid the property id to check for.
+ * @return the pointer to the property structure if found. NULL if not found.
+ */
+LIBMQTT_API MQTTProperty* MQTTProperties_getProperty(MQTTProperties *props, enum MQTTPropertyCodes propid);
+
+/**
+ * Returns a pointer to the property structure for a specific property when it's not the only instance.
+ * @param props pointer to the property list.
+ * @param propid the property id to check for.
+ * @param index the instance number, starting at 0.
+ * @return the pointer to the property structure if found. NULL if not found.
+ */
+LIBMQTT_API MQTTProperty* MQTTProperties_getPropertyAt(MQTTProperties *props, enum MQTTPropertyCodes propid, int index);
+
+#endif /* MQTTPROPERTIES_H */
diff --git a/lib/libpaho-mqtt/include/MQTTReasonCodes.h b/lib/libpaho-mqtt/include/MQTTReasonCodes.h
new file mode 100644
index 0000000..2dc08ea
--- /dev/null
+++ b/lib/libpaho-mqtt/include/MQTTReasonCodes.h
@@ -0,0 +1,79 @@
+/*******************************************************************************
+ * Copyright (c) 2017, 2020 IBM Corp. and others
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v2.0
+ * and Eclipse Distribution License v1.0 which accompany this distribution.
+ *
+ * The Eclipse Public License is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * Contributors:
+ * Ian Craggs - initial API and implementation and/or initial documentation
+ *******************************************************************************/
+
+#if !defined(MQTTREASONCODES_H)
+#define MQTTREASONCODES_H
+
+#include "MQTTExportDeclarations.h"
+
+/** The MQTT V5 one byte reason code */
+enum MQTTReasonCodes {
+ MQTTREASONCODE_SUCCESS = 0,
+ MQTTREASONCODE_NORMAL_DISCONNECTION = 0,
+ MQTTREASONCODE_GRANTED_QOS_0 = 0,
+ MQTTREASONCODE_GRANTED_QOS_1 = 1,
+ MQTTREASONCODE_GRANTED_QOS_2 = 2,
+ MQTTREASONCODE_DISCONNECT_WITH_WILL_MESSAGE = 4,
+ MQTTREASONCODE_NO_MATCHING_SUBSCRIBERS = 16,
+ MQTTREASONCODE_NO_SUBSCRIPTION_FOUND = 17,
+ MQTTREASONCODE_CONTINUE_AUTHENTICATION = 24,
+ MQTTREASONCODE_RE_AUTHENTICATE = 25,
+ MQTTREASONCODE_UNSPECIFIED_ERROR = 128,
+ MQTTREASONCODE_MALFORMED_PACKET = 129,
+ MQTTREASONCODE_PROTOCOL_ERROR = 130,
+ MQTTREASONCODE_IMPLEMENTATION_SPECIFIC_ERROR = 131,
+ MQTTREASONCODE_UNSUPPORTED_PROTOCOL_VERSION = 132,
+ MQTTREASONCODE_CLIENT_IDENTIFIER_NOT_VALID = 133,
+ MQTTREASONCODE_BAD_USER_NAME_OR_PASSWORD = 134,
+ MQTTREASONCODE_NOT_AUTHORIZED = 135,
+ MQTTREASONCODE_SERVER_UNAVAILABLE = 136,
+ MQTTREASONCODE_SERVER_BUSY = 137,
+ MQTTREASONCODE_BANNED = 138,
+ MQTTREASONCODE_SERVER_SHUTTING_DOWN = 139,
+ MQTTREASONCODE_BAD_AUTHENTICATION_METHOD = 140,
+ MQTTREASONCODE_KEEP_ALIVE_TIMEOUT = 141,
+ MQTTREASONCODE_SESSION_TAKEN_OVER = 142,
+ MQTTREASONCODE_TOPIC_FILTER_INVALID = 143,
+ MQTTREASONCODE_TOPIC_NAME_INVALID = 144,
+ MQTTREASONCODE_PACKET_IDENTIFIER_IN_USE = 145,
+ MQTTREASONCODE_PACKET_IDENTIFIER_NOT_FOUND = 146,
+ MQTTREASONCODE_RECEIVE_MAXIMUM_EXCEEDED = 147,
+ MQTTREASONCODE_TOPIC_ALIAS_INVALID = 148,
+ MQTTREASONCODE_PACKET_TOO_LARGE = 149,
+ MQTTREASONCODE_MESSAGE_RATE_TOO_HIGH = 150,
+ MQTTREASONCODE_QUOTA_EXCEEDED = 151,
+ MQTTREASONCODE_ADMINISTRATIVE_ACTION = 152,
+ MQTTREASONCODE_PAYLOAD_FORMAT_INVALID = 153,
+ MQTTREASONCODE_RETAIN_NOT_SUPPORTED = 154,
+ MQTTREASONCODE_QOS_NOT_SUPPORTED = 155,
+ MQTTREASONCODE_USE_ANOTHER_SERVER = 156,
+ MQTTREASONCODE_SERVER_MOVED = 157,
+ MQTTREASONCODE_SHARED_SUBSCRIPTIONS_NOT_SUPPORTED = 158,
+ MQTTREASONCODE_CONNECTION_RATE_EXCEEDED = 159,
+ MQTTREASONCODE_MAXIMUM_CONNECT_TIME = 160,
+ MQTTREASONCODE_SUBSCRIPTION_IDENTIFIERS_NOT_SUPPORTED = 161,
+ MQTTREASONCODE_WILDCARD_SUBSCRIPTIONS_NOT_SUPPORTED = 162
+};
+
+/**
+ * Returns a printable string description of an MQTT V5 reason code.
+ * @param value an MQTT V5 reason code.
+ * @return the printable string description of the input reason code.
+ * NULL if the code was not found.
+ */
+LIBMQTT_API const char* MQTTReasonCode_toString(enum MQTTReasonCodes value);
+
+#endif
diff --git a/lib/libpaho-mqtt/include/MQTTSubscribeOpts.h b/lib/libpaho-mqtt/include/MQTTSubscribeOpts.h
new file mode 100644
index 0000000..264e4d0
--- /dev/null
+++ b/lib/libpaho-mqtt/include/MQTTSubscribeOpts.h
@@ -0,0 +1,46 @@
+/*******************************************************************************
+ * Copyright (c) 2018 IBM Corp.
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v2.0
+ * and Eclipse Distribution License v1.0 which accompany this distribution.
+ *
+ * The Eclipse Public License is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * Contributors:
+ * Ian Craggs - initial API and implementation and/or initial documentation
+ *******************************************************************************/
+
+#if !defined(SUBOPTS_H)
+#define SUBOPTS_H
+
+/** The MQTT V5 subscribe options, apart from QoS which existed before V5. */
+typedef struct MQTTSubscribe_options
+{
+ /** The eyecatcher for this structure. Must be MQSO. */
+ char struct_id[4];
+ /** The version number of this structure. Must be 0.
+ */
+ int struct_version;
+ /** To not receive our own publications, set to 1.
+ * 0 is the original MQTT behaviour - all messages matching the subscription are received.
+ */
+ unsigned char noLocal;
+ /** To keep the retain flag as on the original publish message, set to 1.
+ * If 0, defaults to the original MQTT behaviour where the retain flag is only set on
+ * publications sent by a broker if in response to a subscribe request.
+ */
+ unsigned char retainAsPublished;
+ /** 0 - send retained messages at the time of the subscribe (original MQTT behaviour)
+ * 1 - send retained messages on subscribe only if the subscription is new
+ * 2 - do not send retained messages at all
+ */
+ unsigned char retainHandling;
+} MQTTSubscribe_options;
+
+#define MQTTSubscribe_options_initializer { {'M', 'Q', 'S', 'O'}, 0, 0, 0, 0 }
+
+#endif
diff --git a/lib/libpaho-mqtt/lib/libpaho-mqtt3a.so b/lib/libpaho-mqtt/lib/libpaho-mqtt3a.so
new file mode 120000
index 0000000..9710c1b
--- /dev/null
+++ b/lib/libpaho-mqtt/lib/libpaho-mqtt3a.so
@@ -0,0 +1 @@
+libpaho-mqtt3a.so.1
\ No newline at end of file
diff --git a/lib/libpaho-mqtt/lib/libpaho-mqtt3a.so.1 b/lib/libpaho-mqtt/lib/libpaho-mqtt3a.so.1
new file mode 120000
index 0000000..07ba2c9
--- /dev/null
+++ b/lib/libpaho-mqtt/lib/libpaho-mqtt3a.so.1
@@ -0,0 +1 @@
+libpaho-mqtt3a.so.1.3
\ No newline at end of file
diff --git a/lib/libpaho-mqtt/lib/libpaho-mqtt3a.so.1.3 b/lib/libpaho-mqtt/lib/libpaho-mqtt3a.so.1.3
new file mode 100644
index 0000000..1616051
Binary files /dev/null and b/lib/libpaho-mqtt/lib/libpaho-mqtt3a.so.1.3 differ
diff --git a/lib/libpaho-mqtt/lib/libpaho-mqtt3as.so b/lib/libpaho-mqtt/lib/libpaho-mqtt3as.so
new file mode 120000
index 0000000..e4aabed
--- /dev/null
+++ b/lib/libpaho-mqtt/lib/libpaho-mqtt3as.so
@@ -0,0 +1 @@
+libpaho-mqtt3as.so.1
\ No newline at end of file
diff --git a/lib/libpaho-mqtt/lib/libpaho-mqtt3as.so.1 b/lib/libpaho-mqtt/lib/libpaho-mqtt3as.so.1
new file mode 120000
index 0000000..810def7
--- /dev/null
+++ b/lib/libpaho-mqtt/lib/libpaho-mqtt3as.so.1
@@ -0,0 +1 @@
+libpaho-mqtt3as.so.1.3
\ No newline at end of file
diff --git a/lib/libpaho-mqtt/lib/libpaho-mqtt3as.so.1.3 b/lib/libpaho-mqtt/lib/libpaho-mqtt3as.so.1.3
new file mode 100644
index 0000000..634c9ea
Binary files /dev/null and b/lib/libpaho-mqtt/lib/libpaho-mqtt3as.so.1.3 differ
diff --git a/lib/libpaho-mqtt/lib/libpaho-mqtt3c.so b/lib/libpaho-mqtt/lib/libpaho-mqtt3c.so
new file mode 120000
index 0000000..153ddaa
--- /dev/null
+++ b/lib/libpaho-mqtt/lib/libpaho-mqtt3c.so
@@ -0,0 +1 @@
+libpaho-mqtt3c.so.1
\ No newline at end of file
diff --git a/lib/libpaho-mqtt/lib/libpaho-mqtt3c.so.1 b/lib/libpaho-mqtt/lib/libpaho-mqtt3c.so.1
new file mode 120000
index 0000000..ce1c151
--- /dev/null
+++ b/lib/libpaho-mqtt/lib/libpaho-mqtt3c.so.1
@@ -0,0 +1 @@
+libpaho-mqtt3c.so.1.3
\ No newline at end of file
diff --git a/lib/libpaho-mqtt/lib/libpaho-mqtt3c.so.1.3 b/lib/libpaho-mqtt/lib/libpaho-mqtt3c.so.1.3
new file mode 100644
index 0000000..9f19a9a
Binary files /dev/null and b/lib/libpaho-mqtt/lib/libpaho-mqtt3c.so.1.3 differ
diff --git a/lib/libpaho-mqtt/lib/libpaho-mqtt3cs.so b/lib/libpaho-mqtt/lib/libpaho-mqtt3cs.so
new file mode 120000
index 0000000..ea90fc2
--- /dev/null
+++ b/lib/libpaho-mqtt/lib/libpaho-mqtt3cs.so
@@ -0,0 +1 @@
+libpaho-mqtt3cs.so.1
\ No newline at end of file
diff --git a/lib/libpaho-mqtt/lib/libpaho-mqtt3cs.so.1 b/lib/libpaho-mqtt/lib/libpaho-mqtt3cs.so.1
new file mode 120000
index 0000000..80a4e9d
--- /dev/null
+++ b/lib/libpaho-mqtt/lib/libpaho-mqtt3cs.so.1
@@ -0,0 +1 @@
+libpaho-mqtt3cs.so.1.3
\ No newline at end of file
diff --git a/lib/libpaho-mqtt/lib/libpaho-mqtt3cs.so.1.3 b/lib/libpaho-mqtt/lib/libpaho-mqtt3cs.so.1.3
new file mode 100644
index 0000000..e4ec6ea
Binary files /dev/null and b/lib/libpaho-mqtt/lib/libpaho-mqtt3cs.so.1.3 differ
diff --git a/lib/libpaho-mqtt/share/man/man1/paho_c_pub.1 b/lib/libpaho-mqtt/share/man/man1/paho_c_pub.1
new file mode 100644
index 0000000..60ec2df
--- /dev/null
+++ b/lib/libpaho-mqtt/share/man/man1/paho_c_pub.1
@@ -0,0 +1,199 @@
+.TH PAHO_C_PUB 1L "31 July 2018 (v1.3.0)" http://eclipse.org/paho
+
+.SH NAME
+paho_c_pub \- send (publish) data to an MQTT server
+
+.SH SYNOPSIS
+.B paho_c_pub
+[\fItopic\fR]
+[\fB\-t\fR|\fB\-\-topic\fR \fItopic\fR]
+[\fB\-c\fR|\fB\-\-connection\fR \fIconnection\fR]
+[\fB\-h\fR|\fB\-\-host\fR \fIhostname\fR]
+[\fB\-p\fR|\fB\-\-port\fR \fIportnumber\fR]
+[\fB\-i\fR|\fB\-\-clientid\fR \fIclientid\fR]
+[\fB\-u\fR|\fB\-\-username\fR \fIusername\fR]
+[\fB\-P\fR|\fB\-\-password\fR \fIpassword\fR]
+[\fB\-k\fR|\fB\-\-keepalive\fR \fIkeepalive-timeout\fR]
+[\fB\-V\fR|\fB\-\-MQTT-version\fR \fB31\fR|\fB311\fR|\fB5\fR]
+.br
+[\fB\-q\fR|\fB\-\-qos\fR \fB0\fR|\fB1\fR|\fB2\fR]
+[\fB\-r\fR|\fB\-\-retained\fR]
+[\fB\-n\fR|\fB\-\-null-message\fR]
+[\fB\-m\fR|\fB\-\-message\fR \fImessage\fR]
+[\fB\-f\fR|\fB\-\-filename\fR \fIfilename\fR]
+[\fB\-\-delimiter\fR \fIdelimiter\fR]
+[\fB\-\-maxdatalen\fR \fImaxdatalen\fR]
+.br
+[\fB\-\-message-expiry\fR \fIexpiry-interval\fR]
+[\fB\-\-user-property\fR \fIname\fR \fIvalue\fR]
+.br
+[\fB\-\-quiet\fR]
+[\fB\-\-verbose\fR]
+[\fB\-\-trace\fR \fBmin\fR|\fBmax\fR|\fBerror\fR|\fBprotocol\fR]
+.br
+[\fB\-\-will-topic\fR \fIwill-topic\fR]
+[\fB\-\-will-payload\fR \fIwill-payload\fR]
+[\fB\-\-will-retain\fR]
+[\fB\-\-will-qos\fR \fB0\fR|\fB1\fR|\fB2\fR]
+.br
+[\fB\-\-cafile\fR \fIcafile\fR]
+[\fB\-\-capath\fR \fIcapath\fR]
+[\fB\-\-cert\fR \fIcertfile\fR]
+[\fB\-\-key\fR \fIkeyfile\fR]
+[\fB\-\-keypass\fR \fIpassword\fR]
+[\fB\-\-ciphers\fR \fIcipher-string\fR]
+[\fB\-\-insecure\fR]
+
+
+.SH DESCRIPTION
+.B paho_c_pub
+sends data to an MQTT server using the Eclipse Paho C client asynchronous library (MQTTAsync).
+MQTT is a protocol, operating over TCP/IP, which allows programs to easily communicate
+with each other through a server. Messages are published to topics and delivered to any subscribers to those topics.
+The corresponding subscriber program \fBpaho_c_sub\fR allows the receipt of MQTT messages.
+.PP
+The default mode of operation is to read input from stdin, sending a separate message for each line read. Options exist
+to change this mode to send a one-off message, of 0 length (\fB-n\fR), a given string (\fB-m\fR), or the contents of a file (\fB-f\fR).
+
+.SH "OPTIONS"
+.TP
+.PD 0
+.BI \-t
+.TP
+.PD
+.B \-\-topic
+The MQTT topic to publish the data to.
+.TP
+.PD 0
+.BI \-c
+.TP
+.PD
+.B \-\-connection
+The MQTT URI to connect to, a combination of transport prefix, host, port and for websockets, topic.
+To connect using TCP use the tcp prefix, for example: \fBtcp://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR.
+An example using SSL/TLS: \fBssl://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR.
+An example for websockets, insecure: \fBws://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR\fB/\fR\fItopic\fR, and
+secure: \fBwss://\fR\fIlocalhost\fR\fB:\fR\fI80\fR\fB/\fR\fItopic\fR.
+.TP
+.PD 0
+.BI \-h
+.TP
+.PD
+.B \-\-host
+The TCP/IP host name of the MQTT server to connect to. Along with the \fB--port\fR option, an older alternative to using \fB--connection\fR.
+.TP
+.PD 0
+.BI \-p
+.TP
+.PD
+.B \-\-port
+The TCP/IP port number of the MQTT server to connect to. Along with the \fB--host\fR option, an older alternative to using \fB--connection\fR.
+.TP
+.PD 0
+.BI \-q
+.TP
+.PD
+.B \-\-qos
+The MQTT QoS on which to publish the message. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR.
+.TP
+.PD 0
+.BI \-V
+.TP
+.PD
+.B \-\-MQTTversion
+The version of the MQTT protocol to use. Valid options are \fB31\fR (or \fBmqttv31\fR), \fB311\fR (\fBmqttv311\fR) and \fB5\fR (or \fBmqttv5\fR).
+If MQTT version 5 is used, then some additional options are valid, such as \fB--message-expiry\fR and \fB--user-property\fR.
+.TP
+.PD
+.B \-\-quiet
+Do not print error messages.
+.TP
+.PD
+.B \-\-trace
+Print library internal trace. Valid levels are \fBmin\fR, \fBmax\fR, \fBerror\fR and \fprotocol\fR.
+.TP
+.PD 0
+.BI \-r
+.TP
+.PD
+.B \-\-retained
+Publish messages with the MQTT retained flag set.
+.TP
+.PD 0
+.BI \-n
+.TP
+.PD
+.B \-\-null-message
+Publish a 0-length message.
+.TP
+.PD 0
+.BI \-m
+.TP
+.PD
+.B \-\-message
+Publish a one off message with the payload supplied.
+.TP
+.PD 0
+.BI \-f
+.TP
+.PD
+.B \-\-filename
+Publish a one off message with the contents of the file whose name is given.
+.TP
+.PD
+.B \-\-message-expiry
+[MQTT version 5 only] Sets the expiry interval property of messages in seconds.
+.TP
+.PD
+.B \-\-user-property
+[MQTT version 5 only] Sets a user property of sent messages. A pair of strings, name and value.
+.TP
+.PD
+.B \-\-will-topic
+Sets the MQTT will message topic to publish to. If the application ends without sending an MQTT disconnect, the
+will message will be published to this topic.
+.TP
+.PD
+.B \-\-will-payload
+Only used if \fBwill-topic\fR is set. Sets the MQTT will message to be published.
+.TP
+.PD
+.B \-\-will-qos
+Only used if \fBwill-topic\fR is set. Sets the MQTT QoS at which the will message is published. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR.
+.TP
+.PD
+.B \-\-will-retain
+Only used if \fBwill-topic\fR is set. Sets the MQTT retained flag on the will message.
+.TP
+.PD
+.B \-\-cafile
+Only used with a TLS connection. The name of a file for the OpenSSL trust store.
+.TP
+.PD
+.B \-\-capath
+Only used with a TLS connection. The name of a directory holding OpenSSL trusted certificates.
+.TP
+.PD
+.B \-\-cert
+Only used with a TLS connection. The name of a file for the TLS keystore containing a client certificate to be presented.
+.TP
+.PD
+.B \-\-key
+Only used with a TLS connection. The name of a file containing the client private key.
+.TP
+.PD
+.B \-\-keypass
+Only used with a TLS connection. The password for the client private key file, if needed.
+.TP
+.PD
+.B \-\-ciphers
+Only used with a TLS connection. A list of cipher suites that the client will present to the server during the TLS handshake.
+.TP
+.PD
+.B \-\-insecure
+Only used with a TLS connection. Don't check that the server certificate common name matches the hostname.
+
+
+
+
+
diff --git a/lib/libpaho-mqtt/share/man/man1/paho_c_sub.1 b/lib/libpaho-mqtt/share/man/man1/paho_c_sub.1
new file mode 100644
index 0000000..0f69cef
--- /dev/null
+++ b/lib/libpaho-mqtt/share/man/man1/paho_c_sub.1
@@ -0,0 +1,170 @@
+.TH PAHO_C_SUB 1L "31 July 2018 (v1.3.0)" http://eclipse.org/paho
+
+.SH NAME
+paho_c_sub \- receive (subscribe to) data from an MQTT server
+
+.SH SYNOPSIS
+.B paho_c_sub
+[\fItopic\fR]
+[\fB\-t\fR|\fB\-\-topic\fR \fItopic\fR]
+[\fB\-c\fR|\fB\-\-connection\fR \fIconnection\fR]
+[\fB\-h\fR|\fB\-\-host\fR \fIhostname\fR]
+[\fB\-p\fR|\fB\-\-port\fR \fIportnumber\fR]
+[\fB\-i\fR|\fB\-\-clientid\fR \fIclientid\fR]
+[\fB\-u\fR|\fB\-\-username\fR \fIusername\fR]
+[\fB\-P\fR|\fB\-\-password\fR \fIpassword\fR]
+[\fB\-k\fR|\fB\-\-keepalive\fR \fIkeepalive-timeout\fR]
+[\fB\-V\fR|\fB\-\-MQTT-version\fR \fB31\fR|\fB311\fR|\fB5\fR]
+.br
+[\fB\-q\fR|\fB\-\-qos\fR \fB0\fR|\fB1\fR|\fB2\fR]
+[\fB\-R\fR|\fB\-\-no-retained\fR]
+[\fB\-\-delimiter\fR \fIdelimiter\fR]
+[\fB\-\-no-delimiter\fR]
+.br
+[\fB\-\-quiet\fR]
+[\fB\-\-verbose\fR]
+[\fB\-\-trace\fR \fBmin\fR|\fBmax\fR|\fBerror\fR|\fBprotocol\fR]
+.br
+[\fB\-\-will-topic\fR \fIwill-topic\fR]
+[\fB\-\-will-payload\fR \fIwill-payload\fR]
+[\fB\-\-will-retain\fR]
+[\fB\-\-will-qos\fR \fB0\fR|\fB1\fR|\fB2\fR]
+.br
+[\fB\-\-cafile\fR \fIcafile\fR]
+[\fB\-\-capath\fR \fIcapath\fR]
+[\fB\-\-cert\fR \fIcertfile\fR]
+[\fB\-\-key\fR \fIkeyfile\fR]
+[\fB\-\-keypass\fR \fIpassword\fR]
+[\fB\-\-ciphers\fR \fIcipher-string\fR]
+[\fB\-\-insecure\fR]
+
+
+.SH DESCRIPTION
+.B paho_c_sub
+receives data from an MQTT server using the Eclipse Paho C client asynchronous library (MQTTAsync).
+MQTT is a protocol, operating over TCP/IP, which allows programs to easily communicate
+with each other through a server. Messages are published to topics and delivered to any subscribers to those topics.
+The corresponding publisher program \fBpaho_c_pub\fR allows MQTT messages to be sent.
+.PP
+The default mode of operation is to output each message to stdout terminated by the delimiter.
+
+.SH "OPTIONS"
+.TP
+.PD 0
+.BI \-t
+.TP
+.PD
+.B \-\-topic
+The MQTT topic to publish the data to.
+.TP
+.PD 0
+.BI \-c
+.TP
+.PD
+.B \-\-connection
+The MQTT URI to connect to, a combination of transport prefix, host, port and for websockets, topic.
+To connect using TCP use the tcp prefix, for example: \fBtcp://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR.
+An example using SSL/TLS: \fBssl://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR.
+An example for websockets, insecure: \fBws://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR\fB/\fR\fItopic\fR, and
+secure: \fBwss://\fR\fIlocalhost\fR\fB:\fR\fI80\fR\fB/\fR\fItopic\fR.
+.TP
+.PD 0
+.BI \-h
+.TP
+.PD
+.B \-\-host
+The TCP/IP host name of the MQTT server to connect to. Along with the \fB--port\fR option, an older alternative to using \fB--connection\fR.
+.TP
+.PD 0
+.BI \-p
+.TP
+.PD
+.B \-\-port
+The TCP/IP port number of the MQTT server to connect to. Along with the \fB--host\fR option, an older alternative to using \fB--connection\fR.
+.TP
+.PD 0
+.BI \-q
+.TP
+.PD
+.B \-\-qos
+The MQTT QoS on which to publish the message. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR.
+.TP
+.PD 0
+.BI \-V
+.TP
+.PD
+.B \-\-MQTTversion
+The version of the MQTT protocol to use. Valid options are \fB31\fR (or \fBmqttv31\fR), \fB311\fR (\fBmqttv311\fR) and \fB5\fR (or \fBmqttv5\fR).
+.TP
+.PD
+.B \-\-quiet
+Do not print error messages.
+.TP
+.PD
+.B \-\-trace
+Print library internal trace. Valid levels are \fBmin\fR, \fBmax\fR, \fBerror\fR and \fprotocol\fR.
+.TP
+.PD 0
+.BI \-R
+.TP
+.PD
+.B \-\-no-retained
+Do not print messages which have the MQTT retained flag set.
+.TP
+.PD
+.B \-\-delimiter
+The delimiter string to append to each message when printing. Defaults to newline.
+.TP
+.PD
+.B \-\-no-delimiter
+Do not add a delimiter to each message when printing.
+.TP
+.PD
+.B \-\-will-topic
+Sets the MQTT will message topic to publish to. If the application ends without sending an MQTT disconnect, the
+will message will be published to this topic.
+.TP
+.PD
+.B \-\-will-payload
+Only used if \fBwill-topic\fR is set. Sets the MQTT will message to be published.
+.TP
+.PD
+.B \-\-will-qos
+Only used if \fBwill-topic\fR is set. Sets the MQTT QoS at which the will message is published. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR.
+.TP
+.PD
+.B \-\-will-retain
+Only used if \fBwill-topic\fR is set. Sets the MQTT retained flag on the will message.
+.TP
+.PD
+.B \-\-cafile
+Only used with a TLS connection. The name of a file for the OpenSSL trust store.
+.TP
+.PD
+.B \-\-capath
+Only used with a TLS connection. The name of a directory holding OpenSSL trusted certificates.
+.TP
+.PD
+.B \-\-cert
+Only used with a TLS connection. The name of a file for the TLS keystore containing a client certificate to be presented.
+.TP
+.PD
+.B \-\-key
+Only used with a TLS connection. The name of a file containing the client private key.
+.TP
+.PD
+.B \-\-keypass
+Only used with a TLS connection. The password for the client private key file, if needed.
+.TP
+.PD
+.B \-\-ciphers
+Only used with a TLS connection. A list of cipher suites that the client will present to the server during the TLS handshake.
+.TP
+.PD
+.B \-\-insecure
+Only used with a TLS connection. Don't check that the server certificate common name matches the hostname.
+
+
+
+
+
diff --git a/lib/libpaho-mqtt/share/man/man1/paho_cs_pub.1 b/lib/libpaho-mqtt/share/man/man1/paho_cs_pub.1
new file mode 100644
index 0000000..4e8f4ad
--- /dev/null
+++ b/lib/libpaho-mqtt/share/man/man1/paho_cs_pub.1
@@ -0,0 +1,199 @@
+.TH PAHO_CS_PUB 1L "31 July 2018 (v1.3.0)" http://eclipse.org/paho
+
+.SH NAME
+paho_cs_pub \- send (publish) data to an MQTT server
+
+.SH SYNOPSIS
+.B paho_cs_pub
+[\fItopic\fR]
+[\fB\-t\fR|\fB\-\-topic\fR \fItopic\fR]
+[\fB\-c\fR|\fB\-\-connection\fR \fIconnection\fR]
+[\fB\-h\fR|\fB\-\-host\fR \fIhostname\fR]
+[\fB\-p\fR|\fB\-\-port\fR \fIportnumber\fR]
+[\fB\-i\fR|\fB\-\-clientid\fR \fIclientid\fR]
+[\fB\-u\fR|\fB\-\-username\fR \fIusername\fR]
+[\fB\-P\fR|\fB\-\-password\fR \fIpassword\fR]
+[\fB\-k\fR|\fB\-\-keepalive\fR \fIkeepalive-timeout\fR]
+[\fB\-V\fR|\fB\-\-MQTT-version\fR \fB31\fR|\fB311\fR|\fB5\fR]
+.br
+[\fB\-q\fR|\fB\-\-qos\fR \fB0\fR|\fB1\fR|\fB2\fR]
+[\fB\-r\fR|\fB\-\-retained\fR]
+[\fB\-n\fR|\fB\-\-null-message\fR]
+[\fB\-m\fR|\fB\-\-message\fR \fImessage\fR]
+[\fB\-f\fR|\fB\-\-filename\fR \fIfilename\fR]
+[\fB\-\-delimiter\fR \fIdelimiter\fR]
+[\fB\-\-maxdatalen\fR \fImaxdatalen\fR]
+.br
+[\fB\-\-message-expiry\fR \fIexpiry-interval\fR]
+[\fB\-\-user-property\fR \fIname\fR \fIvalue\fR]
+.br
+[\fB\-\-quiet\fR]
+[\fB\-\-verbose\fR]
+[\fB\-\-trace\fR \fBmin\fR|\fBmax\fR|\fBerror\fR|\fBprotocol\fR]
+.br
+[\fB\-\-will-topic\fR \fIwill-topic\fR]
+[\fB\-\-will-payload\fR \fIwill-payload\fR]
+[\fB\-\-will-retain\fR]
+[\fB\-\-will-qos\fR \fB0\fR|\fB1\fR|\fB2\fR]
+.br
+[\fB\-\-cafile\fR \fIcafile\fR]
+[\fB\-\-capath\fR \fIcapath\fR]
+[\fB\-\-cert\fR \fIcertfile\fR]
+[\fB\-\-key\fR \fIkeyfile\fR]
+[\fB\-\-keypass\fR \fIpassword\fR]
+[\fB\-\-ciphers\fR \fIcipher-string\fR]
+[\fB\-\-insecure\fR]
+
+
+.SH DESCRIPTION
+.B paho_cs_pub
+sends data to an MQTT server using the Eclipse Paho C client synchronous library (MQTTClient).
+MQTT is a protocol, operating over TCP/IP, which allows programs to easily communicate
+with each other through a server. Messages are published to topics and delivered to any subscribers to those topics.
+The corresponding subscriber program \fBpaho_cs_sub\fR allows the receipt of MQTT messages.
+.PP
+The default mode of operation is to read input from stdin, sending a separate message for each line read. Options exist
+to change this mode to send a one-off message, of 0 length (\fB-n\fR), a given string (\fB-m\fR), or the contents of a file (\fB-f\fR).
+
+.SH "OPTIONS"
+.TP
+.PD 0
+.BI \-t
+.TP
+.PD
+.B \-\-topic
+The MQTT topic to publish the data to.
+.TP
+.PD 0
+.BI \-c
+.TP
+.PD
+.B \-\-connection
+The MQTT URI to connect to, a combination of transport prefix, host, port and for websockets, topic.
+To connect using TCP use the tcp prefix, for example: \fBtcp://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR.
+An example using SSL/TLS: \fBssl://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR.
+An example for websockets, insecure: \fBws://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR\fB/\fR\fItopic\fR, and
+secure: \fBwss://\fR\fIlocalhost\fR\fB:\fR\fI80\fR\fB/\fR\fItopic\fR.
+.TP
+.PD 0
+.BI \-h
+.TP
+.PD
+.B \-\-host
+The TCP/IP host name of the MQTT server to connect to. Along with the \fB--port\fR option, an older alternative to using \fB--connection\fR.
+.TP
+.PD 0
+.BI \-p
+.TP
+.PD
+.B \-\-port
+The TCP/IP port number of the MQTT server to connect to. Along with the \fB--host\fR option, an older alternative to using \fB--connection\fR.
+.TP
+.PD 0
+.BI \-q
+.TP
+.PD
+.B \-\-qos
+The MQTT QoS on which to publish the message. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR.
+.TP
+.PD 0
+.BI \-V
+.TP
+.PD
+.B \-\-MQTTversion
+The version of the MQTT protocol to use. Valid options are \fB31\fR (or \fBmqttv31\fR), \fB311\fR (\fBmqttv311\fR) and \fB5\fR (or \fBmqttv5\fR).
+If MQTT version 5 is used, then some additional options are valid, such as \fB--message-expiry\fR and \fB--user-property\fR.
+.TP
+.PD
+.B \-\-quiet
+Do not print error messages.
+.TP
+.PD
+.B \-\-trace
+Print library internal trace. Valid levels are \fBmin\fR, \fBmax\fR, \fBerror\fR and \fprotocol\fR.
+.TP
+.PD 0
+.BI \-r
+.TP
+.PD
+.B \-\-retained
+Publish messages with the MQTT retained flag set.
+.TP
+.PD 0
+.BI \-n
+.TP
+.PD
+.B \-\-null-message
+Publish a 0-length message.
+.TP
+.PD 0
+.BI \-m
+.TP
+.PD
+.B \-\-message
+Publish a one off message with the payload supplied.
+.TP
+.PD 0
+.BI \-f
+.TP
+.PD
+.B \-\-filename
+Publish a one off message with the contents of the file whose name is given.
+.TP
+.PD
+.B \-\-message-expiry
+[MQTT version 5 only] Sets the expiry interval property of messages in seconds.
+.TP
+.PD
+.B \-\-user-property
+[MQTT version 5 only] Sets a user property of sent messages. A pair of strings, name and value.
+.TP
+.PD
+.B \-\-will-topic
+Sets the MQTT will message topic to publish to. If the application ends without sending an MQTT disconnect, the
+will message will be published to this topic.
+.TP
+.PD
+.B \-\-will-payload
+Only used if \fBwill-topic\fR is set. Sets the MQTT will message to be published.
+.TP
+.PD
+.B \-\-will-qos
+Only used if \fBwill-topic\fR is set. Sets the MQTT QoS at which the will message is published. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR.
+.TP
+.PD
+.B \-\-will-retain
+Only used if \fBwill-topic\fR is set. Sets the MQTT retained flag on the will message.
+.TP
+.PD
+.B \-\-cafile
+Only used with a TLS connection. The name of a file for the OpenSSL trust store.
+.TP
+.PD
+.B \-\-capath
+Only used with a TLS connection. The name of a directory holding OpenSSL trusted certificates.
+.TP
+.PD
+.B \-\-cert
+Only used with a TLS connection. The name of a file for the TLS keystore containing a client certificate to be presented.
+.TP
+.PD
+.B \-\-key
+Only used with a TLS connection. The name of a file containing the client private key.
+.TP
+.PD
+.B \-\-keypass
+Only used with a TLS connection. The password for the client private key file, if needed.
+.TP
+.PD
+.B \-\-ciphers
+Only used with a TLS connection. A list of cipher suites that the client will present to the server during the TLS handshake.
+.TP
+.PD
+.B \-\-insecure
+Only used with a TLS connection. Don't check that the server certificate common name matches the hostname.
+
+
+
+
+
diff --git a/lib/libpaho-mqtt/share/man/man1/paho_cs_sub.1 b/lib/libpaho-mqtt/share/man/man1/paho_cs_sub.1
new file mode 100644
index 0000000..7cd2004
--- /dev/null
+++ b/lib/libpaho-mqtt/share/man/man1/paho_cs_sub.1
@@ -0,0 +1,170 @@
+.TH PAHO_CS_SUB 1L "31 July 2018 (v1.3.0)" http://eclipse.org/paho
+
+.SH NAME
+paho_cs_sub \- receive (subscribe to) data from an MQTT server
+
+.SH SYNOPSIS
+.B paho_cs_sub
+[\fItopic\fR]
+[\fB\-t\fR|\fB\-\-topic\fR \fItopic\fR]
+[\fB\-c\fR|\fB\-\-connection\fR \fIconnection\fR]
+[\fB\-h\fR|\fB\-\-host\fR \fIhostname\fR]
+[\fB\-p\fR|\fB\-\-port\fR \fIportnumber\fR]
+[\fB\-i\fR|\fB\-\-clientid\fR \fIclientid\fR]
+[\fB\-u\fR|\fB\-\-username\fR \fIusername\fR]
+[\fB\-P\fR|\fB\-\-password\fR \fIpassword\fR]
+[\fB\-k\fR|\fB\-\-keepalive\fR \fIkeepalive-timeout\fR]
+[\fB\-V\fR|\fB\-\-MQTT-version\fR \fB31\fR|\fB311\fR|\fB5\fR]
+.br
+[\fB\-q\fR|\fB\-\-qos\fR \fB0\fR|\fB1\fR|\fB2\fR]
+[\fB\-R\fR|\fB\-\-no-retained\fR]
+[\fB\-\-delimiter\fR \fIdelimiter\fR]
+[\fB\-\-no-delimiter\fR]
+.br
+[\fB\-\-quiet\fR]
+[\fB\-\-verbose\fR]
+[\fB\-\-trace\fR \fBmin\fR|\fBmax\fR|\fBerror\fR|\fBprotocol\fR]
+.br
+[\fB\-\-will-topic\fR \fIwill-topic\fR]
+[\fB\-\-will-payload\fR \fIwill-payload\fR]
+[\fB\-\-will-retain\fR]
+[\fB\-\-will-qos\fR \fB0\fR|\fB1\fR|\fB2\fR]
+.br
+[\fB\-\-cafile\fR \fIcafile\fR]
+[\fB\-\-capath\fR \fIcapath\fR]
+[\fB\-\-cert\fR \fIcertfile\fR]
+[\fB\-\-key\fR \fIkeyfile\fR]
+[\fB\-\-keypass\fR \fIpassword\fR]
+[\fB\-\-ciphers\fR \fIcipher-string\fR]
+[\fB\-\-insecure\fR]
+
+
+.SH DESCRIPTION
+.B paho_cs_sub
+receives data from an MQTT server using the Eclipse Paho C client synchronous library (MQTTClient).
+MQTT is a protocol, operating over TCP/IP, which allows programs to easily communicate
+with each other through a server. Messages are published to topics and delivered to any subscribers to those topics.
+The corresponding publisher program \fBpaho_cs_pub\fR allows MQTT messages to be sent.
+.PP
+The default mode of operation is to output each message to stdout terminated by the delimiter.
+
+.SH "OPTIONS"
+.TP
+.PD 0
+.BI \-t
+.TP
+.PD
+.B \-\-topic
+The MQTT topic to publish the data to.
+.TP
+.PD 0
+.BI \-c
+.TP
+.PD
+.B \-\-connection
+The MQTT URI to connect to, a combination of transport prefix, host, port and for websockets, topic.
+To connect using TCP use the tcp prefix, for example: \fBtcp://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR.
+An example using SSL/TLS: \fBssl://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR.
+An example for websockets, insecure: \fBws://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR\fB/\fR\fItopic\fR, and
+secure: \fBwss://\fR\fIlocalhost\fR\fB:\fR\fI80\fR\fB/\fR\fItopic\fR.
+.TP
+.PD 0
+.BI \-h
+.TP
+.PD
+.B \-\-host
+The TCP/IP host name of the MQTT server to connect to. Along with the \fB--port\fR option, an older alternative to using \fB--connection\fR.
+.TP
+.PD 0
+.BI \-p
+.TP
+.PD
+.B \-\-port
+The TCP/IP port number of the MQTT server to connect to. Along with the \fB--host\fR option, an older alternative to using \fB--connection\fR.
+.TP
+.PD 0
+.BI \-q
+.TP
+.PD
+.B \-\-qos
+The MQTT QoS on which to publish the message. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR.
+.TP
+.PD 0
+.BI \-V
+.TP
+.PD
+.B \-\-MQTTversion
+The version of the MQTT protocol to use. Valid options are \fB31\fR (or \fBmqttv31\fR), \fB311\fR (\fBmqttv311\fR) and \fB5\fR (or \fBmqttv5\fR).
+.TP
+.PD
+.B \-\-quiet
+Do not print error messages.
+.TP
+.PD
+.B \-\-trace
+Print library internal trace. Valid levels are \fBmin\fR, \fBmax\fR, \fBerror\fR and \fprotocol\fR.
+.TP
+.PD 0
+.BI \-R
+.TP
+.PD
+.B \-\-no-retained
+Do not print messages which have the MQTT retained flag set.
+.TP
+.PD
+.B \-\-delimiter
+The delimiter string to append to each message when printing. Defaults to newline.
+.TP
+.PD
+.B \-\-no-delimiter
+Do not add a delimiter to each message when printing.
+.TP
+.PD
+.B \-\-will-topic
+Sets the MQTT will message topic to publish to. If the application ends without sending an MQTT disconnect, the
+will message will be published to this topic.
+.TP
+.PD
+.B \-\-will-payload
+Only used if \fBwill-topic\fR is set. Sets the MQTT will message to be published.
+.TP
+.PD
+.B \-\-will-qos
+Only used if \fBwill-topic\fR is set. Sets the MQTT QoS at which the will message is published. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR.
+.TP
+.PD
+.B \-\-will-retain
+Only used if \fBwill-topic\fR is set. Sets the MQTT retained flag on the will message.
+.TP
+.PD
+.B \-\-cafile
+Only used with a TLS connection. The name of a file for the OpenSSL trust store.
+.TP
+.PD
+.B \-\-capath
+Only used with a TLS connection. The name of a directory holding OpenSSL trusted certificates.
+.TP
+.PD
+.B \-\-cert
+Only used with a TLS connection. The name of a file for the TLS keystore containing a client certificate to be presented.
+.TP
+.PD
+.B \-\-key
+Only used with a TLS connection. The name of a file containing the client private key.
+.TP
+.PD
+.B \-\-keypass
+Only used with a TLS connection. The password for the client private key file, if needed.
+.TP
+.PD
+.B \-\-ciphers
+Only used with a TLS connection. A list of cipher suites that the client will present to the server during the TLS handshake.
+.TP
+.PD
+.B \-\-insecure
+Only used with a TLS connection. Don't check that the server certificate common name matches the hostname.
+
+
+
+
+