MQTTAsync.h
#include
’MQTTExportDeclarations.h’
#include ’MQTTProperties.h’
#include ’MQTTReasonCodes.h’
#include ’MQTTSubscribeOpts.h’
#include ’MQTTClientPersistence.h’
struct
MQTTAsync_init_options
struct MQTTAsync_message
struct MQTTAsync_connectData
struct MQTTAsync_failureData
struct MQTTAsync_failureData5
struct MQTTAsync_successData
struct MQTTAsync_successData5
struct MQTTAsync_responseOptions
struct MQTTAsync_createOptions
struct MQTTAsync_willOptions
struct MQTTAsync_SSLOptions
struct MQTTAsync_nameValue
struct MQTTAsync_connectOptions
struct MQTTAsync_disconnectOptions
#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 MQTTASYNC_BAD_PROTOCOL −14
#define MQTTASYNC_BAD_MQTT_OPTION −15
#define MQTTASYNC_WRONG_MQTT_VERSION −16
#define MQTTASYNC_0_LEN_WILL_TOPIC −17
#define MQTTASYNC_COMMAND_IGNORED −18
#define MQTTASYNC_MAX_BUFFERED −19
#define MQTTVERSION_DEFAULT 0
#define MQTTVERSION_3_1 3
#define MQTTVERSION_3_1_1 4
#define MQTTVERSION_5 5
#define MQTT_BAD_SUBSCRIBE 0x80
#define MQTTAsync_init_options_initializer {
{’M’, ’Q’, ’T’,
’G’}, 0, 0 }
#define MQTTAsync_message_initializer {
{’M’, ’Q’, ’T’,
’M’}, 1, 0, NULL, 0, 0, 0, 0,
MQTTProperties_initializer }
#define MQTTAsync_connectData_initializer
{{’M’, ’Q’, ’C’,
’D’}, 0, NULL, {0, NULL}}
#define MQTTAsync_failureData5_initializer
{{’M’, ’Q’, ’F’,
’D’}, 0, 0, MQTTREASONCODE_SUCCESS,
MQTTProperties_initializer, 0, NULL, 0}
#define MQTTAsync_successData5_initializer
{{’M’, ’Q’, ’S’,
’D’}, 0, 0, MQTTREASONCODE_SUCCESS,
MQTTProperties_initializer, {.sub={0,0}}}
#define MQTTAsync_responseOptions_initializer {
{’M’, ’Q’, ’T’,
’R’}, 1, NULL, NULL, 0, 0, NULL, NULL,
MQTTProperties_initializer,
MQTTSubscribe_options_initializer, 0, NULL}
#define MQTTAsync_callOptions_initializer
MQTTAsync_responseOptions_initializer
#define MQTTAsync_createOptions_initializer {
{’M’, ’Q’, ’C’,
’O’}, 2, 0, 100, MQTTVERSION_DEFAULT, 0,
0, 1, 1}
#define MQTTAsync_createOptions_initializer5 {
{’M’, ’Q’, ’C’,
’O’}, 2, 0, 100, MQTTVERSION_5, 0, 0, 1,
1}
#define MQTTAsync_willOptions_initializer {
{’M’, ’Q’, ’T’,
’W’}, 1, NULL, NULL, 0, 0, { 0, NULL } }
#define MQTT_SSL_VERSION_DEFAULT 0
#define MQTT_SSL_VERSION_TLS_1_0 1
#define MQTT_SSL_VERSION_TLS_1_1 2
#define MQTT_SSL_VERSION_TLS_1_2 3
#define MQTTAsync_SSLOptions_initializer {
{’M’, ’Q’, ’T’,
’S’}, 5, NULL, NULL, NULL, NULL, NULL, 1,
MQTT_SSL_VERSION_DEFAULT, 0, NULL, NULL, NULL, NULL,
NULL, 0, NULL, 0 }
#define MQTTAsync_connectOptions_initializer
#define MQTTAsync_connectOptions_initializer5
#define MQTTAsync_connectOptions_initializer_ws
#define MQTTAsync_connectOptions_initializer5_ws
#define MQTTAsync_disconnectOptions_initializer
#define MQTTAsync_disconnectOptions_initializer5
#define MQTTASYNC_TRUE 1
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_disconnected(void *context,
MQTTProperties *properties, enum
MQTTReasonCodes reasonCode)
typedef int MQTTAsync_updateConnectOptions(void
*context, MQTTAsync_connectData *data)
typedef void MQTTAsync_onSuccess(void *context,
MQTTAsync_successData *response)
typedef void MQTTAsync_onSuccess5(void *context,
MQTTAsync_successData5 *response)
typedef void MQTTAsync_onFailure(void *context,
MQTTAsync_failureData *response)
typedef void MQTTAsync_onFailure5(void *context,
MQTTAsync_failureData5 *response)
typedef struct MQTTAsync_responseOptions
MQTTAsync_responseOptions
typedef struct MQTTAsync_responseOptions
MQTTAsync_callOptions
typedef void MQTTAsync_traceCallback(enum
MQTTASYNC_TRACE_LEVELS level, char *message)
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 }
void
MQTTAsync_global_init (MQTTAsync_init_options
*inits)
int MQTTAsync_setDisconnected (MQTTAsync
handle, void *context, MQTTAsync_disconnected *co)
int MQTTAsync_setUpdateConnectOptions
(MQTTAsync handle, void *context,
MQTTAsync_updateConnectOptions *co)
int MQTTAsync_setBeforePersistenceWrite
(MQTTAsync handle, void *context,
MQTTPersistence_beforeWrite *co)
int MQTTAsync_setAfterPersistenceRead
(MQTTAsync handle, void *context,
MQTTPersistence_afterRead *co)
int MQTTAsync_setCallbacks (MQTTAsync handle,
void *context, MQTTAsync_connectionLost *cl,
MQTTAsync_messageArrived *ma,
MQTTAsync_deliveryComplete *dc)
int MQTTAsync_setConnectionLostCallback
(MQTTAsync handle, void *context,
MQTTAsync_connectionLost *cl)
int MQTTAsync_setMessageArrivedCallback
(MQTTAsync handle, void *context,
MQTTAsync_messageArrived *ma)
int MQTTAsync_setDeliveryCompleteCallback
(MQTTAsync handle, void *context,
MQTTAsync_deliveryComplete *dc)
int MQTTAsync_setConnected (MQTTAsync handle,
void *context, MQTTAsync_connected *co)
int MQTTAsync_reconnect (MQTTAsync handle)
int MQTTAsync_create (MQTTAsync *handle, const
char *serverURI, const char *clientId, int persistence_type,
void *persistence_context)
int MQTTAsync_createWithOptions (MQTTAsync
*handle, const char *serverURI, const char *clientId, int
persistence_type, void *persistence_context,
MQTTAsync_createOptions *options)
int MQTTAsync_connect (MQTTAsync handle, const
MQTTAsync_connectOptions *options)
int MQTTAsync_disconnect (MQTTAsync handle,
const MQTTAsync_disconnectOptions *options)
int MQTTAsync_isConnected (MQTTAsync handle)
int MQTTAsync_subscribe (MQTTAsync handle,
const char *topic, int qos, MQTTAsync_responseOptions
*response)
int MQTTAsync_subscribeMany (MQTTAsync handle,
int count, char *const *topic, const int *qos,
MQTTAsync_responseOptions *response)
int MQTTAsync_unsubscribe (MQTTAsync handle,
const char *topic, MQTTAsync_responseOptions
*response)
int MQTTAsync_unsubscribeMany (MQTTAsync
handle, int count, char *const *topic,
MQTTAsync_responseOptions *response)
int MQTTAsync_send (MQTTAsync handle, const
char *destinationName, int payloadlen, const void *payload,
int qos, int retained, MQTTAsync_responseOptions
*response)
int MQTTAsync_sendMessage (MQTTAsync handle,
const char *destinationName, const MQTTAsync_message
*msg, MQTTAsync_responseOptions *response)
int MQTTAsync_getPendingTokens (MQTTAsync
handle, MQTTAsync_token **tokens)
int MQTTAsync_isComplete (MQTTAsync handle,
MQTTAsync_token token)
int MQTTAsync_waitForCompletion (MQTTAsync
handle, MQTTAsync_token token, unsigned long timeout)
void MQTTAsync_freeMessage (MQTTAsync_message
**msg)
void MQTTAsync_free (void *ptr)
void * MQTTAsync_malloc (size_t size)
void MQTTAsync_destroy (MQTTAsync *handle)
void MQTTAsync_setTraceLevel (enum
MQTTASYNC_TRACE_LEVELS level)
void MQTTAsync_setTraceCallback
(MQTTAsync_traceCallback *callback)
MQTTAsync_nameValue * MQTTAsync_getVersionInfo
(void)
const char * MQTTAsync_strerror (int code)
Return code: No error. Indicates successful completion of an MQTT client operation.
Return code: A generic error code indicating the failure of an MQTT client operation.
Return code: The client is disconnected.
Return code: The maximum number of messages allowed to be simultaneously in-flight has been reached.
Return code: An invalid UTF-8 string has been detected.
Return code: A NULL parameter has been supplied when this is invalid.
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.
Return code: A structure parameter does not have the correct eyecatcher and version number.
Return code: A qos parameter is not 0, 1 or 2
Return code: All 65535 MQTT msgids are being used
Return code: the request is being discarded when not complete
Return code: no more messages can be buffered
Return code: Attempting SSL connection using non-SSL version of library
Return code: protocol prefix in serverURI should be:
|
• |
tcp:// or mqtt:// - Insecure TCP |
|||
|
• |
ssl:// or mqtts:// - Encrypted SSL/TLS |
|||
|
• |
ws:// - Insecure websockets |
|||
|
• |
wss:// - Secure web sockets |
The TLS enabled prefixes (ssl, mqtts, wss) are only valid if the TLS version of the library is linked with.
Return code: don’t use options for another version of MQTT
Return code: call not applicable to the client’s version of MQTT
Return code: 0 length will topic
Default MQTT version to connect with. Use 3.1.1 then fall back to 3.1
MQTT version to connect with: 3.1
MQTT version to connect with: 3.1.1
MQTT version to connect with: 5
Bad return code from subscribe, as defined in the 3.1.1 specification
Value:
{ {’M’, ’Q’, ’T’,
’C’}, 8, 60, 1, 65535, NULL, NULL, NULL, 30,
0,NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_DEFAULT, 0,
1, 60, {0, NULL}, 0, NULL, NULL, NULL, NULL, NULL, NULL,
NULL}
Initializer for connect options for MQTT 3.1.1 non-WebSocket
connections
Value:
{ {’M’, ’Q’, ’T’,
’C’}, 8, 60, 0, 65535, NULL, NULL, NULL, 30,
0,NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_5, 0, 1, 60,
{0, NULL}, 1, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
Initializer for connect options for MQTT 5.0 non-WebSocket
connections
Value:
{ {’M’, ’Q’, ’T’,
’C’}, 8, 45, 1, 65535, NULL, NULL, NULL, 30,
0,NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_DEFAULT, 0,
1, 60, {0, NULL}, 0, NULL, NULL, NULL, NULL, NULL, NULL,
NULL}
Initializer for connect options for MQTT 3.1.1 WebSockets
connections. The keepalive interval is set to 45 seconds to
avoid webserver 60 second inactivity timeouts.
Value:
{ {’M’, ’Q’, ’T’,
’C’}, 8, 45, 0, 65535, NULL, NULL, NULL, 30,
0,NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_5, 0, 1, 60,
{0, NULL}, 1, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
Initializer for connect options for MQTT 5.0 WebSockets
connections. The keepalive interval is set to 45 seconds to
avoid webserver 60 second inactivity timeouts.
Value:
{ {’M’, ’Q’, ’T’,
’D’}, 0, 0, NULL, NULL, NULL,
MQTTProperties_initializer, MQTTREASONCODE_SUCCESS, NULL,
NULL }
Value:
{ {’M’, ’Q’, ’T’,
’D’}, 1, 0, NULL, NULL, NULL,
MQTTProperties_initializer, MQTTREASONCODE_SUCCESS, NULL,
NULL }
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.
A handle representing an MQTT client. A valid client handle is available following a successful call to MQTTAsync_create().
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()).
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.
Note: Neither MQTTAsync_create() nor
MQTTAsync_destroy() should be called within this
callback.
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 0 or
1 indicating whether or not the message has been safely
received by the client application.
Returning 1 indicates that the message has been successfully
handled. To free the message storage,
MQTTAsync_freeMessage must be called. To free the
topic name storage, MQTTAsync_free must be called.
Returning 0 indicates that there was a problem. In this
case, the client library will reinvoke
MQTTAsync_messageArrived() to attempt to deliver the
message to the application again. Do not free the message
and topic storage when returning 0, otherwise the redelivery
will fail.
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.
Note: Neither MQTTAsync_create() nor
MQTTAsync_destroy() should be called within this
callback.
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.
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.
Note: Neither MQTTAsync_create() nor
MQTTAsync_destroy() should be called within this
callback.
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.
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.
Note: Neither MQTTAsync_create() nor
MQTTAsync_destroy() should be called within this
callback.
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.
This is a callback function,
which will be called when the client library receives a
disconnect packet from the server. This applies to MQTT V5
and above only.
Note: Neither MQTTAsync_create() nor
MQTTAsync_destroy() should be called within this
callback.
Parameters
context A pointer to the
context value originally passed to
MQTTAsync_setCallbacks(), which contains any
application-specific context.
properties the properties in the disconnect packet.
properties the reason code from the disconnect packet
Currently, cause is always set to NULL.
This is a callback function
which will allow the client application to update the
connection data.
Parameters
data The connection data which can be modified by the application.
Returns
Return a non-zero value to update the connect data, zero to keep the same data.
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.
Note: Neither MQTTAsync_create() nor
MQTTAsync_destroy() should be called within this
callback.
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.
This is a callback function, the
MQTT V5 version of MQTTAsync_onSuccess. The client
application must provide an implementation of this function
to enable asynchronous notification of the successful
completion of an API call. The function is registered with
the client library by passing it as an argument in
MQTTAsync_responseOptions.
Note: Neither MQTTAsync_create() nor
MQTTAsync_destroy() should be called within this
callback.
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.
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.
Note: Neither MQTTAsync_create() nor
MQTTAsync_destroy() should be called within this
callback.
Parameters
context A pointer to the
context value originally passed to
MQTTAsync_responseOptions, which contains any
application-specific context.
response Failure data associated with the API
completion.
This is a callback function, the
MQTT V5 version of MQTTAsync_onFailure. The
application must provide an implementation of this function
to enable asynchronous notification of the unsuccessful
completion of an API call. The function is registered with
the client library by passing it as an argument in
MQTTAsync_responseOptions.
Note: Neither MQTTAsync_create() nor
MQTTAsync_destroy() should be called within this
callback.
Parameters
context A pointer to the
context value originally passed to
MQTTAsync_responseOptions, which contains any
application-specific context.
response Failure data associated with the API
completion.
Structure to define call options. For MQTT 5.0 there is input data as well as that describing the response method. So there is now also a synonym MQTTAsync_callOptions to better reflect the use. This responseOptions name is kept for backward compatibility.
A synonym for responseOptions to better reflect its usage since MQTT 5.0
This is a callback function
prototype which must be implemented if you want to receive
trace information. Do not invoke any other Paho API calls in
this callback function - unpredictable behavior may result.
Parameters
level the trace level of
the message returned
message the trace message. This is a pointer to a static
buffer which will be overwritten on each call. You must copy
the data if you want to keep it for later.
Enumerator
MQTTASYNC_TRACE_MAXIMUM
MQTTASYNC_TRACE_MEDIUM
MQTTASYNC_TRACE_MINIMUM
MQTTASYNC_TRACE_PROTOCOL
MQTTASYNC_TRACE_ERROR
MQTTASYNC_TRACE_SEVERE
MQTTASYNC_TRACE_FATAL
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)
Sets the
MQTTAsync_disconnected() callback function for a
client.
Parameters
handle A valid client handle from a successful call to MQTTAsync_create().
Note: Neither
MQTTAsync_create() nor MQTTAsync_destroy()
should be called within this callback.
Parameters
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.
Sets the
MQTTAsync_updateConnectOptions() 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_updateConnectOptions() callback function.
NULL removes the callback setting.
Sets the
MQTTPersistence_beforeWrite() 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 the callback
function to provide access to the context information in the
callback.
co A pointer to an MQTTPersistence_beforeWrite()
callback function. NULL removes the callback setting.
Sets the
MQTTPersistence_afterRead() 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 the callback
function to provide access to the context information in the
callback.
co A pointer to an MQTTPersistence_beforeWrite()
callback function. NULL removes the callback setting.
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. If this callback is not set, an error
will be returned. You must set this callback because
otherwise there would be no way to deliver any incoming
messages.
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.
This function sets the callback
function for a connection lost event for a specific client.
Any necessary message acknowledgements and status
communications are handled in the background without any
intervention from the client application.
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 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.
Returns
MQTTASYNC_SUCCESS if the callbacks were correctly set, MQTTASYNC_FAILURE if an error occurred.
This function sets the callback
function for a message arrived event for a specific client.
Any necessary message acknowledgements and status
communications are handled in the background without any
intervention from the client application. If you do not set
a messageArrived callback function, you will not be notified
of the receipt of any messages as a result of a
subscription.
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 the callback
functions to provide access to the context information in
the callback.
ma A pointer to an MQTTAsync_messageArrived()
callback function. You can set this to NULL if your
application doesn’t handle receipt of messages.
Returns
MQTTASYNC_SUCCESS if the callbacks were correctly set, MQTTASYNC_FAILURE if an error occurred.
This function sets the callback
function for a delivery complete event for a specific
client. Any necessary message acknowledgements and status
communications are handled in the background without any
intervention from the client application.
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 the callback
functions to provide access to the context information in
the callback.
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.
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.
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.
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 where protocol must be:
tcp:// or mqtt:// - Insecure TCP
ssl:// or mqtts:// - Encrypted SSL/TLS
ws:// - Insecure websockets
wss:// - Secure web sockets
The TLS enabled prefixes (ssl, mqtts, wss) are only valid if
a TLS version of the library is linked with. 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.
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
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
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.
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.
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.
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.
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.
This function attempts to
publish a message to a given topic (see also
MQTTAsync_sendMessage()). An MQTTAsync_token
is issued when this function returns successfully if the QoS
is greater than 0. If the client application needs to test
for successful delivery of messages, a callback should be
set (see MQTTAsync_onSuccess() and
MQTTAsync_deliveryComplete()).
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.
This function attempts to
publish a message to a given topic (see also
MQTTAsync_publish()). An MQTTAsync_token is issued
when this function returns successfully if the QoS is
greater than 0. If the client application needs to test for
successful delivery of messages, a callback should be set
(see MQTTAsync_onSuccess() and
MQTTAsync_deliveryComplete()).
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.
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.
Waits for a request
corresponding to a token to complete. This only works for
messages with QoS greater than 0. A QoS 0 message has no
MQTT token. This function will always return
MQTTASYNC_SUCCESS for a QoS 0 message.
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 or MQTTASYNC_DISCONNECTED if not.
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.
This function frees memory
allocated by the MQTT C client library, especially the topic
name. This is needed on Windows when the client library and
application program have been compiled with different
versions of the C compiler. It is thus good policy to always
use this function when freeing any MQTT C client- allocated
memory.
Parameters
ptr The pointer to the client library storage to be freed.
This function is used to
allocate memory to be used or freed by the MQTT C client
library, especially the data in the
MQTTPersistence_afterRead and
MQTTPersistence_beforeWrite callbacks. This is needed
on Windows when the client library and application program
have been compiled with different versions of the C
compiler.
Parameters
size The size of the memory to be allocated.
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.
This function sets the level of
trace information which will be returned in the trace
callback.
Parameters
level the trace level required
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
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.
Returns a pointer to a string
representation of the error code, or NULL. Do not free after
use. Returns NULL if the error code is unknown.
Parameters
code the MQTTASYNC_ return code.
Returns
a static string representation of the error code.
Generated automatically by Doxygen for Paho Asynchronous MQTT C Client Library from the source code.