MQTTAsync.h(3)

📦
version 1.3.16 · 7 versions
, in fedora 44

🌸 NAME 🌸

MQTTAsync.h — it's the header for the async MQTT client library, and it lives in the Library Functions Manual (section 3, bestie, we're in the grown-up section 💅).

✨ SYNOPSIS ✨

First things first, she pulls in her little friend group of headers:

#include 'MQTTExportDeclarations.h'
#include 'MQTTProperties.h'
#include 'MQTTReasonCodes.h'
#include 'MQTTSubscribeOpts.h'
#include 'MQTTClientPersistence.h'

🎀 Data Structures 🎀

The structs. All of them. No skips, we don't do that here 🫶

  • 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

🍓 Macros 🍓

Okay so here's the whole macro mood board. Buckle up, there's a lot and I love that for us ✨

The status / error codes — one good one, and a whole lineup of negative ones:

  • #define MQTTASYNC_SUCCESS 0 — the one you actually want to see, the main character 💖
  • #define MQTTASYNC_FAILURE -1 — the generic "it did not go well" 😭
  • #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

Protocol versions & friends — pick your era, bestie:

  • #define MQTTVERSION_DEFAULT 0
  • #define MQTTVERSION_3_1 3
  • #define MQTTVERSION_3_1_1 4
  • #define MQTTVERSION_5 5
  • #define MQTT_BAD_SUBSCRIBE 0x80

The initializers — these are the "make a struct that's already cute and valid" cheat codes, no cap 🧚:

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

SSL/TLS version picks — secure the bag 🔒:

  • #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

And the SSL options initializer, because even your security config deserves a glow-up:

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

The connect / disconnect initializers — these ones are listed with no value shown on the page, so I'm giving you exactly what the page gives you, nothing invented 🙈:

  • #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

And finally, the truthiest truth there ever was:

  • #define MQTTASYNC_TRUE 1 — it's giving "yes, obviously" ✅

🌈 Typedefs 🌈

Every alias, every callback signature, untouched, periodt:

  • 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)

👑 Enumerations 👑

One enum, seven levels of how loud the library is about what it's going through:

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 💖

The whole roster. Yes, all of them. Every signature, character for character, because we don't do "and so on" in this house 🫶

  • 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)

Okay so that's the whole table of contents, bestie 💅 and honestly that's just the appetizer — the actual tea about what each of these does is coming next, so don't go anywhere 🌸🦋

✨ MACRO DEFINITION DOCUMENTATION ✨

Okay bestie, this part is the macro zone. Return codes, MQTT versions, and initializer macros — all of it, no crumbs left behind. 💅

#define MQTTASYNC_SUCCESS 0

Return code: no error. It means an MQTT client operation completed successfully. ✨

#define MQTTASYNC_FAILURE -1

Return code: a generic error code that says an MQTT client operation failed. 😭

#define MQTTASYNC_PERSISTENCE_ERROR -2

The page gives this one no extra description — it's just the define with its value. 💀

#define MQTTASYNC_DISCONNECTED -3

Return code: the client is disconnected. Periodt. 💅

#define MQTTASYNC_MAX_MESSAGES_INFLIGHT -4

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

#define MQTTASYNC_BAD_UTF8_STRING -5

Return code: an invalid UTF-8 string has been detected. Yikes. 😭

#define MQTTASYNC_NULL_PARAMETER -6

Return code: a NULL parameter has been supplied when that's invalid. 🚫

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

#define MQTTASYNC_BAD_STRUCTURE -8

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

#define MQTTASYNC_BAD_QOS -9

Return code: a qos parameter is not 0, 1 or 2. 🚨

#define MQTTASYNC_NO_MORE_MSGIDS -10

Return code: all 65535 MQTT msgids are being used. 😵

#define MQTTASYNC_OPERATION_INCOMPLETE -11

Return code: the request is being discarded when not complete. 🗑️

#define MQTTASYNC_MAX_BUFFERED_MESSAGES -12

Return code: no more messages can be buffered. 📦

#define MQTTASYNC_SSL_NOT_SUPPORTED -13

Return code: attempting SSL connection using non-SSL version of library. 🔓

#define MQTTASYNC_BAD_PROTOCOL -14

Return code: protocol prefix in serverURI should be:

  • tcp:// or mqtt:// — insecure TCP
  • ssl:// or tls:// or mqtts:// — encrypted SSL/TLS
  • ws:// — insecure websockets
  • wss:// — secure web sockets

The TLS enabled prefixes (ssl, tls, mqtts, wss) are only valid if the TLS version of the library is linked with. 🔐

#define MQTTASYNC_BAD_MQTT_OPTION -15

Return code: don't use options for another version of MQTT. 🚫

#define MQTTASYNC_WRONG_MQTT_VERSION -16

Return code: call not applicable to the client's version of MQTT. 🧐

#define MQTTASYNC_0_LEN_WILL_TOPIC -17

Return code: 0 length will topic. 🕳️

#define MQTTASYNC_COMMAND_IGNORED -18

No description on the page for this one — it just vibes at -18. 💀

#define MQTTASYNC_MAX_BUFFERED -19

Also no description on the page — just -19. 🫥

#define MQTTVERSION_DEFAULT 0

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

#define MQTTVERSION_3_1 3

MQTT version to connect with: 3.1. 🕰️

#define MQTTVERSION_3_1_1 4

MQTT version to connect with: 3.1.1. ✨

#define MQTTVERSION_5 5

MQTT version to connect with: 5. 🚀

#define MQTT_BAD_SUBSCRIBE 0x80

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

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

No extra description on the page — just the exact initializer. 🫧

#define MQTTAsync_message_initializer

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

No extra description on the page. 🫧

#define MQTTAsync_connectData_initializer

#define MQTTAsync_connectData_initializer   {{'M', 'Q', 'C', 'D'}, 0, NULL,
    {0, NULL}}

No extra description on the page. 🫧

#define MQTTAsync_failureData5_initializer

#define MQTTAsync_failureData5_initializer   {{'M', 'Q', 'F', 'D'}, 0, 0,
    MQTTREASONCODE_SUCCESS, MQTTProperties_initializer, 0, NULL, 0}

No extra description on the page. 🫧

#define MQTTAsync_successData5_initializer

#define MQTTAsync_successData5_initializer   {{'M', 'Q', 'S', 'D'}, 0, 0,
    MQTTREASONCODE_SUCCESS, MQTTProperties_initializer, {.sub={0,0}}}

No extra description on the page. 🫧

#define MQTTAsync_responseOptions_initializer

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

No extra description on the page. 🫧

#define MQTTAsync_callOptions_initializer

#define MQTTAsync_callOptions_initializer
       MQTTAsync_responseOptions_initializer

No extra description on the page. 🫧

#define MQTTAsync_createOptions_initializer

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

No extra description on the page. 🫧

#define MQTTAsync_createOptions_initializer5

#define MQTTAsync_createOptions_initializer5   { {'M', 'Q', 'C', 'O'}, 2, 0,
    100, MQTTVERSION_5, 0, 0, 1, 1}

No extra description on the page. 🫧

#define MQTTAsync_willOptions_initializer

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

No extra description on the page. 🫧

#define MQTT_SSL_VERSION_DEFAULT 0

No extra description on the page. 🫧

#define MQTT_SSL_VERSION_TLS_1_0 1

No extra description on the page. 🫧

#define MQTT_SSL_VERSION_TLS_1_1 2

No extra description on the page. 🫧

#define MQTT_SSL_VERSION_TLS_1_2 3

No extra description on the page. 🫧

#define MQTTAsync_SSLOptions_initializer

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

No extra description on the page. 🫧

#define MQTTAsync_connectOptions_initializer

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

#define MQTTAsync_connectOptions_initializer5

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

#define MQTTAsync_connectOptions_initializer_ws

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

#define MQTTAsync_connectOptions_initializer5_ws

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

#define MQTTAsync_disconnectOptions_initializer

Value:

{ {'M', 'Q', 'T', 'D'}, 0, 0, NULL, NULL, NULL,\
MQTTProperties_initializer, MQTTREASONCODE_SUCCESS, NULL, NULL }

No extra description on the page. 🫧

#define MQTTAsync_disconnectOptions_initializer5

Value:

{ {'M', 'Q', 'T', 'D'}, 1, 0, NULL, NULL, NULL,\
MQTTProperties_initializer, MQTTREASONCODE_SUCCESS, NULL, NULL }

No extra description on the page. 🫧

#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 ✨

okay bestie, this is where the library hands you its lil building blocks 🧱 every type you're gonna be touching lives here, and ngl you're gonna be touching a LOT of them. let's get into it 💅

MQTTAsync

typedef void* MQTTAsync

A handle that represents an MQTT client, periodt 👑. You only get a valid client handle once a call to MQTTAsync_create() has actually succeeded — before that, no handle for you, sorry babe. 🌸

MQTTAsync_token

typedef int MQTTAsync_token

A value that represents an MQTT message 📨. When you publish a message, the library hands you back one of these lil tokens, and then you can use it to double-check that the message actually made it to its destination (iykyk — see MQTTAsync_publish(), MQTTAsync_publishMessage(), MQTTAsync_deliveryComplete(), and MQTTAsync_getPendingTokens() for the whole squad). ✨

MQTTAsync_messageArrived

typedef int MQTTAsync_messageArrived(void *context, char *topicName, int
    topicLen, MQTTAsync_message *message)

This one's a callback function, bestie 🫶. Your client app must implement it if you want asynchronous receipt of messages, no way around it. You register it with the client library by passing it as an argument to MQTTAsync_setCallbacks(), and then the library calls it whenever a new message matching a client subscription shows up from the server 📬. Heads up: this function runs on a separate thread from the one your client application is running on, so act accordingly. 🦋

Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be called within this callback. Not the vibe, don't do it. 💀

Parameters

  • context — A pointer to the context value you originally passed to MQTTAsync_setCallbacks(), which holds any application-specific context you want.
  • topicName — The topic associated with the received message.
  • topicLen — The length of the topic if there are one or more NULL characters embedded in topicName, otherwise topicLen is 0. If topicLen is 0, then the value returned by strlen(topicName) can be trusted. If topicLen is greater than 0, you can retrieve the full topic name 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 means 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 means 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.

MQTTAsync_deliveryComplete

typedef void MQTTAsync_deliveryComplete(void *context, MQTTAsync_token
    token)

Another callback function, bestie 🎀. Your client app must implement this one to enable asynchronous notification of delivery of messages to the server. You register it by passing it as an argument to MQTTAsync_setCallbacks(). The library calls it after the client application has published a message to the server, and it signals that all the necessary handshaking and acknowledgements for the requested quality of service (see MQTTAsync_message.qos) have been completed ✅. And yep — this function is executed on a separate thread from the one your client application is running on.

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

Parameters

  • context — A pointer to the context value you 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)

Callback function, and this one is giving "uh oh" energy 😭. Your client app must implement it to enable asynchronous notification of the loss of connection to the server. You register it by passing it as an argument to MQTTAsync_setCallbacks(). The library calls it if the client loses its connection to the server, and then your client application must take appropriate action — like trying to reconnect or reporting the problem 📢. Runs on a separate thread from your client app, obvi.

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

Parameters

  • context — A pointer to the context value you 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)

A callback function that gets called when the client library successfully connects 🎉✨. Lowkey this one is superfluous when the connection is made in response to a MQTTAsync_connect call, because you can just use the onSuccess callback instead. It's really intended for when automatic reconnect is enabled, so that when a reconnection attempt succeeds in the background, your application gets 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 you 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_disconnected

typedef void MQTTAsync_disconnected(void *context, MQTTProperties
    *properties, enum MQTTReasonCodes reasonCode)

A callback function that gets called when the client library receives a disconnect packet from the server 📪. Important: this applies to MQTT V5 and above only, so if you're on an older version, this is not your moment bestie.

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

Parameters

  • context — A pointer to the context value you originally passed to MQTTAsync_setCallbacks(), which contains any application-specific context.
  • properties — the properties in the disconnect packet.
  • reasonCode — the reason code from the disconnect packet.

MQTTAsync_updateConnectOptions

typedef int MQTTAsync_updateConnectOptions(void *context,
    MQTTAsync_connectData *data)

A callback function that lets your client application 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, or zero to keep the same data. Simple as that. 💅

MQTTAsync_onSuccess

typedef void MQTTAsync_onSuccess(void *context, MQTTAsync_successData
    *response)

A callback function, bestie 🫶. Your client application must implement it to enable asynchronous notification of the successful completion of an API call. You register it with the client library by passing it as an argument in MQTTAsync_responseOptions. Iconic behaviour only. ✨

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

Parameters

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

MQTTAsync_onSuccess5

typedef void MQTTAsync_onSuccess5(void *context, MQTTAsync_successData5
    *response)

A callback function — this is the MQTT V5 version of MQTTAsync_onSuccess 🌈. Your client application must implement it to enable asynchronous notification of the successful completion of an API call. You register it 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 you 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)

A callback function 😭. Your client application must implement it to enable asynchronous notification of the unsuccessful completion of an API call. You register it 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 you originally passed to MQTTAsync_responseOptions, which contains any application-specific context.
  • response — Failure data associated with the API completion.

MQTTAsync_onFailure5

typedef void MQTTAsync_onFailure5(void *context, MQTTAsync_failureData5
    *response)

A callback function — the MQTT V5 version of MQTTAsync_onFailure 🌈. Your application must implement it to enable asynchronous notification of the unsuccessful completion of an API call. You register it 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 you originally passed to MQTTAsync_responseOptions, which contains any application-specific context.
  • response — Failure data associated with the API completion.

MQTTAsync_responseOptions

typedef struct MQTTAsync_responseOptions MQTTAsync_responseOptions

A structure that defines call options 📋. Here's the tea: for MQTT 5.0 there's input data as well as the stuff describing the response method, so there's now also a synonym, MQTTAsync_callOptions, to better reflect how it's actually used. The responseOptions name is kept around for backward compatibility, so nobody's old code breaks. 🫶

MQTTAsync_callOptions

typedef struct MQTTAsync_responseOptions MQTTAsync_callOptions

A synonym for responseOptions, to better reflect its usage since MQTT 5.0 💅✨.

MQTTAsync_traceCallback

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

A callback function prototype that must be implemented if you want to receive trace information 🔍. Real talk though: do not invoke any other Paho API calls inside this callback function — unpredictable behavior may result. Not the vibe. 💀

Parameters

  • level — the trace level of the message returned.
  • message — the trace message. Heads up bestie, this is a pointer to a static buffer which will be overwritten on each call, so you must copy the data if you want to keep it for later. 📝

✨ ENUMERATION TYPE DOCUMENTATION ✨

💫 enum MQTTASYNC_TRACE_LEVELS

okay so this one is literally just the vibe-check dial for how much the library is gonna yap at you 🗣️✨ Here's every single level, no skips:

  • MQTTASYNC_TRACE_MAXIMUM
  • MQTTASYNC_TRACE_MEDIUM
  • MQTTASYNC_TRACE_MINIMUM
  • MQTTASYNC_TRACE_PROTOCOL
  • MQTTASYNC_TRACE_ERROR
  • MQTTASYNC_TRACE_SEVERE
  • MQTTASYNC_TRACE_FATAL

🎀 FUNCTION DOCUMENTATION 🎀

💖 void MQTTAsync_global_init (MQTTAsync_init_options * inits) [extern]

bestie this is the global init of mqtt library. Call it once on program start to set global behaviour, okay? Once. Not twice. Not in a loop. One time. 🫶

And here's the tea on the option it takes:

  • handle_openssl_init — if the mqtt library should handle openssl init (1) or rely on the caller to init it before using mqtt (0)

💖 int MQTTAsync_setDisconnected (MQTTAsync handle, void * context, MQTTAsync_disconnected * co) [extern]

Sets the MQTTAsync_disconnected() callback function for a client. iconic behaviour tbh 💅

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. like. don't. 🙈

Parameters (yes bestie, there's a second parameters block, that's just how this one is written)

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

💖 int MQTTAsync_setUpdateConnectOptions (MQTTAsync handle, void * context, MQTTAsync_updateConnectOptions * co) [extern]

Sets the MQTTAsync_updateConnectOptions() callback function for a client. yes queen, update those connect options ✨

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.

💖 int MQTTAsync_setBeforePersistenceWrite (MQTTAsync handle, void * context, MQTTPersistence_beforeWrite * co) [extern]

Sets the MQTTPersistence_beforeWrite() callback function for a client. pre-gaming the persistence write, lowkey genius 🍓

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.

💖 int MQTTAsync_setAfterPersistenceRead (MQTTAsync handle, void * context, MQTTPersistence_afterRead * co) [extern]

Sets the MQTTPersistence_afterRead() callback function for a client. post-read glow-up 🌸

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.

👑 int MQTTAsync_setCallbacks (MQTTAsync handle, void * context, MQTTAsync_connectionLost * cl, MQTTAsync_messageArrived * ma, MQTTAsync_deliveryComplete * dc) [extern]

This function sets the global callback functions for a specific client. So like, the whole squad of callbacks in one go 💅

If your client application doesn't use a particular callback, set the relevant parameter to NULL — except for message arrived, which must be given. that one's mandatory bestie, no exceptions.

Any necessary message acknowledgements and status communications are handled in the background without any intervention from the client application. the library just. handles it. main character energy 🔥

⚠️ Note: The MQTT client must be disconnected when this function is called. do not test me on this.

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.

💖 int MQTTAsync_setConnectionLostCallback (MQTTAsync handle, void * context, MQTTAsync_connectionLost * cl) [extern]

This function sets the callback function for a connection lost event for a specific client. sad girl hours but make it functional 😭

Any necessary message acknowledgements and status communications are handled in the background without any intervention from the client application. it just does it, periodt.

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

💖 int MQTTAsync_setMessageArrivedCallback (MQTTAsync handle, void * context, MQTTAsync_messageArrived * ma) [extern]

This function sets the callback function for a message arrived event for a specific client. incoming messages, we love to see it 🦋

Any necessary message acknowledgements and status communications are handled in the background without any intervention from the client application.

And listen — 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. like, radio silence. nothing. ngl that's on you 🙈

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

💖 int MQTTAsync_setDeliveryCompleteCallback (MQTTAsync handle, void * context, MQTTAsync_deliveryComplete * dc) [extern]

This function sets the callback function for a delivery complete event for a specific client. delivered, slayed, done 💅✨

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. Like, literally do not try this while connected, bestie. 💅
  • handle — A valid client handle from a successful call to MQTTAsync_create(). ✨
  • context — A pointer to any application-specific context. 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. ❌

int MQTTAsync_setConnected (MQTTAsync handle, void * context, MQTTAsync_connected * co) [extern] ✨

Sets the MQTTAsync_connected() callback function for a client. No cap, it's giving callback energy. 💖

Parameters:

  • handle — A valid client handle from a successful call to MQTTAsync_create(). 💖
  • context — A pointer to any application-specific context. 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. ❌

int MQTTAsync_reconnect (MQTTAsync handle) [extern] 🔄

Reconnects a client with the previously used connect options. Connect must have previously been called for this to work. So like, you gotta have connected before you can reconnect. Periodt. 💅

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

int MQTTAsync_create (MQTTAsync * handle, const char * serverURI, const char * clientId, int persistence_type, void * persistence_context) [extern] 🎉

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(). It's the main character of client creation, fr fr. 👑

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 tls:// or mqtts:// — Encrypted SSL/TLS
    • ws:// — Insecure websockets
    • wss:// — Secure web sockets

The TLS enabled prefixes (ssl, tls, 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. ✅

int MQTTAsync_createWithOptions (MQTTAsync * handle, const char * serverURI, const char * clientId, int persistence_type, void * persistence_context, MQTTAsync_createOptions * options) [extern] 🎀

(no description in the original, just the signature — but you know it's the same vibe as MQTTAsync_create with extra options, iykyk 💅)

int MQTTAsync_connect (MQTTAsync handle, const MQTTAsync_connectOptions * options) [extern] 🔌

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(). So like, set those callbacks first, bestie. 🫶

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

✅ for accepted, and those error codes are giving ❌ energy, but at least you know what's up.

💖 MQTTAsync_disconnect

int MQTTAsync_disconnect (MQTTAsync handle, const MQTTAsync_disconnectOptions * options) [extern]

Okay so bestie, this one is the ✨ goodbye button ✨. It attempts to disconnect the client from the MQTT server. But like, not instantly — because we're polite. 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

int MQTTAsync_isConnected (MQTTAsync handle) [extern]

This function allows the client application to test whether or not a client is currently connected to the MQTT server. Like a vibe check for your connection. 👀

Parameters

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

Returns

  • Boolean true if the client is connected, otherwise false. No cap. ✅❌

🎀 MQTTAsync_subscribe

int MQTTAsync_subscribe (MQTTAsync handle, const char * topic, int qos, MQTTAsync_responseOptions * response) [extern]

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()). It's giving "let me in, bestie" energy. 🔑

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

int MQTTAsync_subscribeMany (MQTTAsync handle, int count, char *const * topic, const int * qos, MQTTAsync_responseOptions * response) [extern]

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()). Bestie said "give me the whole menu." 📋✨

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

int MQTTAsync_unsubscribe (MQTTAsync handle, const char * topic, MQTTAsync_responseOptions * response) [extern]

This function attempts to remove an existing subscription made by the specified client. It's the "we're not friends anymore" button, but make it MQTT. 💔

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

int MQTTAsync_unsubscribeMany (MQTTAsync handle, int count, char *const * topic, MQTTAsync_responseOptions * response) [extern]

This function attempts to remove existing subscriptions to a list of topics made by the specified client. Mass unfollow, periodt. 🚫

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

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

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()). Sending a message is literally main character energy. 💌

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

int MQTTAsync_sendMessage (MQTTAsync handle, const char * destinationName, const MQTTAsync_message * msg, MQTTAsync_responseOptions * response) [extern]

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()). It's the full-message flex. 💅

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

int MQTTAsync_getPendingTokens (MQTTAsync handle, MQTTAsync_token ** tokens) [extern]

This function sets a pointer to an array of tokens for messages that are currently in-flight (pending completion). It's like checking who's still in the group chat but hasn't replied. 👀

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. Don't forget, bestie, or it's a leak. 😭

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

int MQTTAsync_isComplete (MQTTAsync handle, MQTTAsync_token token) [extern]

That's the whole entry, bestie. No description, just the signature. It's giving mysterious. 👑

🕰️ MQTTAsync_waitForCompletion

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

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. So if QoS is 0, it's an instant slay. ✨

Okay so for that function from before, here's the tea on its 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. ✨

void MQTTAsync_freeMessage (MQTTAsync_message ** msg) [extern]

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

void MQTTAsync_free (void * ptr) [extern]

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

void * MQTTAsync_malloc (size_t size) [extern]

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

void MQTTAsync_destroy (MQTTAsync * handle) [extern]

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

void MQTTAsync_setTraceLevel (enum MQTTASYNC_TRACE_LEVELS level) [extern]

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

Parameters

  • level — the trace level required 👑

void MQTTAsync_setTraceCallback (MQTTAsync_traceCallback * callback) [extern]

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_nameValue * MQTTAsync_getVersionInfo (void ) [extern]

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

const char * MQTTAsync_strerror (int code) [extern]

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

👑 Author 👑

Generated automatically by Doxygen for Paho Asynchronous MQTT C Client Library from the source code.

And that's a wrap, bestie! This whole thing was generated automatically by Doxygen for Paho Asynchronous MQTT C... — dated Tue Jun 2 2026 00:00:00 — and it's all for MQTTAsync.h(3). Stay slaying with your async MQTT! 💅✨

📦 where this page comes from