|
@@ -0,0 +1,1717 @@
|
|
|
+/*******************************************************************************
|
|
|
+ * Copyright (c) 2009, 2017 IBM Corp.
|
|
|
+ *
|
|
|
+ * All rights reserved. This program and the accompanying materials
|
|
|
+ * are made available under the terms of the Eclipse Public License v1.0
|
|
|
+ * and Eclipse Distribution License v1.0 which accompany this distribution.
|
|
|
+ *
|
|
|
+ * The Eclipse Public License is available at
|
|
|
+ * http://www.eclipse.org/legal/epl-v10.html
|
|
|
+ * 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
|
|
|
+ *******************************************************************************/
|
|
|
+
|
|
|
+/********************************************************************/
|
|
|
+
|
|
|
+/**
|
|
|
+ * @cond MQTTAsync_main
|
|
|
+ * @mainpage Asynchronous MQTT client library for C
|
|
|
+ *
|
|
|
+ * © Copyright IBM Corp. 2009, 2017
|
|
|
+ *
|
|
|
+ * @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(__cplusplus)
|
|
|
+ extern "C" {
|
|
|
+#endif
|
|
|
+
|
|
|
+#if !defined(MQTTASYNC_H)
|
|
|
+#define MQTTASYNC_H
|
|
|
+
|
|
|
+#if defined(WIN32) || defined(WIN64)
|
|
|
+ #define DLLImport __declspec(dllimport)
|
|
|
+ #define DLLExport __declspec(dllexport)
|
|
|
+#else
|
|
|
+ #define DLLImport extern
|
|
|
+ #define DLLExport __attribute__ ((visibility ("default")))
|
|
|
+#endif
|
|
|
+
|
|
|
+#include <stdio.h>
|
|
|
+/*
|
|
|
+/// @endcond
|
|
|
+*/
|
|
|
+
|
|
|
+#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
|
|
|
+
|
|
|
+/**
|
|
|
+ * 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
|
|
|
+/**
|
|
|
+ * 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)
|
|
|
+ */
|
|
|
+DLLExport 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 */
|
|
|
+ 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 ndicates 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;
|
|
|
+} MQTTAsync_message;
|
|
|
+
|
|
|
+#define MQTTAsync_message_initializer { {'M', 'Q', 'T', 'M'}, 0, 0, NULL, 0, 0, 0, 0 }
|
|
|
+
|
|
|
+/**
|
|
|
+ * 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.
|
|
|
+ * @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 a boolean value indicating whether or not
|
|
|
+ * the message has been safely received by the client application. Returning
|
|
|
+ * true indicates that the message has been successfully handled.
|
|
|
+ * Returning false 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.
|
|
|
+ */
|
|
|
+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.
|
|
|
+ * @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.
|
|
|
+ * @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.
|
|
|
+ * @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);
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+/** 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 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. */
|
|
|
+ int qos;
|
|
|
+ /** For subscribeMany, 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;
|
|
|
+ char* destinationName;
|
|
|
+ } pub;
|
|
|
+ /* For connect, the server connected to, MQTT version used, and sessionPresent flag */
|
|
|
+ struct
|
|
|
+ {
|
|
|
+ char* serverURI;
|
|
|
+ int MQTTVersion;
|
|
|
+ int sessionPresent;
|
|
|
+ } connect;
|
|
|
+ } alt;
|
|
|
+} MQTTAsync_successData;
|
|
|
+
|
|
|
+/**
|
|
|
+ * 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.
|
|
|
+ * @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 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.
|
|
|
+ * @param context A pointer to the <i>context</i> value originally passed to
|
|
|
+ * ::MQTTAsync_responseOptions, which contains any application-specific context.
|
|
|
+ * @param response Any failure data associated with the API completion.
|
|
|
+ */
|
|
|
+typedef void MQTTAsync_onFailure(void* context, MQTTAsync_failureData* response);
|
|
|
+
|
|
|
+typedef struct
|
|
|
+{
|
|
|
+ /** The eyecatcher for this structure. Must be MQTR */
|
|
|
+ char struct_id[4];
|
|
|
+ /** The version number of this structure. Must be 0 */
|
|
|
+ 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;
|
|
|
+ MQTTAsync_token token; /* output */
|
|
|
+} MQTTAsync_responseOptions;
|
|
|
+
|
|
|
+#define MQTTAsync_responseOptions_initializer { {'M', 'Q', 'T', 'R'}, 0, NULL, NULL, 0, 0 }
|
|
|
+
|
|
|
+
|
|
|
+/**
|
|
|
+ * 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. You can set this to NULL if your application doesn't handle
|
|
|
+ * receipt of 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.
|
|
|
+ */
|
|
|
+DLLExport int MQTTAsync_setCallbacks(MQTTAsync handle, void* context, MQTTAsync_connectionLost* cl,
|
|
|
+ MQTTAsync_messageArrived* ma, 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.
|
|
|
+ */
|
|
|
+DLLExport 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.
|
|
|
+ */
|
|
|
+DLLExport 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>.
|
|
|
+ * <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.
|
|
|
+ * @return ::MQTTASYNC_SUCCESS if the client is successfully created, otherwise
|
|
|
+ * an error code is returned.
|
|
|
+ */
|
|
|
+DLLExport int MQTTAsync_create(MQTTAsync* handle, const char* serverURI, const char* clientId,
|
|
|
+ int persistence_type, void* persistence_context);
|
|
|
+
|
|
|
+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 to allow messages to be sent when the client library is not connected. */
|
|
|
+ int sendWhileDisconnected;
|
|
|
+ /** the maximum number of messages allowed to be buffered while not connected. */
|
|
|
+ int maxBufferedMessages;
|
|
|
+} MQTTAsync_createOptions;
|
|
|
+
|
|
|
+#define MQTTAsync_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 0, 0, 100 }
|
|
|
+
|
|
|
+
|
|
|
+DLLExport 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 } }
|
|
|
+
|
|
|
+/**
|
|
|
+* 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 */
|
|
|
+ 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;
|
|
|
+
|
|
|
+} MQTTAsync_SSLOptions;
|
|
|
+
|
|
|
+#define MQTTAsync_SSLOptions_initializer { {'M', 'Q', 'T', 'S'}, 0, NULL, NULL, NULL, NULL, NULL, 1 }
|
|
|
+
|
|
|
+/**
|
|
|
+ * MQTTAsync_connectOptions defines several settings that control the way the
|
|
|
+ * client connects to an MQTT server. Default values are set in
|
|
|
+ * MQTTAsync_connectOptions_initializer.
|
|
|
+ */
|
|
|
+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 or 5.
|
|
|
+ * 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)
|
|
|
+ */
|
|
|
+ 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
|
|
|
+ */
|
|
|
+ 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> or <i>ssl</i>. 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?
|
|
|
+ */
|
|
|
+ int automaticReconnect;
|
|
|
+ /**
|
|
|
+ * Minimum retry interval in seconds. Doubled on each failed retry.
|
|
|
+ */
|
|
|
+ int minRetryInterval;
|
|
|
+ /**
|
|
|
+ * Maximum 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;
|
|
|
+} MQTTAsync_connectOptions;
|
|
|
+
|
|
|
+
|
|
|
+#define MQTTAsync_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 5, 60, 1, 10, NULL, NULL, NULL, 30, 0,\
|
|
|
+NULL, NULL, NULL, NULL, 0, NULL, 0, 0, 1, 60, {0, 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>
|
|
|
+ */
|
|
|
+DLLExport int MQTTAsync_connect(MQTTAsync handle, const MQTTAsync_connectOptions* options);
|
|
|
+
|
|
|
+
|
|
|
+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 SSL options */
|
|
|
+ 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;
|
|
|
+} MQTTAsync_disconnectOptions;
|
|
|
+
|
|
|
+#define MQTTAsync_disconnectOptions_initializer { {'M', 'Q', 'T', 'D'}, 0, 0, NULL, 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
|
|
|
+ */
|
|
|
+DLLExport 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.
|
|
|
+ */
|
|
|
+DLLExport 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.
|
|
|
+ */
|
|
|
+DLLExport 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.
|
|
|
+ */
|
|
|
+DLLExport int MQTTAsync_subscribeMany(MQTTAsync handle, int count, char* const* topic, 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.
|
|
|
+ */
|
|
|
+DLLExport 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.
|
|
|
+ */
|
|
|
+DLLExport 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 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.
|
|
|
+ */
|
|
|
+DLLExport int MQTTAsync_send(MQTTAsync handle, const char* destinationName, int payloadlen, 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 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.
|
|
|
+ */
|
|
|
+DLLExport 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.
|
|
|
+ */
|
|
|
+DLLExport 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
|
|
|
+DLLExport int MQTTAsync_isComplete(MQTTAsync handle, MQTTAsync_token token);
|
|
|
+
|
|
|
+
|
|
|
+/**
|
|
|
+ * Waits for a request corresponding to a token to complete.
|
|
|
+ *
|
|
|
+ * @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 if not.
|
|
|
+ */
|
|
|
+DLLExport 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.
|
|
|
+ */
|
|
|
+DLLExport 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 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.
|
|
|
+ */
|
|
|
+DLLExport void MQTTAsync_free(void* ptr);
|
|
|
+
|
|
|
+/**
|
|
|
+ * 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.
|
|
|
+ */
|
|
|
+DLLExport 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
|
|
|
+ */
|
|
|
+DLLExport 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.
|
|
|
+ * @param level the trace level of the message returned
|
|
|
+ * @param meesage 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
|
|
|
+ */
|
|
|
+DLLExport void MQTTAsync_setTraceCallback(MQTTAsync_traceCallback* callback);
|
|
|
+
|
|
|
+
|
|
|
+typedef struct
|
|
|
+{
|
|
|
+ const char* name;
|
|
|
+ const char* value;
|
|
|
+} MQTTAsync_nameValue;
|
|
|
+
|
|
|
+/**
|
|
|
+ * 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.
|
|
|
+ */
|
|
|
+DLLExport MQTTAsync_nameValue* MQTTAsync_getVersionInfo(void);
|
|
|
+
|
|
|
+
|
|
|
+/**
|
|
|
+ * @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. Note that it is a theoretically
|
|
|
+ * possible but unlikely event, that a success or failure callback could be called
|
|
|
+ * before function requesting the callback has returned. In this case the token
|
|
|
+ * delivered in the callback would not yet be known to the application program (see
|
|
|
+ * Race condition for MQTTAsync_token in MQTTAsync.c
|
|
|
+ * https://bugs.eclipse.org/bugs/show_bug.cgi?id=444093)
|
|
|
+ *
|
|
|
+ * @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 ::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"
|
|
|
+
|
|
|
+#define ADDRESS "tcp://localhost:1883"
|
|
|
+#define CLIENTID "ExampleClientPub"
|
|
|
+#define TOPIC "MQTT Examples"
|
|
|
+#define PAYLOAD "Hello World!"
|
|
|
+#define QOS 1
|
|
|
+#define TIMEOUT 10000L
|
|
|
+
|
|
|
+volatile MQTTAsync_token deliveredtoken;
|
|
|
+
|
|
|
+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 onDisconnect(void* context, MQTTAsync_successData* response)
|
|
|
+{
|
|
|
+ printf("Successful disconnection\n");
|
|
|
+ finished = 1;
|
|
|
+}
|
|
|
+
|
|
|
+
|
|
|
+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.context = client;
|
|
|
+
|
|
|
+ if ((rc = MQTTAsync_disconnect(client, &opts)) != MQTTASYNC_SUCCESS)
|
|
|
+ {
|
|
|
+ printf("Failed to start sendMessage, 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.context = client;
|
|
|
+
|
|
|
+ pubmsg.payload = PAYLOAD;
|
|
|
+ pubmsg.payloadlen = strlen(PAYLOAD);
|
|
|
+ pubmsg.qos = QOS;
|
|
|
+ pubmsg.retained = 0;
|
|
|
+ deliveredtoken = 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 main(int argc, char* argv[])
|
|
|
+{
|
|
|
+ MQTTAsync client;
|
|
|
+ MQTTAsync_connectOptions conn_opts = MQTTAsync_connectOptions_initializer;
|
|
|
+ MQTTAsync_message pubmsg = MQTTAsync_message_initializer;
|
|
|
+ MQTTAsync_token token;
|
|
|
+ int rc;
|
|
|
+
|
|
|
+ MQTTAsync_create(&client, ADDRESS, CLIENTID, MQTTCLIENT_PERSISTENCE_NONE, NULL);
|
|
|
+
|
|
|
+ MQTTAsync_setCallbacks(client, NULL, connlost, NULL, NULL);
|
|
|
+
|
|
|
+ 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) || defined(WIN64)
|
|
|
+ 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"
|
|
|
+
|
|
|
+#define ADDRESS "tcp://localhost:1883"
|
|
|
+#define CLIENTID "ExampleClientSub"
|
|
|
+#define TOPIC "MQTT Examples"
|
|
|
+#define PAYLOAD "Hello World!"
|
|
|
+#define QOS 1
|
|
|
+#define TIMEOUT 10000L
|
|
|
+
|
|
|
+volatile MQTTAsync_token deliveredtoken;
|
|
|
+
|
|
|
+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");
|
|
|
+ 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)
|
|
|
+{
|
|
|
+ int i;
|
|
|
+ char* payloadptr;
|
|
|
+
|
|
|
+ printf("Message arrived\n");
|
|
|
+ printf(" topic: %s\n", topicName);
|
|
|
+ printf(" message: ");
|
|
|
+
|
|
|
+ payloadptr = message->payload;
|
|
|
+ for(i=0; i<message->payloadlen; i++)
|
|
|
+ {
|
|
|
+ putchar(*payloadptr++);
|
|
|
+ }
|
|
|
+ putchar('\n');
|
|
|
+ MQTTAsync_freeMessage(&message);
|
|
|
+ MQTTAsync_free(topicName);
|
|
|
+ return 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 ? response->code : 0);
|
|
|
+ finished = 1;
|
|
|
+}
|
|
|
+
|
|
|
+
|
|
|
+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");
|
|
|
+
|
|
|
+ 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;
|
|
|
+
|
|
|
+ deliveredtoken = 0;
|
|
|
+
|
|
|
+ if ((rc = MQTTAsync_subscribe(client, TOPIC, QOS, &opts)) != MQTTASYNC_SUCCESS)
|
|
|
+ {
|
|
|
+ printf("Failed to start subscribe, return code %d\n", rc);
|
|
|
+ exit(EXIT_FAILURE);
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+
|
|
|
+int main(int argc, char* argv[])
|
|
|
+{
|
|
|
+ MQTTAsync client;
|
|
|
+ MQTTAsync_connectOptions conn_opts = MQTTAsync_connectOptions_initializer;
|
|
|
+ MQTTAsync_disconnectOptions disc_opts = MQTTAsync_disconnectOptions_initializer;
|
|
|
+ MQTTAsync_message pubmsg = MQTTAsync_message_initializer;
|
|
|
+ MQTTAsync_token token;
|
|
|
+ int rc;
|
|
|
+ int ch;
|
|
|
+
|
|
|
+ MQTTAsync_create(&client, ADDRESS, CLIENTID, MQTTCLIENT_PERSISTENCE_NONE, NULL);
|
|
|
+
|
|
|
+ MQTTAsync_setCallbacks(client, NULL, connlost, msgarrvd, NULL);
|
|
|
+
|
|
|
+ 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);
|
|
|
+ }
|
|
|
+
|
|
|
+ while (!subscribed)
|
|
|
+ #if defined(WIN32) || defined(WIN64)
|
|
|
+ Sleep(100);
|
|
|
+ #else
|
|
|
+ usleep(10000L);
|
|
|
+ #endif
|
|
|
+
|
|
|
+ if (finished)
|
|
|
+ goto exit;
|
|
|
+
|
|
|
+ do
|
|
|
+ {
|
|
|
+ ch = getchar();
|
|
|
+ } while (ch!='Q' && ch != 'q');
|
|
|
+
|
|
|
+ disc_opts.onSuccess = onDisconnect;
|
|
|
+ if ((rc = MQTTAsync_disconnect(client, &disc_opts)) != MQTTASYNC_SUCCESS)
|
|
|
+ {
|
|
|
+ printf("Failed to start disconnect, return code %d\n", rc);
|
|
|
+ exit(EXIT_FAILURE);
|
|
|
+ }
|
|
|
+ while (!disc_finished)
|
|
|
+ #if defined(WIN32) || defined(WIN64)
|
|
|
+ Sleep(100);
|
|
|
+ #else
|
|
|
+ usleep(10000L);
|
|
|
+ #endif
|
|
|
+
|
|
|
+exit:
|
|
|
+ MQTTAsync_destroy(&client);
|
|
|
+ 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
|
|
|
+ */
|
|
|
+
|
|
|
+
|
|
|
+#endif
|
|
|
+
|
|
|
+#ifdef __cplusplus
|
|
|
+ }
|
|
|
+#endif
|