MQTTAsync.h File Reference

#include "MQTTClientPersistence.h"

Go to the source code of this file.

Data Structures
struct	MQTTAsync_init_options
struct	MQTTAsync_message
struct	MQTTAsync_failureData
struct	MQTTAsync_successData
struct	MQTTAsync_responseOptions
struct	MQTTAsync_createOptions
struct	MQTTAsync_willOptions
struct	MQTTAsync_SSLOptions
struct	MQTTAsync_connectOptions
struct	MQTTAsync_disconnectOptions
struct	MQTTAsync_nameValue

Macros
#define	MQTTASYNC_SUCCESS   0
#define	MQTTASYNC_FAILURE   -1
#define	MQTTASYNC_PERSISTENCE_ERROR   -2
#define	MQTTASYNC_DISCONNECTED   -3
#define	MQTTASYNC_MAX_MESSAGES_INFLIGHT   -4
#define	MQTTASYNC_BAD_UTF8_STRING   -5
#define	MQTTASYNC_NULL_PARAMETER   -6
#define	MQTTASYNC_TOPICNAME_TRUNCATED   -7
#define	MQTTASYNC_BAD_STRUCTURE   -8
#define	MQTTASYNC_BAD_QOS   -9
#define	MQTTASYNC_NO_MORE_MSGIDS   -10
#define	MQTTASYNC_OPERATION_INCOMPLETE   -11
#define	MQTTASYNC_MAX_BUFFERED_MESSAGES   -12
#define	MQTTASYNC_SSL_NOT_SUPPORTED   -13
#define	MQTTVERSION_DEFAULT   0
#define	MQTTVERSION_3_1   3
#define	MQTTVERSION_3_1_1   4
#define	MQTT_BAD_SUBSCRIBE   0x80
#define	MQTTAsync_init_options_initializer   { {'M', 'Q', 'T', 'G'}, 0, 0 }
#define	MQTTAsync_message_initializer   { {'M', 'Q', 'T', 'M'}, 0, 0, NULL, 0, 0, 0, 0 }
#define	MQTTAsync_responseOptions_initializer   { {'M', 'Q', 'T', 'R'}, 0, NULL, NULL, 0, 0 }
#define	MQTTAsync_createOptions_initializer   { {'M', 'Q', 'C', 'O'}, 0, 0, 100 }
#define	MQTTAsync_willOptions_initializer   { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, { 0, NULL } }
#define	MQTTAsync_SSLOptions_initializer   { {'M', 'Q', 'T', 'S'}, 0, NULL, NULL, NULL, NULL, NULL, 1 }
#define	MQTTAsync_connectOptions_initializer
#define	MQTTAsync_disconnectOptions_initializer   { {'M', 'Q', 'T', 'D'}, 0, 0, NULL, NULL, NULL }
#define	MQTTASYNC_TRUE   1

Typedefs
typedef void *	MQTTAsync
typedef int	MQTTAsync_token
typedef int	MQTTAsync_messageArrived(void *context, char *topicName, int topicLen, MQTTAsync_message *message)
typedef void	MQTTAsync_deliveryComplete(void *context, MQTTAsync_token token)
typedef void	MQTTAsync_connectionLost(void *context, char *cause)
typedef void	MQTTAsync_connected(void *context, char *cause)
typedef void	MQTTAsync_onSuccess(void *context, MQTTAsync_successData *response)
typedef void	MQTTAsync_onFailure(void *context, MQTTAsync_failureData *response)
typedef void	MQTTAsync_traceCallback(enum MQTTASYNC_TRACE_LEVELS level, char *message)

Enumerations
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 }

Functions
void	MQTTAsync_global_init (MQTTAsync_init_options *inits)
DLLExport int	MQTTAsync_setCallbacks (MQTTAsync handle, void *context, MQTTAsync_connectionLost *cl, MQTTAsync_messageArrived *ma, MQTTAsync_deliveryComplete *dc)
DLLExport int	MQTTAsync_setConnected (MQTTAsync handle, void *context, MQTTAsync_connected *co)
DLLExport int	MQTTAsync_reconnect (MQTTAsync handle)
DLLExport int	MQTTAsync_create (MQTTAsync *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context)
DLLExport int	MQTTAsync_createWithOptions (MQTTAsync *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context, MQTTAsync_createOptions *options)
DLLExport int	MQTTAsync_connect (MQTTAsync handle, const MQTTAsync_connectOptions *options)
DLLExport int	MQTTAsync_disconnect (MQTTAsync handle, const MQTTAsync_disconnectOptions *options)
DLLExport int	MQTTAsync_isConnected (MQTTAsync handle)
DLLExport int	MQTTAsync_subscribe (MQTTAsync handle, const char *topic, int qos, MQTTAsync_responseOptions *response)
DLLExport int	MQTTAsync_subscribeMany (MQTTAsync handle, int count, char *const *topic, int *qos, MQTTAsync_responseOptions *response)
DLLExport int	MQTTAsync_unsubscribe (MQTTAsync handle, const char *topic, MQTTAsync_responseOptions *response)
DLLExport int	MQTTAsync_unsubscribeMany (MQTTAsync handle, int count, char *const *topic, MQTTAsync_responseOptions *response)
DLLExport int	MQTTAsync_send (MQTTAsync handle, const char *destinationName, int payloadlen, void *payload, int qos, int retained, MQTTAsync_responseOptions *response)
DLLExport int	MQTTAsync_sendMessage (MQTTAsync handle, const char *destinationName, const MQTTAsync_message *msg, MQTTAsync_responseOptions *response)
DLLExport int	MQTTAsync_getPendingTokens (MQTTAsync handle, MQTTAsync_token **tokens)
DLLExport int	MQTTAsync_isComplete (MQTTAsync handle, MQTTAsync_token token)
DLLExport int	MQTTAsync_waitForCompletion (MQTTAsync handle, MQTTAsync_token token, unsigned long timeout)
DLLExport void	MQTTAsync_freeMessage (MQTTAsync_message **msg)
DLLExport void	MQTTAsync_free (void *ptr)
DLLExport void	MQTTAsync_destroy (MQTTAsync *handle)
DLLExport void	MQTTAsync_setTraceLevel (enum MQTTASYNC_TRACE_LEVELS level)
DLLExport void	MQTTAsync_setTraceCallback (MQTTAsync_traceCallback *callback)
DLLExport MQTTAsync_nameValue *	MQTTAsync_getVersionInfo (void)

Macro Definition Documentation

MQTTASYNC_SUCCESS

#define MQTTASYNC_SUCCESS   0

Return code: No error. Indicates successful completion of an MQTT client operation.

MQTTASYNC_FAILURE

#define MQTTASYNC_FAILURE   -1

Return code: A generic error code indicating the failure of an MQTT client operation.

MQTTASYNC_PERSISTENCE_ERROR

#define MQTTASYNC_PERSISTENCE_ERROR   -2

MQTTASYNC_DISCONNECTED

#define MQTTASYNC_DISCONNECTED   -3

Return code: The client is disconnected.

MQTTASYNC_MAX_MESSAGES_INFLIGHT

#define MQTTASYNC_MAX_MESSAGES_INFLIGHT   -4

Return code: The maximum number of messages allowed to be simultaneously in-flight has been reached.

MQTTASYNC_BAD_UTF8_STRING

#define MQTTASYNC_BAD_UTF8_STRING   -5

Return code: An invalid UTF-8 string has been detected.

MQTTASYNC_NULL_PARAMETER

#define MQTTASYNC_NULL_PARAMETER   -6

Return code: A NULL parameter has been supplied when this is invalid.

MQTTASYNC_TOPICNAME_TRUNCATED

#define MQTTASYNC_TOPICNAME_TRUNCATED   -7

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.

MQTTASYNC_BAD_STRUCTURE

#define MQTTASYNC_BAD_STRUCTURE   -8

Return code: A structure parameter does not have the correct eyecatcher and version number.

MQTTASYNC_BAD_QOS

#define MQTTASYNC_BAD_QOS   -9

Return code: A qos parameter is not 0, 1 or 2

MQTTASYNC_NO_MORE_MSGIDS

#define MQTTASYNC_NO_MORE_MSGIDS   -10

Return code: All 65535 MQTT msgids are being used

MQTTASYNC_OPERATION_INCOMPLETE

#define MQTTASYNC_OPERATION_INCOMPLETE   -11

Return code: the request is being discarded when not complete

MQTTASYNC_MAX_BUFFERED_MESSAGES

#define MQTTASYNC_MAX_BUFFERED_MESSAGES   -12

Return code: no more messages can be buffered

MQTTASYNC_SSL_NOT_SUPPORTED

#define MQTTASYNC_SSL_NOT_SUPPORTED   -13

Return code: Attempting SSL connection using non-SSL version of library

MQTTVERSION_DEFAULT

#define MQTTVERSION_DEFAULT   0

Default MQTT version to connect with. Use 3.1.1 then fall back to 3.1

MQTTVERSION_3_1

#define MQTTVERSION_3_1   3

MQTT version to connect with: 3.1

MQTTVERSION_3_1_1

#define MQTTVERSION_3_1_1   4

MQTT version to connect with: 3.1.1

MQTT_BAD_SUBSCRIBE

#define MQTT_BAD_SUBSCRIBE   0x80

Bad return code from subscribe, as defined in the 3.1.1 specification

MQTTAsync_init_options_initializer

#define MQTTAsync_init_options_initializer   { {'M', 'Q', 'T', 'G'}, 0, 0 }

MQTTAsync_message_initializer

#define MQTTAsync_message_initializer   { {'M', 'Q', 'T', 'M'}, 0, 0, NULL, 0, 0, 0, 0 }

MQTTAsync_responseOptions_initializer

#define MQTTAsync_responseOptions_initializer   { {'M', 'Q', 'T', 'R'}, 0, NULL, NULL, 0, 0 }

MQTTAsync_createOptions_initializer

#define MQTTAsync_createOptions_initializer   { {'M', 'Q', 'C', 'O'}, 0, 0, 100 }

MQTTAsync_willOptions_initializer

#define MQTTAsync_willOptions_initializer   { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, { 0, NULL } }

MQTTAsync_SSLOptions_initializer

#define MQTTAsync_SSLOptions_initializer   { {'M', 'Q', 'T', 'S'}, 0, NULL, NULL, NULL, NULL, NULL, 1 }

MQTTAsync_connectOptions_initializer

#define MQTTAsync_connectOptions_initializer

Value:

{ {'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}}

MQTTAsync_disconnectOptions_initializer

#define MQTTAsync_disconnectOptions_initializer   { {'M', 'Q', 'T', 'D'}, 0, 0, NULL, NULL, NULL }

MQTTASYNC_TRUE

#define MQTTASYNC_TRUE   1

Tests whether a request corresponding to a token is complete.

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
token	An MQTTAsync_token associated with a request.

Returns

1 if the request has been completed, 0 if not.

Typedef Documentation

MQTTAsync

typedef void* MQTTAsync

A handle representing an MQTT client. A valid client handle is available following a successful call to MQTTAsync_create().

MQTTAsync_token

typedef int MQTTAsync_token

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()).

MQTTAsync_messageArrived

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 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.

Parameters

context	A pointer to the context value originally passed to MQTTAsync_setCallbacks(), which contains any application-specific context.
topicName	The topic associated with the received message.
topicLen	The length of the topic if there are one more NULL characters embedded in topicName, otherwise topicLen is 0. If topicLen is 0, the value returned by strlen(topicName) can be trusted. If topicLen is greater than 0, the full topic name can be retrieved by accessing topicName as a byte array of length topicLen.
message	The MQTTAsync_message structure for the received message. This structure contains the message payload and attributes.

Returns

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.

MQTTAsync_deliveryComplete

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 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.

Parameters

context	A pointer to the context value originally passed to MQTTAsync_setCallbacks(), which contains any application-specific context.
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.

MQTTAsync_connectionLost

typedef void MQTTAsync_connectionLost(void *context, char *cause)

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.

Parameters

context	A pointer to the context value originally passed to MQTTAsync_setCallbacks(), which contains any application-specific context.
cause	The reason for the disconnection. Currently, cause is always set to NULL.

MQTTAsync_connected

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

Parameters

context	A pointer to the context value originally passed to MQTTAsync_setCallbacks(), which contains any application-specific context.
cause	The reason for the disconnection. Currently, cause is always set to NULL.

MQTTAsync_onSuccess

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 successful completion of an API call. The function is registered with the client library by passing it as an argument in MQTTAsync_responseOptions.

Parameters

context	A pointer to the context value originally passed to MQTTAsync_responseOptions, which contains any application-specific context.
response	Any success data associated with the API completion.

MQTTAsync_onFailure

typedef void MQTTAsync_onFailure(void *context, MQTTAsync_failureData *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.

Parameters

context	A pointer to the context value originally passed to MQTTAsync_responseOptions, which contains any application-specific context.
response	Any failure data associated with the API completion.

MQTTAsync_traceCallback

typedef void MQTTAsync_traceCallback(enum MQTTASYNC_TRACE_LEVELS level, char *message)

This is a callback function prototype which must be implemented if you want to receive trace information.

Parameters

level	the trace level of the message returned
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.

Enumeration Type Documentation

MQTTASYNC_TRACE_LEVELS

enum MQTTASYNC_TRACE_LEVELS

Enumerator
MQTTASYNC_TRACE_MAXIMUM
MQTTASYNC_TRACE_MEDIUM
MQTTASYNC_TRACE_MINIMUM
MQTTASYNC_TRACE_PROTOCOL
MQTTASYNC_TRACE_ERROR
MQTTASYNC_TRACE_SEVERE
MQTTASYNC_TRACE_FATAL

Function Documentation

MQTTAsync_global_init()

void MQTTAsync_global_init

(

MQTTAsync_init_options *

inits

)

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)

MQTTAsync_setCallbacks()

DLLExport int MQTTAsync_setCallbacks	(	MQTTAsync	handle,
		void *	context,
		MQTTAsync_connectionLost *	cl,
		MQTTAsync_messageArrived *	ma,
		MQTTAsync_deliveryComplete *	dc
	)

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.

Note: The MQTT client must be disconnected when this function is called.

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
context	A pointer to any application-specific context. The the context pointer is passed to each of the callback functions to provide access to the context information in the callback.
cl	A pointer to an MQTTAsync_connectionLost() callback function. You can set this to NULL if your application doesn't handle disconnections.
ma	A pointer to an MQTTAsync_messageArrived() callback function. You can set this to NULL if your application doesn't handle receipt of messages.
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.

Returns

MQTTASYNC_SUCCESS if the callbacks were correctly set, MQTTASYNC_FAILURE if an error occurred.

MQTTAsync_setConnected()

DLLExport int MQTTAsync_setConnected	(	MQTTAsync	handle,
		void *	context,
		MQTTAsync_connected *	co
	)

Sets the MQTTAsync_connected() callback function for a client.

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
context	A pointer to any application-specific context. The the context pointer is passed to each of the callback functions to provide access to the context information in the callback.
co	A pointer to an MQTTAsync_connected() callback function. NULL removes the callback setting.

Returns

MQTTASYNC_SUCCESS if the callbacks were correctly set, MQTTASYNC_FAILURE if an error occurred.

MQTTAsync_reconnect()

DLLExport int MQTTAsync_reconnect

(

MQTTAsync

handle

)

Reconnects a client with the previously used connect options. Connect must have previously been called for this to work.

Parameters

handle

A valid client handle from a successful call to MQTTAsync_create().

Returns

MQTTASYNC_SUCCESS if the callbacks were correctly set, MQTTASYNC_FAILURE if an error occurred.

MQTTAsync_create()

DLLExport int MQTTAsync_create	(	MQTTAsync *	handle,
		const char *	serverURI,
		const char *	clientId,
		int	persistence_type,
		void *	persistence_context
	)

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().

Parameters

handle	A pointer to an MQTTAsync handle. The handle is populated with a valid client reference following a successful return from this function.
serverURI	A null-terminated string specifying the server to which the client will connect. It takes the form protocol://host:port. protocol must be tcp or ssl. For host, 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 tcp://localhost:1883.
clientId	The client identifier passed to the server when the client connects to it. It is a null-terminated UTF-8 encoded string.
persistence_type	The type of persistence to be used by the client: 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. 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. 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.
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.

Returns

MQTTASYNC_SUCCESS if the client is successfully created, otherwise an error code is returned.

MQTTAsync_createWithOptions()

DLLExport int MQTTAsync_createWithOptions	(	MQTTAsync *	handle,
		const char *	serverURI,
		const char *	clientId,
		int	persistence_type,
		void *	persistence_context,
		MQTTAsync_createOptions *	options
	)

MQTTAsync_connect()

DLLExport int MQTTAsync_connect	(	MQTTAsync	handle,
		const MQTTAsync_connectOptions *	options
	)

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().

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
options	A pointer to a valid MQTTAsync_connectOptions structure.

Returns

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:

1: Connection refused: Unacceptable protocol version
2: Connection refused: Identifier rejected
3: Connection refused: Server unavailable
4: Connection refused: Bad user name or password
5: Connection refused: Not authorized
6-255: Reserved for future use

MQTTAsync_disconnect()

DLLExport int MQTTAsync_disconnect	(	MQTTAsync	handle,
		const MQTTAsync_disconnectOptions *	options
	)

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()).

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
options	The client delays disconnection for up to this time (in milliseconds) in order to allow in-flight message transfers to complete.

Returns

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

MQTTAsync_isConnected()

DLLExport int MQTTAsync_isConnected

(

MQTTAsync

handle

)

This function allows the client application to test whether or not a client is currently connected to the MQTT server.

Parameters

handle

A valid client handle from a successful call to MQTTAsync_create().

Returns

Boolean true if the client is connected, otherwise false.

MQTTAsync_subscribe()

DLLExport int MQTTAsync_subscribe	(	MQTTAsync	handle,
		const char *	topic,
		int	qos,
		MQTTAsync_responseOptions *	response
	)

This function attempts to subscribe a client to a single topic, which may contain wildcards (see Subscription wildcards). This call also specifies the Quality of service requested for the subscription (see also MQTTAsync_subscribeMany()).

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
topic	The subscription topic, which may include wildcards.
qos	The requested quality of service for the subscription.
response	A pointer to a response options structure. Used to set callback functions.

Returns

MQTTASYNC_SUCCESS if the subscription request is successful. An error code is returned if there was a problem registering the subscription.

MQTTAsync_subscribeMany()

DLLExport int MQTTAsync_subscribeMany	(	MQTTAsync	handle,
		int	count,
		char *const *	topic,
		int *	qos,
		MQTTAsync_responseOptions *	response
	)

This function attempts to subscribe a client to a list of topics, which may contain wildcards (see Subscription wildcards). This call also specifies the Quality of service requested for each topic (see also MQTTAsync_subscribe()).

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
count	The number of topics for which the client is requesting subscriptions.
topic	An array (of length count) of pointers to topics, each of which may include wildcards.
qos	An array (of length count) of Quality of service values. qos[n] is the requested QoS for topic[n].
response	A pointer to a response options structure. Used to set callback functions.

Returns

MQTTASYNC_SUCCESS if the subscription request is successful. An error code is returned if there was a problem registering the subscriptions.

MQTTAsync_unsubscribe()

DLLExport int MQTTAsync_unsubscribe	(	MQTTAsync	handle,
		const char *	topic,
		MQTTAsync_responseOptions *	response
	)

This function attempts to remove an existing subscription made by the specified client.

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
topic	The topic for the subscription to be removed, which may include wildcards (see Subscription wildcards).
response	A pointer to a response options structure. Used to set callback functions.

Returns

MQTTASYNC_SUCCESS if the subscription is removed. An error code is returned if there was a problem removing the subscription.

MQTTAsync_unsubscribeMany()

DLLExport int MQTTAsync_unsubscribeMany	(	MQTTAsync	handle,
		int	count,
		char *const *	topic,
		MQTTAsync_responseOptions *	response
	)

This function attempts to remove existing subscriptions to a list of topics made by the specified client.

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
count	The number subscriptions to be removed.
topic	An array (of length count) of pointers to the topics of the subscriptions to be removed, each of which may include wildcards.
response	A pointer to a response options structure. Used to set callback functions.

Returns

MQTTASYNC_SUCCESS if the subscriptions are removed. An error code is returned if there was a problem removing the subscriptions.

MQTTAsync_send()

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_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()).

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
destinationName	The topic associated with this message.
payloadlen	The length of the payload in bytes.
payload	A pointer to the byte array payload of the message.
qos	The Quality of service of the message.
retained	The retained flag for the message.
response	A pointer to an MQTTAsync_responseOptions structure. Used to set callback functions. This is optional and can be set to NULL.

Returns

MQTTASYNC_SUCCESS if the message is accepted for publication. An error code is returned if there was a problem accepting the message.

MQTTAsync_sendMessage()

DLLExport int MQTTAsync_sendMessage	(	MQTTAsync	handle,
		const char *	destinationName,
		const MQTTAsync_message *	msg,
		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()).

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
destinationName	The topic associated with this message.
msg	A pointer to a valid MQTTAsync_message structure containing the payload and attributes of the message to be published.
response	A pointer to an MQTTAsync_responseOptions structure. Used to set callback functions.

Returns

MQTTASYNC_SUCCESS if the message is accepted for publication. An error code is returned if there was a problem accepting the message.

MQTTAsync_getPendingTokens()

DLLExport int MQTTAsync_getPendingTokens	(	MQTTAsync	handle,
		MQTTAsync_token **	tokens
	)

This function sets a pointer to an array of tokens for messages that are currently in-flight (pending completion).

Important note: 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.

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
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.

Returns

MQTTASYNC_SUCCESS if the function returns successfully. An error code is returned if there was a problem obtaining the list of pending tokens.

MQTTAsync_isComplete()

DLLExport int MQTTAsync_isComplete	(	MQTTAsync	handle,
		MQTTAsync_token	token
	)

MQTTAsync_waitForCompletion()

DLLExport int MQTTAsync_waitForCompletion	(	MQTTAsync	handle,
		MQTTAsync_token	token,
		unsigned long	timeout
	)

Waits for a request corresponding to a token to complete.

Parameters

handle	A valid client handle from a successful call to MQTTAsync_create().
token	An MQTTAsync_token associated with a request.
timeout	the maximum time to wait for completion, in milliseconds

Returns

MQTTASYNC_SUCCESS if the request has been completed in the time allocated, MQTTASYNC_FAILURE if not.

MQTTAsync_freeMessage()

DLLExport void MQTTAsync_freeMessage

(

MQTTAsync_message **

msg

)

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. Important note: 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.

Parameters

msg	The address of a pointer to the MQTTAsync_message structure to be freed.

MQTTAsync_free()

DLLExport void MQTTAsync_free

(

void *

ptr

)

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.

Parameters

ptr	The pointer to the client library storage to be freed.

MQTTAsync_destroy()

DLLExport void MQTTAsync_destroy

(

MQTTAsync *

handle

)

This function frees the memory allocated to an MQTT client (see MQTTAsync_create()). It should be called when the client is no longer required.

Parameters

handle

A pointer to the handle referring to the MQTTAsync structure to be freed.

MQTTAsync_setTraceLevel()

DLLExport void MQTTAsync_setTraceLevel

(

enum MQTTASYNC_TRACE_LEVELS

level

)

This function sets the level of trace information which will be returned in the trace callback.

Parameters

level

the trace level required

MQTTAsync_setTraceCallback()

DLLExport void MQTTAsync_setTraceCallback

(

MQTTAsync_traceCallback *

callback

)

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.

Parameters

callback

a pointer to the function which will handle the trace information

MQTTAsync_getVersionInfo()

DLLExport MQTTAsync_nameValue* MQTTAsync_getVersionInfo

(

void

)

This function returns version information about the library. no trace information will be returned. The default trace level is MQTTASYNC_TRACE_MINIMUM

Returns

an array of strings describing the library. The last entry is a NULL pointer.