MQTT C Client Libraries Internals
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
MQTTAsync.c File Reference

Asynchronous API implementation. More...

#include <stdlib.h>
#include <string.h>
#include <sys/time.h>
#include "MQTTPersistence.h"
#include "MQTTAsync.h"
#include "utf-8.h"
#include "MQTTProtocol.h"
#include "MQTTProtocolOut.h"
#include "Thread.h"
#include "SocketBuffer.h"
#include "StackTrace.h"
#include "Heap.h"
#include "OsWrapper.h"
#include "WebSocket.h"
#include "VersionInfo.h"
Include dependency graph for MQTTAsync.c:

Data Structures

struct  qEntry
 
struct  MQTTAsync_command
 
struct  MQTTAsync_struct
 
struct  MQTTAsync_queuedCommand
 

Macros

#define URI_TCP   "tcp://"
 
#define URI_WS   "ws://"
 
#define URI_WSS   "wss://"
 
#define min(a, b)   (((a) < (b)) ? (a) : (b))
 
#define WINAPI
 
#define MAX_INFO_STRINGS   8
 

Typedefs

typedef struct MQTTAsync_struct MQTTAsyncs
 

Enumerations

enum  MQTTAsync_threadStates { STOPPED, STARTING, RUNNING, STOPPING }
 

Functions

int MQTTAsync_init (void)
 
void MQTTAsync_global_init (MQTTAsync_init_options *inits)
 Global init of mqtt library. More...
 
void MQTTAsync_init_rand (void)
 
static int clientSockCompare (void *a, void *b)
 List callback function for comparing clients by socket. More...
 
static void MQTTAsync_lock_mutex (mutex_type amutex)
 
static void MQTTAsync_unlock_mutex (mutex_type amutex)
 
static int MQTTAsync_checkConn (MQTTAsync_command *command, MQTTAsyncs *client)
 
static void MQTTAsync_terminate (void)
 
static int MQTTAsync_unpersistCommand (MQTTAsync_queuedCommand *qcmd)
 
static int MQTTAsync_persistCommand (MQTTAsync_queuedCommand *qcmd)
 
static MQTTAsync_queuedCommandMQTTAsync_restoreCommand (char *buffer, int buflen, int MQTTVersion)
 
static int MQTTAsync_restoreCommands (MQTTAsyncs *client)
 
static int MQTTAsync_addCommand (MQTTAsync_queuedCommand *command, int command_size)
 
static void MQTTAsync_startConnectRetry (MQTTAsyncs *m)
 
static void MQTTAsync_checkDisconnect (MQTTAsync handle, MQTTAsync_command *command)
 
static void MQTTProtocol_checkPendingWrites (void)
 See if any pending writes have been completed, and cleanup if so. More...
 
static void MQTTAsync_freeServerURIs (MQTTAsyncs *m)
 
static void MQTTAsync_freeCommand1 (MQTTAsync_queuedCommand *command)
 
static void MQTTAsync_freeCommand (MQTTAsync_queuedCommand *command)
 
static void MQTTAsync_writeComplete (int socket, int rc)
 
static int MQTTAsync_processCommand (void)
 
static void MQTTAsync_checkTimeouts (void)
 
static thread_return_type WINAPI MQTTAsync_sendThread (void *n)
 
static void MQTTAsync_emptyMessageQueue (Clients *client)
 
static void MQTTAsync_removeResponsesAndCommands (MQTTAsyncs *m)
 
static int MQTTAsync_completeConnection (MQTTAsyncs *m, Connack *connack)
 
static thread_return_type WINAPI MQTTAsync_receiveThread (void *n)
 
static void MQTTAsync_stop (void)
 
static void MQTTAsync_closeOnly (Clients *client, enum MQTTReasonCodes reasonCode, MQTTProperties *props)
 
static void MQTTAsync_closeSession (Clients *client, enum MQTTReasonCodes reasonCode, MQTTProperties *props)
 
static int clientStructCompare (void *a, void *b)
 List callback function for comparing clients by client structure. More...
 
static int MQTTAsync_cleanSession (Clients *client)
 
static int MQTTAsync_deliverMessage (MQTTAsyncs *m, char *topicName, size_t topicLen, MQTTAsync_message *mm)
 
static int MQTTAsync_disconnect1 (MQTTAsync handle, const MQTTAsync_disconnectOptions *options, int internal)
 
static int MQTTAsync_disconnect_internal (MQTTAsync handle, int timeout)
 
static int cmdMessageIDCompare (void *a, void *b)
 
static int MQTTAsync_assignMsgId (MQTTAsyncs *m)
 Assign a new message id for a client. More...
 
static int MQTTAsync_countBufferedMessages (MQTTAsyncs *m)
 
static void MQTTAsync_retry (void)
 
static int MQTTAsync_connecting (MQTTAsyncs *m)
 
static MQTTPacketMQTTAsync_cycle (int *sock, unsigned long timeout, int *rc)
 
void MQTTAsync_sleep (long milliseconds)
 
int MQTTAsync_randomJitter (int currentIntervalBase, int minInterval, int maxInterval)
 
int MQTTAsync_createWithOptions (MQTTAsync *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context, MQTTAsync_createOptions *options)
 
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). More...
 
int MQTTAsync_reconnect (MQTTAsync handle)
 Reconnects a client with the previously used connect options. More...
 
static int MQTTAsync_Socket_noPendingWrites (int socket)
 Call Socket_noPendingWrites(int socket) with protection by socket_mutex, see https://github.com/eclipse/paho.mqtt.c/issues/385.
 
static void nextOrClose (MQTTAsyncs *m, int rc, char *message)
 
void MQTTAsync_destroy (MQTTAsync *handle)
 This function frees the memory allocated to an MQTT client (see MQTTAsync_create()). More...
 
void MQTTAsync_freeMessage (MQTTAsync_message **message)
 This function frees memory allocated to an MQTT message, including the additional memory allocated to the message payload. More...
 
void MQTTAsync_free (void *memory)
 This function frees memory allocated by the MQTT C client library, especially the topic name. More...
 
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. More...
 
int MQTTAsync_setConnectionLostCallback (MQTTAsync handle, void *context, MQTTAsync_connectionLost *cl)
 This function sets the callback function for a connection lost event for a specific client. More...
 
int MQTTAsync_setMessageArrivedCallback (MQTTAsync handle, void *context, MQTTAsync_messageArrived *ma)
 This function sets the callback function for a message arrived event for a specific client. More...
 
int MQTTAsync_setDeliveryCompleteCallback (MQTTAsync handle, void *context, MQTTAsync_deliveryComplete *dc)
 This function sets the callback function for a delivery complete event for a specific client. More...
 
int MQTTAsync_setDisconnected (MQTTAsync handle, void *context, MQTTAsync_disconnected *disconnected)
 Sets the MQTTAsync_disconnected() callback function for a client. More...
 
int MQTTAsync_setConnected (MQTTAsync handle, void *context, MQTTAsync_connected *connected)
 Sets the MQTTAsync_connected() callback function for a client. More...
 
void Protocol_processPublication (Publish *publish, Clients *client, int allocatePayload)
 
static void setRetryLoopInterval (int keepalive)
 
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. More...
 
void MQTTProtocol_closeSession (Clients *c, int sendwill)
 
int MQTTAsync_disconnect (MQTTAsync handle, const MQTTAsync_disconnectOptions *options)
 This function attempts to disconnect the client from the MQTT server. More...
 
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. More...
 
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 wildcard). More...
 
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 wildcard). More...
 
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. More...
 
int MQTTAsync_unsubscribe (MQTTAsync handle, const char *topic, MQTTAsync_responseOptions *response)
 This function attempts to remove an existing subscription made by the specified client. More...
 
int MQTTAsync_send (MQTTAsync handle, const char *destinationName, int payloadlen, const void *payload, int qos, int retained, MQTTAsync_responseOptions *response)
 This function attempts to publish a message to a given topic (see also MQTTAsync_sendMessage()). More...
 
int MQTTAsync_sendMessage (MQTTAsync handle, const char *destinationName, const MQTTAsync_message *message, MQTTAsync_responseOptions *response)
 This function attempts to publish a message to a given topic (see also MQTTAsync_publish()). More...
 
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). More...
 
int MQTTAsync_isComplete (MQTTAsync handle, MQTTAsync_token dt)
 
int MQTTAsync_waitForCompletion (MQTTAsync handle, MQTTAsync_token dt, unsigned long timeout)
 Waits for a request corresponding to a token to complete. More...
 
void MQTTAsync_setTraceLevel (enum MQTTASYNC_TRACE_LEVELS level)
 This function sets the level of trace information which will be returned in the trace callback. More...
 
void MQTTAsync_setTraceCallback (MQTTAsync_traceCallback *callback)
 This function sets the trace callback if needed. More...
 
MQTTAsync_nameValueMQTTAsync_getVersionInfo (void)
 This function returns version information about the library. More...
 
const char * MQTTAsync_strerror (int code)
 Returns a pointer to a string representation of the error code, or NULL. More...
 

Variables

const char * client_timestamp_eye = "MQTTAsyncV3_Timestamp " BUILD_TIMESTAMP
 
const char * client_version_eye = "MQTTAsyncV3_Version " CLIENT_VERSION
 
static ClientStates ClientState
 
ClientStatesbstate = &ClientState
 
MQTTProtocol state
 
enum MQTTAsync_threadStates sendThread_state = STOPPED
 
enum MQTTAsync_threadStates receiveThread_state = STOPPED
 
static thread_id_type sendThread_id = 0
 
static thread_id_type receiveThread_id = 0
 
static pthread_mutex_t mqttasync_mutex_store = PTHREAD_MUTEX_INITIALIZER
 
static mutex_type mqttasync_mutex = &mqttasync_mutex_store
 
static pthread_mutex_t socket_mutex_store = PTHREAD_MUTEX_INITIALIZER
 
static mutex_type socket_mutex = &socket_mutex_store
 
static pthread_mutex_t mqttcommand_mutex_store = PTHREAD_MUTEX_INITIALIZER
 
static mutex_type mqttcommand_mutex = &mqttcommand_mutex_store
 
static cond_type_struct send_cond_store = { PTHREAD_COND_INITIALIZER, PTHREAD_MUTEX_INITIALIZER }
 
static cond_type send_cond = &send_cond_store
 
static volatile int global_initialized = 0
 
static Listhandles = NULL
 
static int tostop = 0
 
static Listcommands = NULL
 
static int retryLoopInterval = 5
 

Detailed Description

Asynchronous API implementation.

Function Documentation

◆ clientSockCompare()

static int clientSockCompare ( void *  a,
void *  b 
)
static

List callback function for comparing clients by socket.

Parameters
afirst integer value
bsecond integer value
Returns
boolean indicating whether a and b are equal

◆ clientStructCompare()

static int clientStructCompare ( void *  a,
void *  b 
)
static

List callback function for comparing clients by client structure.

Parameters
aAsync structure
bClient structure
Returns
boolean indicating whether a and b are equal

◆ MQTTAsync_assignMsgId()

static int MQTTAsync_assignMsgId ( MQTTAsyncs m)
static

Assign a new message id for a client.

Make sure it isn't already being used and does not exceed the maximum.

Parameters
ma client structure
Returns
the next message id to use, or 0 if none available
Here is the call graph for this function:

◆ MQTTAsync_connect()

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
handleA valid client handle from a successful call to MQTTAsync_create().
optionsA 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
Here is the call graph for this function:

◆ MQTTAsync_create()

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
handleA pointer to an ::MQTTAsync handle. The handle is populated with a valid client reference following a successful return from this function.
serverURIA 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.
clientIdThe client identifier passed to the server when the client connects to it. It is a null-terminated UTF-8 encoded string.
persistence_typeThe 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_contextIf 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_destroy()

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
handleA pointer to the handle referring to the ::MQTTAsync structure to be freed.

◆ MQTTAsync_disconnect()

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

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
ptrThe pointer to the client library storage to be freed.

◆ MQTTAsync_freeMessage()

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
msgThe address of a pointer to the MQTTAsync_message structure to be freed.

◆ MQTTAsync_getPendingTokens()

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

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.

◆ 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_isConnected()

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
handleA valid client handle from a successful call to MQTTAsync_create().
Returns
Boolean true if the client is connected, otherwise false.

◆ MQTTAsync_reconnect()

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
handleA 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_send()

int MQTTAsync_send ( MQTTAsync  handle,
const char *  destinationName,
int  payloadlen,
const void *  payload,
int  qos,
int  retained,
MQTTAsync_responseOptions response 
)

This function attempts to publish a message to a given topic (see also MQTTAsync_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
handleA valid client handle from a successful call to MQTTAsync_create().
destinationNameThe topic associated with this message.
payloadlenThe length of the payload in bytes.
payloadA pointer to the byte array payload of the message.
qosThe qos of the message.
retainedThe retained flag for the message.
responseA 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.
Here is the call graph for this function:

◆ MQTTAsync_sendMessage()

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
handleA valid client handle from a successful call to MQTTAsync_create().
destinationNameThe topic associated with this message.
msgA pointer to a valid MQTTAsync_message structure containing the payload and attributes of the message to be published.
responseA 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.
Here is the call graph for this function:

◆ MQTTAsync_setCallbacks()

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
handleA valid client handle from a successful call to MQTTAsync_create().
contextA 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.
clA pointer to an MQTTAsync_connectionLost() callback function. You can set this to NULL if your application doesn't handle disconnections.
maA pointer to an MQTTAsync_messageArrived() callback function. You can set this to NULL if your application doesn't handle receipt of messages.
dcA 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()

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

Sets the MQTTAsync_connected() callback function for a client.

Parameters
handleA valid client handle from a successful call to MQTTAsync_create().
contextA 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.
coA 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_setConnectionLostCallback()

int MQTTAsync_setConnectionLostCallback ( MQTTAsync  handle,
void *  context,
MQTTAsync_connectionLost *  cl 
)

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

◆ MQTTAsync_setDeliveryCompleteCallback()

int MQTTAsync_setDeliveryCompleteCallback ( MQTTAsync  handle,
void *  context,
MQTTAsync_deliveryComplete *  dc 
)

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

int MQTTAsync_setDisconnected ( MQTTAsync  handle,
void *  context,
MQTTAsync_disconnected *  co 
)

Sets the MQTTAsync_disconnected() callback function for a client.

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

Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be called within this callback.

Parameters
contextA 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.
coA 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_setMessageArrivedCallback()

int MQTTAsync_setMessageArrivedCallback ( MQTTAsync  handle,
void *  context,
MQTTAsync_messageArrived *  ma 
)

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

◆ MQTTAsync_setTraceCallback()

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
callbacka pointer to the function which will handle the trace information

◆ MQTTAsync_setTraceLevel()

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
levelthe trace level required

◆ MQTTAsync_strerror()

const char* MQTTAsync_strerror ( int  code)

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
codethe MQTTASYNC_ return code.
Returns
a static string representation of the error code.

◆ MQTTAsync_subscribe()

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

This call also specifies the qos requested for the subscription (see also MQTTAsync_subscribeMany()).

Parameters
handleA valid client handle from a successful call to MQTTAsync_create().
topicThe subscription topic, which may include wildcards.
qosThe requested quality of service for the subscription.
responseA 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.
Here is the call graph for this function:

◆ MQTTAsync_subscribeMany()

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

This call also specifies the qos requested for each topic (see also MQTTAsync_subscribe()).

Parameters
handleA valid client handle from a successful call to MQTTAsync_create().
countThe number of topics for which the client is requesting subscriptions.
topicAn array (of length count) of pointers to topics, each of which may include wildcards.
qosAn array (of length count) of qos values. qos[n] is the requested QoS for topic[n].
responseA 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.
Here is the call graph for this function:

◆ MQTTAsync_unsubscribe()

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
handleA valid client handle from a successful call to MQTTAsync_create().
topicThe topic for the subscription to be removed, which may include wildcards (see wildcard).
responseA 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.
Here is the call graph for this function:

◆ MQTTAsync_unsubscribeMany()

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
handleA valid client handle from a successful call to MQTTAsync_create().
countThe number subscriptions to be removed.
topicAn array (of length count) of pointers to the topics of the subscriptions to be removed, each of which may include wildcards.
responseA 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.
Here is the call graph for this function:

◆ MQTTAsync_waitForCompletion()

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

Waits for a request corresponding to a token to complete.

Parameters
handleA valid client handle from a successful call to MQTTAsync_create().
tokenAn ::MQTTAsync_token associated with a request.
timeoutthe 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.

◆ MQTTProtocol_checkPendingWrites()

static void MQTTProtocol_checkPendingWrites ( void  )
static

See if any pending writes have been completed, and cleanup if so.

Cleaning up means removing any publication data that was stored because the write did not originally complete.

Here is the call graph for this function:

Variable Documentation

◆ ClientState

ClientStates ClientState
static
Initial value:
=
{
CLIENT_VERSION,
NULL
}