MQTTASYNC_CONNECTOPTIONS(3)
💖 MQTTAsync_connectOptions 💖
okay so hi bestie 🫶 you're on the MQTTAsync_connectOptions(3) page, straight out of the Library Functions Manual. this is the struct that holds every single setting for how your async MQTT client connects to a server. it's giving "character creation screen for your connection". let's get into it ✨
🌸 NAME 🌸
MQTTAsync_connectOptions — that's it, that's the name section, she's self-titled and she knows it 💅
🎀 SYNOPSIS 🎀
#include <MQTTAsync.h>🦋 Data Fields 🦋
char struct_id [4]
int struct_version
int keepAliveInterval
int cleansession
int maxInflight
MQTTAsync_willOptions * will
const char * username
const char * password
int connectTimeout
int retryInterval
MQTTAsync_SSLOptions * ssl
MQTTAsync_onSuccess * onSuccess
MQTTAsync_onFailure * onFailure
void * context
int serverURIcount
char *const * serverURIs
int MQTTVersion
int automaticReconnect
int minRetryInterval
int maxRetryInterval
struct {
int len
const void * data
} binarypwd
int cleanstart
MQTTProperties * connectProperties
MQTTProperties * willProperties
MQTTAsync_onSuccess5 * onSuccess5
MQTTAsync_onFailure5 * onFailure5
const MQTTAsync_nameValue * httpHeaders
const char * httpProxy
const char * httpsProxy✨ Detailed Description ✨
MQTTAsync_connectOptions defines several settings that control the way the client connects to an MQTT server. literally the entire connection personality of your client lives in here 🧚
the good news is you don't have to hand-craft her from scratch, because suitable default values are already set in these initializers:
MQTTAsync_connectOptions_initializer— for MQTT 3.1.1 non-WebSocketsMQTTAsync_connectOptions_initializer5— for MQTT 5.0 non-WebSocketsMQTTAsync_connectOptions_initializer_ws— for MQTT 3.1.1 WebSocketsMQTTAsync_connectOptions_initializer5_ws— for MQTT 5.0 WebSockets
pick the one that matches your protocol + transport combo and you're already slaying 👑
💅 Field Documentation 💅
🌟 char struct_id[4]
the eyecatcher for this structure. must be MQTC. no cap, she checks.
🌟 int struct_version
the version number of this structure. must be 0, 1, 2, 3 4 5 6, 7 or 8. here's what each one is telling you about what's not in there yet:
0signifies no SSL options and no serverURIs1signifies no serverURIs2signifies no MQTTVersion3signifies no automatic reconnect options4signifies no binary password option (just string)5signifies no MQTTV5 properties6signifies no HTTP headers option7signifies no HTTP proxy and HTTPS proxy options
🌟 int keepAliveInterval
the "keep alive" interval, measured in seconds — it defines the maximum time that should pass without communication between the client and the server. the client will make sure at least one message travels across the network within each keep alive period. in the absence of a data-related message during that time period, the client sends a very small MQTT "ping" message, which the server will acknowledge. this interval is what lets the client detect when the server is no longer available without having to wait for the long TCP/IP timeout. set it to 0 if you do not want any keep alive processing. 🫶
🌟 int cleansession
this is a boolean value. the cleansession setting controls the behaviour of both the client and the server at connection and disconnection time. the client and server both maintain session state information, and that info is what ensures "at least once" and "exactly once" delivery, plus "exactly once" receipt of messages. session state also includes subscriptions created by an MQTT client. you can choose to maintain or discard state information between sessions.
when cleansession is true, the state information is discarded at connect and disconnect. setting cleansession to false keeps the state information. when you connect an MQTT client application with MQTTAsync_connect(), the client identifies the connection using the client identifier and the address of the server. the server checks whether session information for this client has been saved from a previous connection to the server. if a previous session still exists, and cleansession=true, then the previous session information at the client and server is cleared. if cleansession=false, the previous session is resumed. if no previous session exists, a new session is started. periodt 💅
🌟 int maxInflight
this controls how many messages can be in-flight simultaneously. (multitasking queen but make it bounded 🦋)
🌟 MQTTAsync_willOptions* will
this is a pointer to an MQTTAsync_willOptions structure. if your application does not make use of the Last Will and Testament feature, set this pointer to NULL.
🌟 const char* username
MQTT servers that support the MQTT v3.1 protocol provide authentication and authorisation by user name and password. this is the user name parameter.
🌟 const char* password
MQTT servers that support the MQTT v3.1 protocol provide authentication and authorisation by user name and password. this is the password parameter.
🌟 int connectTimeout
the time interval in seconds to allow a connect to complete.
🌟 int retryInterval
the time interval in seconds after which unacknowledged publish requests are retried during a TCP session. with MQTT 3.1.1 and later, retries are not required except on reconnect. 0 turns off in-session retries, and is the recommended setting. adding retries to an already overloaded network only exacerbates the problem. (so like, don't 😭)
🌟 MQTTAsync_SSLOptions* ssl
this is a pointer to an MQTTAsync_SSLOptions structure. if your application does not make use of SSL, set this pointer to NULL.
🌟 MQTTAsync_onSuccess* onSuccess
a pointer to a callback function to be called if the connect successfully completes. can be set to NULL, in which case no indication of successful completion will be received.
🌟 MQTTAsync_onFailure* onFailure
a pointer to a callback function to be called if the connect fails. can be set to NULL, in which case no indication of unsuccessful completion will be received.
🌟 void* context
a pointer to any application-specific context. the context pointer is passed to success or failure callback functions to provide access to the context information in the callback. it's giving "bring your own baggage, we'll carry it for you" 🎀
🌟 int serverURIcount
the number of entries in the serverURIs array.
🌟 char* const* serverURIs
an array of null-terminated strings specifying the servers to which the client will connect. each string takes the form protocol://host:port. protocol must be tcp, ssl, tls, ws or wss. the TLS enabled prefixes (ssl, tls, 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 domain name. for instance, to connect to a server running on the local machines with the default MQTT port, specify tcp://localhost:1883. 🌈
🌟 int MQTTVersion
sets the version of MQTT to be used on the connect.
MQTTVERSION_DEFAULT(0) = default: start with 3.1.1, and if that fails, fall back to 3.1MQTTVERSION_3_1(3) = only try version 3.1MQTTVERSION_3_1_1(4) = only try version 3.1.1
🌟 int automaticReconnect
reconnect automatically in the case of a connection being lost. 0=false, 1=true. (main character energy: she comes back 💅)
🌟 int minRetryInterval
the minimum automatic reconnect retry interval in seconds. doubled on each failed retry.
🌟 int maxRetryInterval
the maximum automatic reconnect retry interval in seconds. the doubling stops here on failed retries.
🌟 int len
binary password length
🌟 const void* data
binary password data
🌟 struct { ... } binarypwd
optional binary password. only checked and used if the password option is NULL.
🌟 int cleanstart
(the page just leaves this one here with no description, iykyk 🙈)
🌟 MQTTProperties* connectProperties
MQTT V5 properties for connect
🌟 MQTTProperties* willProperties
MQTT V5 properties for the will message in the connect
🌟 MQTTAsync_onSuccess5* onSuccess5
a pointer to a callback function to be called if the connect successfully completes. can be set to NULL, in which case no indication of successful completion will be received.
🌟 MQTTAsync_onFailure5* onFailure5
a pointer to a callback function to be called if the connect fails. can be set to NULL, in which case no indication of unsuccessful completion will be received.
🌟 const MQTTAsync_nameValue* httpHeaders
HTTP headers for websockets
🌟 const char* httpProxy
the string value of the HTTP proxy. examples:
🌟 const char* httpsProxy
HTTPS proxy setting. see MQTTAsync_connectOptions.httpProxy and the section HTTP Proxies.
👑 Author 👑
Generated automatically by Doxygen for Paho Asynchronous MQTT C Client Library from the source code. (not a human, just a very efficient little robot 🧚✨)
okay that's the whole page bestie, you ate it up 💖 this lil' slice of the docs comes to you from the Paho Asynchronous MQTT C... source, dated Tue Jun 2 2026 00:00:00. go forth and connect responsibly, mwah 🫶💅🎀
📦 where this page comes from
- fedora 44: paho-c-devel 1.3.16-1.fc44 · BSD-3-Clause AND EPL-2.0
- fedora 44: paho-c-devel 1.3.16-1.fc44 · BSD-3-Clause AND EPL-2.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms