MQTTClient.h(3)

📦
version 1.3.16 · 7 versions
, in fedora 44

💖 NAME 💖

okay so bestie 💖, this page is MQTTClient.h from the Library Functions Manual, section 3. it's part 1 of 6 and it's giving "we're about to get so fluent in MQTT client" energy ✨. no cap. this first chunk is the NAME and SYNOPSIS with all the structs, macros, typedefs, enums, and function signatures you need to know. keep every token exactly as written, okay? periodt 💅

✨ SYNOPSIS ✨

first up, the includes. yes, all five. don't skip any, bestie 🫶:

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

🦋 Data Structures 🦋

these are the structs, and they're all main character energy in their own way 💜:

  • struct MQTTClient_init_options
  • struct MQTTClient_message
  • struct MQTTClient_createOptions
  • struct MQTTClient_willOptions
  • struct MQTTClient_SSLOptions
  • struct MQTTClient_nameValue
  • struct MQTTClient_connectOptions
  • struct MQTTResponse

🎀 Macros 🎀

okay so the macros? literally the whole lore 🔥. return codes, version numbers, initializers, all of it. keep every single one exactly as written, fr fr:

#define MQTTCLIENT_SUCCESS   0
#define MQTTCLIENT_FAILURE   -1
#define MQTTCLIENT_DISCONNECTED   -3
#define MQTTCLIENT_MAX_MESSAGES_INFLIGHT   -4
#define MQTTCLIENT_BAD_UTF8_STRING   -5
#define MQTTCLIENT_NULL_PARAMETER   -6
#define MQTTCLIENT_TOPICNAME_TRUNCATED   -7
#define MQTTCLIENT_BAD_STRUCTURE   -8
#define MQTTCLIENT_BAD_QOS   -9
#define MQTTCLIENT_SSL_NOT_SUPPORTED   -10
#define MQTTCLIENT_BAD_MQTT_VERSION   -11
#define MQTTCLIENT_BAD_PROTOCOL   -14
#define MQTTCLIENT_BAD_MQTT_OPTION   -15
#define MQTTCLIENT_WRONG_MQTT_VERSION   -16
#define MQTTCLIENT_0_LEN_WILL_TOPIC   -17
#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 MQTTClient_init_options_initializer   { {'M', 'Q', 'T', 'G'}, 0, 0 }
#define MQTTClient_message_initializer   { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer }
#define MQTTClient_createOptions_initializer   { {'M', 'Q', 'C', 'O'}, 0, MQTTVERSION_DEFAULT }
#define MQTTClient_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 MQTTClient_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 MQTTClient_connectOptions_initializer
#define MQTTClient_connectOptions_initializer5
#define MQTTClient_connectOptions_initializer_ws
#define MQTTClient_connectOptions_initializer5_ws
#define MQTTResponse_initializer   {1, MQTTREASONCODE_SUCCESS, 0, NULL, NULL}

🧚 Typedefs 🧚

these typedefs are the blueprint besties 🌈. function pointers, handles, tokens, all of it:

typedef void * MQTTClient
typedef int MQTTClient_deliveryToken
typedef int MQTTClient_token
typedef int MQTTClient_messageArrived(void *context, char *topicName, int topicLen, MQTTClient_message *message)
typedef void MQTTClient_deliveryComplete(void *context, MQTTClient_deliveryToken dt)
typedef void MQTTClient_connectionLost(void *context, char *cause)
typedef void MQTTClient_disconnected(void *context, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
typedef void MQTTClient_published(void *context, int dt, int packet_type, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
typedef struct MQTTResponse MQTTResponse
typedef void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char *message)

👑 Enumerations 👑

one enum, but it's iconic 💛. trace levels, from maximum down to fatal:

enum MQTTCLIENT_TRACE_LEVELS { MQTTCLIENT_TRACE_MAXIMUM = 1, MQTTCLIENT_TRACE_MEDIUM, MQTTCLIENT_TRACE_MINIMUM, MQTTCLIENT_TRACE_PROTOCOL, MQTTCLIENT_TRACE_ERROR, MQTTCLIENT_TRACE_SEVERE, MQTTCLIENT_TRACE_FATAL }

🔥 Functions 🔥

and here's the whole function lineup. every signature, exactly as written. don't change a single character, i'm literally begging 🙈:

void MQTTClient_global_init (MQTTClient_init_options *inits)
int MQTTClient_setCallbacks (MQTTClient handle, void *context, MQTTClient_connectionLost *cl, MQTTClient_messageArrived *ma, MQTTClient_deliveryComplete *dc)
int MQTTClient_setDisconnected (MQTTClient handle, void *context, MQTTClient_disconnected *co)
int MQTTClient_setPublished (MQTTClient handle, void *context, MQTTClient_published *co)
int MQTTClient_create (MQTTClient *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context)
int MQTTClient_createWithOptions (MQTTClient *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context, MQTTClient_createOptions *options)
MQTTClient_nameValue * MQTTClient_getVersionInfo (void)
int MQTTClient_connect (MQTTClient handle, MQTTClient_connectOptions *options)
void MQTTResponse_free (MQTTResponse response)
MQTTResponse MQTTClient_connect5 (MQTTClient handle, MQTTClient_connectOptions *options, MQTTProperties *connectProperties, MQTTProperties *willProperties)
int MQTTClient_disconnect (MQTTClient handle, int timeout)
int MQTTClient_disconnect5 (MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties *props)
int MQTTClient_isConnected (MQTTClient handle)
int MQTTClient_subscribe (MQTTClient handle, const char *topic, int qos)
MQTTResponse MQTTClient_subscribe5 (MQTTClient handle, const char *topic, int qos, MQTTSubscribe_options *opts, MQTTProperties *props)
int MQTTClient_subscribeMany (MQTTClient handle, int count, char *const *topic, int *qos)
MQTTResponse MQTTClient_subscribeMany5 (MQTTClient handle, int count, char *const *topic, int *qos, MQTTSubscribe_options *opts, MQTTProperties *props)
int MQTTClient_unsubscribe (MQTTClient handle, const char *topic)
MQTTResponse MQTTClient_unsubscribe5 (MQTTClient handle, const char *topic, MQTTProperties *props)
int MQTTClient_unsubscribeMany (MQTTClient handle, int count, char *const *topic)
MQTTResponse MQTTClient_unsubscribeMany5 (MQTTClient handle, int count, char *const *topic, MQTTProperties *props)
int MQTTClient_publish (MQTTClient handle, const char *topicName, int payloadlen, const void *payload, int qos, int retained, MQTTClient_deliveryToken *dt)
MQTTResponse MQTTClient_publish5 (MQTTClient handle, const char *topicName, int payloadlen, const void *payload, int qos, int retained, MQTTProperties *properties, MQTTClient_deliveryToken *dt)
int MQTTClient_publishMessage (MQTTClient handle, const char *topicName, MQTTClient_message *msg, MQTTClient_deliveryToken *dt)
MQTTResponse MQTTClient_publishMessage5 (MQTTClient handle, const char *topicName, MQTTClient_message *msg, MQTTClient_deliveryToken *dt)
int MQTTClient_waitForCompletion (MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout)
int MQTTClient_getPendingDeliveryTokens (MQTTClient handle, MQTTClient_deliveryToken **tokens)
void MQTTClient_yield (void)
int MQTTClient_receive (MQTTClient handle, char **topicName, int *topicLen, MQTTClient_message **message, unsigned long timeout)
void MQTTClient_freeMessage (MQTTClient_message **msg)
void MQTTClient_free (void *ptr)
void * MQTTClient_malloc (size_t size)
void MQTTClient_destroy (MQTTClient *handle)
void MQTTClient_setTraceLevel (enum MQTTCLIENT_TRACE_LEVELS level)
void MQTTClient_setTraceCallback (MQTTClient_traceCallback *callback)
int MQTTClient_setCommandTimeout (MQTTClient handle, unsigned long milliSeconds)
const char * MQTTClient_strerror (int code)

💖 MACRO DEFINITION DOCUMENTATION 💖

okay bestie, welcome to the macro zone, and no cap this is where all the little constants and initializer recipes live. it's giving the secret sauce 🫶✨ every single one matters, so we're going through them all, fr fr.

  • MQTTCLIENT_SUCCESS — Return code: No error. Indicates successful completion of an MQTT client operation.
#define MQTTCLIENT_SUCCESS   0
  • MQTTCLIENT_FAILURE — Return code: A generic error code indicating the failure of an MQTT client operation.
#define MQTTCLIENT_FAILURE   -1
  • MQTTCLIENT_DISCONNECTED — Return code: The client is disconnected.
#define MQTTCLIENT_DISCONNECTED   -3
  • MQTTCLIENT_MAX_MESSAGES_INFLIGHT — Return code: The maximum number of messages allowed to be simultaneously in-flight has been reached.
#define MQTTCLIENT_MAX_MESSAGES_INFLIGHT   -4
  • MQTTCLIENT_BAD_UTF8_STRING — Return code: An invalid UTF-8 string has been detected.
#define MQTTCLIENT_BAD_UTF8_STRING   -5
  • MQTTCLIENT_NULL_PARAMETER — Return code: A NULL parameter has been supplied when this is invalid.
#define MQTTCLIENT_NULL_PARAMETER   -6
  • MQTTCLIENT_TOPICNAME_TRUNCATED — 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 MQTTCLIENT_TOPICNAME_TRUNCATED   -7
  • MQTTCLIENT_BAD_STRUCTURE — Return code: A structure parameter does not have the correct eyecatcher and version number.
#define MQTTCLIENT_BAD_STRUCTURE   -8
  • MQTTCLIENT_BAD_QOS — Return code: A QoS value that falls outside of the acceptable range (0,1,2)
#define MQTTCLIENT_BAD_QOS   -9
  • MQTTCLIENT_SSL_NOT_SUPPORTED — Return code: Attempting SSL connection using non-SSL version of library
#define MQTTCLIENT_SSL_NOT_SUPPORTED   -10
  • MQTTCLIENT_BAD_MQTT_VERSION — Return code: unrecognized MQTT version
#define MQTTCLIENT_BAD_MQTT_VERSION   -11
  • MQTTCLIENT_BAD_PROTOCOL — 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 a TLS version of the library is linked with.

#define MQTTCLIENT_BAD_PROTOCOL   -14
  • MQTTCLIENT_BAD_MQTT_OPTION — Return code: option not applicable to the requested version of MQTT
#define MQTTCLIENT_BAD_MQTT_OPTION   -15
  • MQTTCLIENT_WRONG_MQTT_VERSION — Return code: call not applicable to the requested version of MQTT
#define MQTTCLIENT_WRONG_MQTT_VERSION   -16
  • MQTTCLIENT_0_LEN_WILL_TOPIC — Return code: 0 length will topic on connect
#define MQTTCLIENT_0_LEN_WILL_TOPIC   -17
  • MQTTVERSION_DEFAULT — Default MQTT version to connect with. Use 3.1.1 then fall back to 3.1
#define MQTTVERSION_DEFAULT   0
  • MQTTVERSION_3_1 — MQTT version to connect with: 3.1
#define MQTTVERSION_3_1   3
  • MQTTVERSION_3_1_1 — MQTT version to connect with: 3.1.1
#define MQTTVERSION_3_1_1   4
  • MQTTVERSION_5 — MQTT version to connect with: 5
#define MQTTVERSION_5   5
  • MQTT_BAD_SUBSCRIBE — Bad return code from subscribe, as defined in the 3.1.1 specification
#define MQTT_BAD_SUBSCRIBE   0x80
  • MQTTClient_init_options_initializer — initializer for init options.
#define MQTTClient_init_options_initializer   { {'M', 'Q', 'T', 'G'}, 0, 0 }
  • MQTTClient_message_initializer — initializer for message struct.
#define MQTTClient_message_initializer   { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer }
  • MQTTClient_createOptions_initializer — initializer for create options.
#define MQTTClient_createOptions_initializer   { {'M', 'Q', 'C', 'O'}, 0, MQTTVERSION_DEFAULT }
  • MQTTClient_willOptions_initializer — initializer for will options.
#define MQTTClient_willOptions_initializer   { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, {0, NULL} }
  • MQTT_SSL_VERSION_DEFAULT — default SSL version.
#define MQTT_SSL_VERSION_DEFAULT   0
  • MQTT_SSL_VERSION_TLS_1_0 — TLS 1.0.
#define MQTT_SSL_VERSION_TLS_1_0   1
  • MQTT_SSL_VERSION_TLS_1_1 — TLS 1.1.
#define MQTT_SSL_VERSION_TLS_1_1   2
  • MQTT_SSL_VERSION_TLS_1_2 — TLS 1.2.
#define MQTT_SSL_VERSION_TLS_1_2   3
  • MQTTClient_SSLOptions_initializer — initializer for SSL options.
#define MQTTClient_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 }
  • MQTTClient_connectOptions_initializer — Initializer for connect options for MQTT 3.1.1 non-WebSocket connections.
#define MQTTClient_connectOptions_initializer
    Value:
    { {'M', 'Q', 'T', 'C'}, 8, 60, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\
    0, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL}
  • MQTTClient_connectOptions_initializer5 — Initializer for connect options for MQTT 5.0 non-WebSocket connections.
#define MQTTClient_connectOptions_initializer5
    Value:
    { {'M', 'Q', 'T', 'C'}, 8, 60, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\
    0, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL}
  • MQTTClient_connectOptions_initializer_ws — 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 MQTTClient_connectOptions_initializer_ws
    Value:
    { {'M', 'Q', 'T', 'C'}, 8, 45, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\
    0, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL}
  • MQTTClient_connectOptions_initializer5_ws — 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 MQTTClient_connectOptions_initializer5_ws
    Value:
    { {'M', 'Q', 'T', 'C'}, 8, 45, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\
    0, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL}
  • MQTTResponse_initializer — initializer for response struct.
#define MQTTResponse_initializer   {1, MQTTREASONCODE_SUCCESS, 0, NULL, NULL}

🦋 TYPEDEF DOCUMENTATION 🦋

okay bestie, this is where the library introduces you to all its little named types, and honestly? each one is a whole personality. let's meet them 💖

💅 typedef void* MQTTClient

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

so basically: this is your client's little ID badge 🪪 — you only get a valid one after MQTTClient_create() actually works. no create, no badge, no vibes.

🎀 typedef int MQTTClient_deliveryToken

A value representing an MQTT message. A delivery 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 MQTTClient_publish(), MQTTClient_publishMessage(), MQTTClient_deliveryComplete(), MQTTClient_waitForCompletion() and MQTTClient_getPendingDeliveryTokens()).

it's giving "receipt for your message" 🧾 — you publish, you get a token back, and then you can go check if your lil message actually made it to its destination. the cross-references for that whole journey are: MQTTClient_publish(), MQTTClient_publishMessage(), MQTTClient_deliveryComplete(), MQTTClient_waitForCompletion() and MQTTClient_getPendingDeliveryTokens().

🌸 typedef int MQTTClient_token

bestie... that's it. that's the whole description. no notes, no lore, just a type. we move 🫶

✨ typedef int MQTTClient_messageArrived(void *context, char *topicName, int topicLen, MQTTClient_message *message)

This is a callback function. The client application must provide an implementation of this function to enable asynchronous receipt of messages. The function is registered with the client library by passing it as an argument to MQTTClient_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.

it's giving "your phone buzzing with a new notif" 📲 — you must write this function yourself if you want messages to arrive asynchronously, you hand it over as an argument to MQTTClient_setCallbacks(), and the library calls it whenever a message matching one of your subscriptions lands from the server. also important: it runs on a separate thread from your app's main one. so mind your threading, queen 👑

💜 Parameters

  • context — A pointer to the context value originally passed to MQTTClient_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 MQTTClient_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, MQTTClient_freeMessage must be called. To free the topic name storage, MQTTClient_free must be called.
  • Returning 0 indicates that there was a problem. In this case, the client library will reinvoke MQTTClient_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.
⚠️ okay this part is lowkey serious: if you return 0, do NOT free the message and topic storage, or the redelivery will fail. the library is literally going to try again, so don't yank the rug out from under it 💀

🧚 typedef void MQTTClient_deliveryComplete(void *context, MQTTClient_deliveryToken dt)

This is a callback function. The client application must provide an implementation of this function to enable asynchronous notification of delivery of messages. The function is registered with the client library by passing it as an argument to MQTTClient_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 MQTTClient_message.qos) have been completed. This function is executed on a separate thread to the one on which the client application is running. Note: MQTTClient_deliveryComplete() is not called when messages are published at QoS0.

this is the "delivered ✅" ping you get after you publish — all the handshaking and acknowledgements for the QoS you asked for (peep MQTTClient_message.qos) are done, so this callback fires. runs on its own separate thread, obviously, because everything here has main character energy and refuses to share a thread. and ✋ heads up: MQTTClient_deliveryComplete() is not called when messages are published at QoS0. zero, none, silence.

💜 Parameters

  • context — A pointer to the context value originally passed to MQTTClient_setCallbacks(), which contains any application-specific context.
  • dt — The MQTTClient_deliveryToken associated with the published message. Applications can check that all messages have been correctly published by matching the delivery tokens returned from calls to MQTTClient_publish() and MQTTClient_publishMessage() with the tokens passed to this callback.

🌈 typedef void MQTTClient_connectionLost(void *context, char *cause)

This is a callback function. The client application must provide an implementation of this function to enable asynchronous notification of the loss of connection to the server. The function is registered with the client library by passing it as an argument to MQTTClient_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.

it's giving "bestie we got ghosted by the server 😭" — register it via MQTTClient_setCallbacks() and the library will ring it up the moment the connection drops. you have to handle it: try reconnecting, log the problem, whatever fits. again, separate thread, because of course.

💜 Parameters

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

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

This is a callback function, which will be called when the a disconnect packet is received from the server. This applies to MQTT V5 and above only.

v5 girlies rise 💅 this one fires when a disconnect packet shows up from the server — and remember, V5 and above only, so if you're on older MQTT, this is not your moment.

💜 Parameters

  • context — A pointer to the context value originally passed to MQTTClient_setDisconnected(), which contains any application-specific context.
  • properties — The MQTT V5 properties received with the disconnect, if any.
  • reasonCode — The MQTT V5 reason code received with the disconnect. Currently, cause is always set to NULL.

🔥 typedef void MQTTClient_published(void *context, int dt, int packet_type, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)

This is a callback function, the MQTT V5 version of MQTTClient_deliveryComplete(). The client application must provide an implementation of this function to enable asynchronous notification of the completed delivery of messages. 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 MQTTClient_message.qos) have been completed. This function is executed on a separate thread to the one on which the client application is running. Note: It is not called when messages are published at QoS0.

the glow-up version of MQTTClient_deliveryComplete() for MQTT V5 ✨ same deal: you implement it, it fires after you publish, it means the handshaking and acks for your requested QoS (see MQTTClient_message.qos) are all done, and yep — separate thread. and same note as before, because it matters: it is not called when messages are published at QoS0.

💜 Parameters

  • context — A pointer to the context value originally passed to MQTTClient_setCallbacks(), which contains any application-specific context.
  • dt — The MQTTClient_deliveryToken associated with the published message. Applications can check that all messages have been correctly published by matching the delivery tokens returned from calls to MQTTClient_publish() and MQTTClient_publishMessage() with the tokens passed to this callback.
  • packet_type — the last received packet type for this completion. For QoS 1 always PUBACK. For QoS 2 could be PUBREC or PUBCOMP.
  • properties — the MQTT V5 properties returned with the last packet from the server.
  • reasonCode — the reason code returned from the server.

👑 typedef struct MQTTResponse MQTTResponse

MQTT version 5.0 response information.

short and iconic. it's the v5.0 response info, periodt 💖

🎀 typedef void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char *message)

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.

so if you want the tea on what's happening internally (trace info, iykyk), you implement this. but listen: do not invoke any other Paho API calls in this callback function — unpredictable behavior may result. it's giving "don't text back while you're already on the phone with the server" 🙈

💜 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.
🌸 psst: that message pointer is a static buffer that gets overwritten every single call. if you want to keep it, COPY IT. don't just stash the pointer and cry later 😭

🌟 ENUMERATION TYPE DOCUMENTATION 🌟

💫 enum MQTTCLIENT_TRACE_LEVELS

the trace levels, from max chatter to full-on fatal. here's the whole set, no skipping:

Enumerator

  • MQTTCLIENT_TRACE_MAXIMUM
  • MQTTCLIENT_TRACE_MEDIUM
  • MQTTCLIENT_TRACE_MINIMUM
  • MQTTCLIENT_TRACE_PROTOCOL
  • MQTTCLIENT_TRACE_ERROR
  • MQTTCLIENT_TRACE_SEVERE
  • MQTTCLIENT_TRACE_FATAL

⭐ FUNCTION DOCUMENTATION ⭐

🫶 void MQTTClient_global_init (MQTTClient_init_options * inits) [extern]

Global init of mqtt library. Call once on program start to set global behaviour.

  • do_openssl_init — if mqtt library should initialize OpenSSL (1) or rely on the caller to do it before using the library (0).

so: call this once, at program start, to set the global behaviour of the whole library. and do_openssl_init is the switch — 1 means the mqtt library initializes OpenSSL for you, 0 means it's on you to do it before using the library. pick your fighter 💅

💖 int MQTTClient_setCallbacks (MQTTClient handle, void * context, MQTTClient_connectionLost * cl, MQTTClient_messageArrived * ma, MQTTClient_deliveryComplete * dc) [extern]

This function sets the callback functions for a specific client. If your client application doesn't use a particular callback, set the relevant parameter to NULL (except for message arrived, which must be given). Calling MQTTClient_setCallbacks() puts the client into multi-threaded mode. Any necessary message acknowledgements and status communications are handled in the background without any intervention from the client application. See Asynchronous vs synchronous client applications for more information.

this is where you hand over your callbacks for a specific client 🎁 — and if you don't use one of them, just set that parameter to NULL. the one exception? message arrived must be given. no NULL there, sorry bestie.

and the big glow-up: calling MQTTClient_setCallbacks() drops the client into multi-threaded mode, which means all the message acknowledgements and status communications get handled in the background, no intervention needed from you. it's giving "the library is handling it, you go be great" ✨ see Asynchronous vs synchronous client applications for more.

Note: the MQTT client must be disconnected when this function is called. Like, not connected. At all. Periodt.

Parameters 💜

  • handle — a valid client handle from a successful call to MQTTClient_create(). Gotta have the goods.
  • context — a pointer to any application-specific context. This context pointer gets passed to each of the callback functions so they can actually reach the context info inside the callback. It's giving ✨shared memory✨.
  • cl — a pointer to an MQTTClient_connectionLost() callback function. Set it to NULL if your application just… doesn't handle disconnections. (Bold choice, bestie, but okay 💅)
  • ma — a pointer to an MQTTClient_messageArrived() callback function. This one must be set when you call MQTTClient_setCallbacks(), because otherwise there's literally nowhere for incoming messages to land. Like a delivery with no mailbox 🫶
  • dc — a pointer to an MQTTClient_deliveryComplete() callback function. Set it to NULL if your application publishes synchronously, or if you simply do not care to check whether delivery succeeded. Live your truth 🌸

Returns 🎀

  • MQTTCLIENT_SUCCESS if the callbacks were correctly set
  • MQTTCLIENT_FAILURE if an error occurred 😭

int MQTTClient_setDisconnected (MQTTClient handle, void * context, MQTTClient_disconnected * co) [extern]

Sets the MQTTClient_disconnected() callback function for a client. This one gets called if a disconnect packet is received from the server. Only valid for MQTT V5 and above — no cap, older versions don't get to play.

Parameters 🦋

  • handle — a valid client handle from a successful call to MQTTClient_create().
  • context — a pointer to any application-specific context. This pointer is passed to each of the callback functions to provide access to the context information inside the callback.
  • co — a pointer to an MQTTClient_disconnected() callback function. Passing NULL removes the callback setting. Poof, gone 💨

Returns ✨

  • MQTTCLIENT_SUCCESS if the callbacks were correctly set
  • MQTTCLIENT_FAILURE if an error occurred

int MQTTClient_setPublished (MQTTClient handle, void * context, MQTTClient_published * co) [extern]

Okay so this one is literally just the signature. The manpage gives us the function and then dips — no description, no parameters, no returns section. That's the whole thing. Iconic of it to show up with zero context 🙈

int MQTTClient_create (MQTTClient * handle, const char * serverURI, const char * clientId, int persistence_type, void * persistence_context) [extern]

THE moment. This function creates an MQTT client, all ready to connect to the server you specify, using the persistent storage you specify (peep MQTTClient_persistence for that). Also go look at MQTTClient_destroy() when you're done with it — clean up after yourself, queen 👑

Parameters 💖

  • handle — a pointer to an MQTTClient handle. Once this function returns successfully, that handle gets populated with a valid client reference. It's giving new-baby energy 🎀
  • serverURI — a null-terminated string saying which server the client will connect to. The form is protocol://host:port. Currently, the protocol must be one of:
    • tcp:// or mqtt:// — Insecure TCP
    • ssl:// or tls:// or mqtts:// — Encrypted SSL/TLS
    • ws:// — Insecure websockets
    • wss:// — Secure web sockets
Heads up: the TLS-enabled prefixes (ssl, tls, mqtts, wss) are only valid if a TLS version of the library is linked with. No TLS library, no TLS prefixes. Periodt.

For host, you can drop either an IP address or a host name. So like, to connect to a server running on the local machine with the default MQTT port, you'd specify tcp://localhost:1883. Simple as 🦋

  • clientId — the client identifier that gets passed to the server when the client connects. It's a null-terminated UTF-8 encoded string.
  • persistence_type — the type of persistence the client is gonna use:
    • MQTTCLIENT_PERSISTENCE_NONE: use in-memory persistence. If the device or system the client is running on fails or gets switched off, the current state of any in-flight messages is lost, and some messages may not be delivered even at QoS1 and QoS2. 💀 Yeah. Read that again.
    • MQTTCLIENT_PERSISTENCE_DEFAULT: use the default (file system-based) persistence mechanism. Status about in-flight messages is held in persistent storage, which gives you some protection against message loss if something unexpectedly fails. Protection, not a promise 🫶
    • MQTTCLIENT_PERSISTENCE_USER: use an application-specific persistence implementation. This hands control of the persistence mechanism over to the application — which means the application has to implement the MQTTClient_persistence interface itself. You wanted the keys, now drive 🚗
  • persistence_context — depends on the vibe:
    • If the application uses MQTTCLIENT_PERSISTENCE_NONE, this argument is unused and should be set to NULL.
    • For MQTTCLIENT_PERSISTENCE_DEFAULT, set it to the location of the persistence directory. If you set it to NULL, the persistence directory used is the working directory.
    • Applications using MQTTCLIENT_PERSISTENCE_USER set this argument to point to a valid MQTTClient_persistence structure.

Returns ⭐

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

int MQTTClient_createWithOptions (MQTTClient * handle, const char * serverURI, const char * clientId, int persistence_type, void * persistence_context, MQTTClient_createOptions * options) [extern]

A version of MQTTClient_create() that comes with additional options — like the deluxe edition 💅 This function creates an MQTT client ready for connection to the specified server and using the specified persistent storage (see MQTTClient_persistence). See also MQTTClient_destroy().

Parameters 🌈

  • handle — a pointer to an MQTTClient 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 the client will connect to. It takes the form protocol://host:port. Currently, the protocol must be tcp or ssl. For host, you can specify either an IP address or a host name. For instance, to connect to a server running on the local machines with the default MQTT port, specify tcp://localhost:1883.
  • clientId — the client identifier passed to the server when the client connects to it. It is a null-terminated UTF-8 encoded string.
  • persistence_type — the type of persistence to be used by the client:
    • MQTTCLIENT_PERSISTENCE_NONE: use in-memory persistence. If the device or system on which the client is running fails or is switched off, the current state of any in-flight messages is lost and some messages may not be delivered even at QoS1 and QoS2.
    • MQTTCLIENT_PERSISTENCE_DEFAULT: use the default (file system-based) persistence mechanism. Status about in-flight messages is held in persistent storage and provides some protection against message loss in the case of unexpected failure.
    • MQTTCLIENT_PERSISTENCE_USER: use an application-specific persistence implementation. Using this type of persistence gives control of the persistence mechanism to the application. The application has to implement the MQTTClient_persistence interface.
  • persistence_context — if the application uses MQTTCLIENT_PERSISTENCE_NONE persistence, this argument is unused and should be set to NULL. For MQTTCLIENT_PERSISTENCE_DEFAULT persistence, it should be set to the location of the persistence directory (if set to NULL, the persistence directory used is the working directory). Applications that use MQTTCLIENT_PERSISTENCE_USER persistence set this argument to point to a valid MQTTClient_persistence structure.
  • options — additional options for the create. The little extras 🎁

Returns ✨

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

MQTTClient_nameValue * MQTTClient_getVersionInfo (void ) [extern]

This function returns version info about the library. No trace information will be returned — just the version tea, nothing extra.

Returns 👑

  • an array of strings describing the library. The last entry is a NULL pointer. That NULL is your stopping signal, bestie — don't walk past it.

int MQTTClient_connect (MQTTClient handle, MQTTClient_connectOptions * options) [extern]

This function attempts to connect a previously-created client (see MQTTClient_create()) to an MQTT server using the options you specify. If you want asynchronous message and status notifications, you must call MQTTClient_setCallbacks() prior to MQTTClient_connect() — order matters, no skipping steps 💅

Parameters 💜

  • handle — a valid client handle from a successful call to MQTTClient_create().
  • options — a pointer to a valid MQTTClient_connectOptions structure.

Returns 🎀

  • MQTTCLIENT_SUCCESS if the client successfully connects to the server.
  • An error code is returned if the client was unable to connect to the server. 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
So if you get a number back that isn't MQTTCLIENT_SUCCESS, check the chart. 1 through 5 have meanings, 6-255 are just sitting there reserved for future use — do not go guessing what they do 🙈

void MQTTResponse_free (MQTTResponse response) [extern] 🧹

Frees the storage associated with the MQTT response. Bestie, when you're done with a response, you gotta let it go — otherwise that memory just sits there being extra. 💅

Parameters

  • response — the response structure to be freed

MQTTResponse MQTTClient_connect5 (MQTTClient handle, MQTTClient_connectOptions * options, MQTTProperties * connectProperties, MQTTProperties * willProperties) [extern] 🔌✨

Attempts to connect a previously-created client (see MQTTClient_create()) to an MQTT server using MQTT version 5.0 and the specified options. If you want to enable asynchronous message and status notifications, you must call MQTTClient_setCallbacks() prior to MQTTClient_connect(). no cap, do the callbacks thing first. 🫶

Parameters

  • handle — A valid client handle from a successful call to MQTTClient_create().
  • options — A pointer to a valid MQTTClient_connectOptions structure.
  • connectProperties — the MQTT 5.0 connect properties to use
  • willProperties — the MQTT 5.0 properties to set on the will message

Returns

  • the MQTT 5.0 response information: error codes and properties. 👑

int MQTTClient_disconnect (MQTTClient handle, int timeout) [extern] 🚪

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 MQTTClient_connectOptions.cleansession and MQTTClient_connect()). it's giving "leaving the group chat but the messages still send" energy ngl 😭

Parameters

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

Returns

  • MQTTCLIENT_SUCCESS if the client successfully disconnects from the server. An error code is returned if the client was unable to disconnect from the server

int MQTTClient_disconnect5 (MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties * props) [extern] 🚪5️⃣

int MQTTClient_isConnected (MQTTClient handle) [extern] 🕵️♀️💖

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

Parameters

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

Returns

  • Boolean true if the client is connected, otherwise false. 🦋

int MQTTClient_subscribe (MQTTClient handle, const char * topic, int qos) [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 MQTTClient_subscribeMany()).

Parameters

  • handle — A valid client handle from a successful call to MQTTClient_create().
  • topic — The subscription topic, which may include wildcards.
  • qos — The requested quality of service for the subscription.

Returns

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

MQTTResponse MQTTClient_subscribe5 (MQTTClient handle, const char * topic, int qos, MQTTSubscribe_options * opts, MQTTProperties * props) [extern] 📥5️⃣✨

This function attempts to subscribe an MQTT version 5.0 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 MQTTClient_subscribeMany()).

Parameters

  • handle — A valid client handle from a successful call to MQTTClient_create().
  • topic — The subscription topic, which may include wildcards.
  • qos — The requested quality of service for the subscription.
  • opts — the MQTT 5.0 subscribe options to be used
  • props — the MQTT 5.0 properties to be used

Returns

  • the MQTT 5.0 response information: error codes and properties. 💜

int MQTTClient_subscribeMany (MQTTClient handle, int count, char *const * topic, int * qos) [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 MQTTClient_subscribe()). it's the "subscribe to everything" era and honestly? valid. 🔥

Parameters

  • handle — A valid client handle from a successful call to MQTTClient_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].

Returns

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

MQTTResponse MQTTClient_subscribeMany5 (MQTTClient handle, int count, char *const * topic, int * qos, MQTTSubscribe_options * opts, MQTTProperties * props) [extern] 📥5️⃣🌈

This function attempts to subscribe an MQTT version 5.0 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 MQTTClient_subscribe()).

Parameters

  • handle — A valid client handle from a successful call to MQTTClient_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].
  • opts — the MQTT 5.0 subscribe options to be used
  • props — the MQTT 5.0 properties to be used

Returns

  • the MQTT 5.0 response information: error codes and properties. ⭐

int MQTTClient_unsubscribe (MQTTClient handle, const char * topic) [extern] 📤🍓

This function attempts to remove an existing subscription made by the specified client. we love a clean unfollow. 🎀

Parameters

  • handle — A valid client handle from a successful call to MQTTClient_create().
  • topic — The topic for the subscription to be removed, which may include wildcards (see Subscription wildcards).

Returns

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

MQTTResponse MQTTClient_unsubscribe5 (MQTTClient handle, const char * topic, MQTTProperties * props) [extern] 📤5️⃣

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

Parameters

  • handle — A valid client handle from a successful call to MQTTClient_create().
  • topic — The topic for the subscription to be removed, which may include wildcards (see Subscription wildcards).
  • props — the MQTT 5.0 properties to be used

Returns

  • the MQTT 5.0 response information: error codes and properties. 🦋

int MQTTClient_unsubscribeMany (MQTTClient handle, int count, char *const * topic) [extern] 📤📤📤

This function attempts to remove existing subscriptions to a list of topics made by the specified client. mass unfollow moment, iconic. 👑

Parameters

  • handle — A valid client handle from a successful call to MQTTClient_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.

Returns

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

MQTTResponse MQTTClient_unsubscribeMany5 (MQTTClient handle, int count, char *const * topic, MQTTProperties * props) [extern] 📤5️⃣💜

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

Parameters

  • handle — A valid client handle from a successful call to MQTTClient_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.
  • props — the MQTT 5.0 properties to be used

Returns

  • the MQTT 5.0 response information: error codes and properties. ✨

int MQTTClient_publish (MQTTClient handle, const char * topicName, int payloadlen, const void * payload, int qos, int retained, MQTTClient_deliveryToken * dt) [extern] 📮🔥

This function attempts to publish a message to a given topic (see also MQTTClient_publishMessage()). An MQTTClient_deliveryToken is issued when this function returns successfully. If the client application needs to test for succesful delivery of QoS1 and QoS2 messages, this can be done either asynchronously or synchronously (see Asynchronous vs synchronous client applications, MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()). the way that delivery token just appears when it works >>> 💅

Parameters

  • handle — A valid client handle from a successful call to MQTTClient_create().
  • topicName — 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.
  • dt — A pointer to an MQTTClient_deliveryToken. This is populated with a token representing the message when the function returns successfully. If your application does not use delivery tokens, set this argument to NULL.

Returns

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

MQTTResponse MQTTClient_publish5 (MQTTClient handle, const char * topicName, int payloadlen, const void * payload, int qos, int retained, MQTTProperties * properties, MQTTClient_deliveryToken * dt) [extern] 📮5️⃣⭐

Attempts to publish a message to a given topic using MQTT version 5.0 (see also MQTTClient_publishMessage5()). An MQTTClient_deliveryToken is issued when this function returns successfully. If the client application needs to test for succesful delivery of QoS1 and QoS2 messages, this can be done either asynchronously or synchronously (see Asynchronous vs synchronous client applications, MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()).

Parameters

  • handle — A valid client handle from a successful call to MQTTClient_create().
  • topicName — 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. 📌
  • properties — the MQTT 5.0 properties to be used. ✨
  • dt — a pointer to an MQTTClient_deliveryToken. This gets populated with a token representing the message when the function returns successfully. If your app doesn't use delivery tokens, set this argument to NULL. Bestie, just say NULL, it's fine. 🫶

Returns

the MQTT 5.0 response information: error codes and properties.

💌 int MQTTClient_publishMessage (MQTTClient handle, const char * topicName, MQTTClient_message * msg, MQTTClient_deliveryToken * dt) [extern]

Okay so this one tries to publish a message to a given topic (peep also MQTTClient_publish()). An MQTTClient_deliveryToken is issued when this function returns successfully. And if your client app needs to test for succesful delivery of QoS1 and QoS2 messages, you can do that either asynchronously or synchronously (go look at Asynchronous vs synchronous client applications, MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()). ✨

Parameters

  • handle — a valid client handle from a successful call to MQTTClient_create().
  • topicName — the topic associated with this message.
  • msg — a pointer to a valid MQTTClient_message structure containing the payload and attributes of the message to be published.
  • dt — a pointer to an MQTTClient_deliveryToken. This is populated with a token representing the message when the function returns successfully. If your application does not use delivery tokens, set this argument to NULL.

Returns

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

🌈 MQTTResponse MQTTClient_publishMessage5 (MQTTClient handle, const char * topicName, MQTTClient_message * msg, MQTTClient_deliveryToken * dt) [extern]

Attempts to publish a message to the given topic using MQTT version 5.0 (see also MQTTClient_publish5()). An MQTTClient_deliveryToken is issued when this function returns successfully. If the client application needs to test for succesful delivery of QoS1 and QoS2 messages, this can be done either asynchronously or synchronously (see Asynchronous vs synchronous client applications, MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()). Same energy as its sibling, just v5 flavoured. 💖

Parameters

  • handle — a valid client handle from a successful call to MQTTClient_create().
  • topicName — the topic associated with this message.
  • msg — a pointer to a valid MQTTClient_message structure containing the payload and attributes of the message to be published.
  • dt — a pointer to an MQTTClient_deliveryToken. This is populated with a token representing the message when the function returns successfully. If your application does not use delivery tokens, set this argument to NULL.

Returns

the MQTT 5.0 response information: error codes and properties.

⏳ int MQTTClient_waitForCompletion (MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout) [extern]

Your client app calls this to sync up the main thread with the completed publication of a message. The moment you call it, MQTTClient_waitForCompletion() blocks execution until the message has been successful delivered or the timeout you specified has expired. See Asynchronous vs synchronous client applications. Yes queen, it will just sit there and wait. That's the whole job. 🛑

Parameters

  • handle — a valid client handle from a successful call to MQTTClient_create().
  • dt — the MQTTClient_deliveryToken that represents the message being tested for successful delivery. Delivery tokens are issued by the publishing functions MQTTClient_publish() and MQTTClient_publishMessage().
  • timeout — the maximum time to wait in milliseconds.

Returns

MQTTCLIENT_SUCCESS if the message was successfully delivered. An error code is returned if the timeout expires or there was a problem checking the token. 😭

🎀 int MQTTClient_getPendingDeliveryTokens (MQTTClient handle, MQTTClient_deliveryToken ** tokens) [extern]

This function sets a pointer to an array of delivery tokens for messages that are currently in-flight (pending completion). Little snapshot of the chaos. 📸

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. Do not forget. I am watching. 👀

Parameters

  • handle — a valid client handle from a successful call to MQTTClient_create().
  • tokens — the address of a pointer to an MQTTClient_deliveryToken. 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

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

🦋 void MQTTClient_yield (void ) [extern]

When implementing a single-threaded client, call this function periodically to allow processing of message retries and to send MQTT keepalive pings. If the application is calling MQTTClient_receive() regularly, then it is not necessary to call this function. So like… it's one or the other, bestie, don't do both. 💅

📥 int MQTTClient_receive (MQTTClient handle, char ** topicName, int * topicLen, MQTTClient_message ** message, unsigned long timeout) [extern]

This function performs a synchronous receive of incoming messages. It should be used only when the client application has not set callback methods to support asynchronous receipt of messages (see Asynchronous vs synchronous client applications and MQTTClient_setCallbacks()). Using this function allows a single-threaded client subscriber application to be written. When called, this function blocks until the next message arrives or the specified timeout expires (see also MQTTClient_yield()). Sit. Wait. Receive. Iconic behaviour, no notes. 🧘

Important note: The application must free() the memory allocated to the topic and the message when processing is complete (see MQTTClient_freeMessage()). No leaks in this household. 🚫

Parameters

  • handle — a valid client handle from a successful call to MQTTClient_create().
  • topicName — the address of a pointer to a topic. This function allocates the memory for the topic and returns it to the application by setting topicName to point to the topic.
  • topicLen — the length of the topic. If the return code from this function is MQTTCLIENT_TOPICNAME_TRUNCATED, the topic contains embedded NULL characters and the full topic should be retrieved by using topicLen. Sneaky little NULLs. 🙈
  • message — the address of a pointer to the received message. This function allocates the memory for the message and returns it to the application by setting message to point to the received message. The pointer is set to NULL if the timeout expires.
  • timeout — the length of time to wait for a message in milliseconds.

Returns

MQTTCLIENT_SUCCESS or MQTTCLIENT_TOPICNAME_TRUNCATED if a message is received. MQTTCLIENT_SUCCESS can also indicate that the timeout expired, in which case message is NULL. An error code is returned if there was a problem trying to receive a message. Yeah, MQTTCLIENT_SUCCESS doing double duty, we love a multitasker. 👑

🧹 void MQTTClient_freeMessage (MQTTClient_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 MQTTClient_free() library function. Two separate cleanups, bestie. Do them both. 🫶

Parameters

  • msg — the address of a pointer to the MQTTClient_message structure to be freed.

🗑️ void MQTTClient_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 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. Windows, you chaotic little thing. 💀

Parameters

  • ptr — the pointer to the client library storage to be freed.

🌸 void * MQTTClient_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 user persistence. This is needed on Windows when the client library and application program have been compiled with different versions of the C compiler. Same Windows situation, but make it allocation. 🪟

Parameters

  • size — the size of the memory to be allocated.

💔 void MQTTClient_destroy (MQTTClient * handle) [extern]

This function frees the memory allocated to an MQTT client (see MQTTClient_create()). It should be called when the client is no longer required. It's the breakup function. Say your goodbyes, free your handle. 😭

Parameters

  • handle — a pointer to the handle referring to the MQTTClient structure to be freed.

🔍 void MQTTClient_setTraceLevel (enum MQTTCLIENT_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 MQTTClient_setTraceCallback (MQTTClient_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. Set it to NULL and it goes fully silent, like a ghost. 👻

Parameters

  • callback — a pointer to the function which will handle the trace information

⏰ int MQTTClient_setCommandTimeout (MQTTClient handle, unsigned long milliSeconds) [extern]

Sets the timeout value for un/subscribe commands when waiting for the un/suback response from the server. Values less than 5000 are not allowed. Don't try it. The library said what it said. 🚫

Parameters

  • handle — a valid client handle from a successful call to MQTTClient_create().
  • milliSeconds — the maximum number of milliseconds to wait

Returns

MQTTCLIENT_SUCCESS or MQTTCLIENT_FAILURE

💬 const char * MQTTClient_strerror (int code) [extern]

Returns a pointer to the string representation of the error or NULL. Translation service for your error codes, so slay. 🫶

Do not free after use. Returns NULL if the error code is unknown. Do not free it. I said what I said. 💅

✨ Author ✨

Generated automatically by Doxygen for Paho MQTT C Client Library from the source code. Not a human, just Doxygen doing its little robot thing. 🤖

And that's the whole page, bestie!! 💖 This was Paho MQTT C Client Library, the MQTTClient.h(3) manual page, and it was generated on Tue Jun 2 2026 00:00:00. Go forth and publish responsibly. ✨🎀🦋

📦 where this page comes from