/********************************************************************************
* 版權所有 (c) 2009, 2025 IBM Corp.、Ian Craggs 及其他
*
* 保留所有權利。本程序及其隨附材料
* 根據 Eclipse 公共許可證 v2.0 的條款提供
* 以及隨附的 Eclipse 分發許可證 v1.0。
*
* Eclipse 公共許可證可在以下網址獲?。?* https://www.eclipse.org/legal/epl-2.0/
* Eclipse 分發許可證可在以下網址獲取：
* http://www.eclipse.org/org/documents/edl-v10.php。
*
* 貢獻者：
* Ian Craggs - 初始 API 和實現
* Ian Craggs、Allan Stockdill-Mander - SSL 連接
* Ian Craggs - 多服務器連接支持
* Ian Craggs - MQTT 3.1.1 支持
* Ian Craggs - 修復 bug 444103 - 未調用成功/失敗回調
* Ian Craggs - 自動重連和離線緩沖（斷開連接時發送）
* Ian Craggs - 二進制遺囑消息
* Ian Craggs - 二進制密碼
* Ian Craggs - 移除 eyecatchers 上的 const #168
* Ian Craggs - MQTT 5.0
***********************************************************************************/
////////////////////////////////////////////////////////////////////////////////////
/**
* @cond MQTTAsync_main
* @mainpage C 語言異步 MQTT 客戶端庫 (MQTTAsync)
*
* © 版權所有 2009, 2025 IBM Corp.，Ian Craggs 等。
*
* @brief C 語言異步 MQTT 客戶端庫。
*
* 版本 1.3.14
*
* MQTT 客戶端應用程序連接到支持 MQTT 的服務器。
* 典型的客戶端負責從遙測設備收集信息并將信息發布到服務器。
* 它還可以訂閱主題、接收消息并使用這些信息來控制遙測設備。
*
* MQTT 客戶端實現了已發布的 MQTT v3 協議。
* 您可以選擇編程語言和平臺編寫自己的 MQTT 協議 API，但這可能非常耗時且容易出錯。
*
* 為了簡化 MQTT 客戶端應用程序的編寫，此庫為您封裝了
* MQTT v3 協議。使用此庫，您只需幾行代碼即可編寫一個功能齊全的
* MQTT 客戶端應用程序。
* 此處提供的信息記錄了異步 MQTT 客戶端庫（適用于 C 語言）提供的 API。
*
* 使用客戶端
* 使用客戶端庫的應用程序通常使用類似的結構：
* 創建客戶端對象
* 設置連接到 MQTT 服務器的選項
* 設置回調函數
* 將客戶端連接到 MQTT 服務器
* 訂閱客戶端需要接收的任何主題
* 重復直至完成：
* 發布客戶端需要接收的任何消息
* 處理所有傳入消息
* 斷開客戶端連接
* 釋放客戶端正在使用的任何內存
* 以下顯示一些簡單示例：
* @ref publish
* @ref subscribe
* 以下是一些重要概念的補充信息：
* @ref async
* @ref wildcard
* @ref qos
* @ref tracing
* @ref auto_reconnect
* @ref offline_publish
* @ref HTTP_proxies
* @endcond
*/
//返回碼：無錯誤。表示 MQTT 客戶端操作成功完成。
#define MQTTASYNC_SUCCESS 0
//返回代碼：指示 MQTT 客戶端操作失敗的通用錯誤代碼。
#define MQTTASYNC_FAILURE -1
//錯誤代碼 -2
#define MQTTASYNC_PERSISTENCE_ERROR -2
//客戶端已斷開連接。
#define MQTTASYNC_DISCONNECTED -3
/** 返回代碼：已達到允許同時傳輸的最大消息數量。
* 已達到允許同時傳輸的最大消息數量。
*/
#define MQTTASYNC_MAX_MESSAGES_INFLIGHT -4
/**返回代碼：檢測到無效的 UTF-8 字符串。
*/
#define MQTTASYNC_BAD_UTF8_STRING -5
/**返回代碼：當該參數無效時，提供一個 NULL 參數。
*/
#define MQTTASYNC_NULL_PARAMETER -6
/**返回代碼：主題已被截斷（主題字符串包含嵌入的 NULL 字符）。字符串函數將無法訪問完整主題。
* 使用主題長度值訪問完整主題。
*/
#define MQTTASYNC_TOPICNAME_TRUNCATED -7
/**返回代碼：結構體參數缺少正確的醒目標記和版本號。
*/
#define MQTTASYNC_BAD_STRUCTURE -8
/**返回代碼：qos 參數不為 0、1 或 2
*/
#define MQTTASYNC_BAD_QOS -9
/**返回代碼：所有 65535 個 MQTT msgid 均正在使用
*/
#define MQTTASYNC_NO_MORE_MSGIDS -10
/**返回代碼：請求未完成時被丟棄
*/
#define MQTTASYNC_OPERATION_INCOMPLETE -11
/**返回代碼：無法緩沖更多消息
*/
#define MQTTASYNC_MAX_BUFFERED_MESSAGES -12
/**返回代碼：嘗試使用非 SSL 版本的庫建立 SSL 連接
*/
#define MQTTASYNC_SSL_NOT_SUPPORTED -13
/**返回代碼：serverURI 中的協議前綴應為：
* @li @em tcp:// 或 @em mqtt:// - 不安全的 TCP
* @li @em ssl:// 或 @em mqtts:// - 加密 SSL/TLS
* @li @em ws:// - 不安全的 WebSocket
* @li @em wss:// - 安全的 WebSocket
*
* 啟用 TLS 的前綴（ssl、mqtts、wss）僅在鏈接了 TLS 版本的庫時有效。
*/
#define MQTTASYNC_BAD_PROTOCOL -14
/**返回代碼：請勿使用其他版本 MQTT 的選項
*/
#define MQTTASYNC_BAD_MQTT_OPTION -15
/**返回代碼：調用不適用于客戶端的 MQTT 版本
*/
#define MQTTASYNC_WRONG_MQTT_VERSION -16
/**返回代碼：0長度將主題
*/
#define MQTTASYNC_0_LEN_WILL_TOPIC -17
/*返回代碼：連接或斷開連接命令被忽略，因為列表頭部已有一個連接或斷開連接命令正在等待處理。
* 請使用 onSuccess/onFailure 回調等待上一個連接或斷開連接命令完成。
*/
#define MQTTASYNC_COMMAND_IGNORED -18
/*返回代碼：連接選項中的 maxBufferedMessages 必須 >= 0
*/
#define MQTTASYNC_MAX_BUFFERED -19
/**默認連接的 MQTT 版本。使用 3.1.1 后可回退到 3.1
*/
#define MQTTVERSION_DEFAULT 0
/**連接的 MQTT 版本：3.1
*/
#define MQTTVERSION_3_1 3
/**
* 連接的 MQTT 版本：3.1.1
*/
#define MQTTVERSION_3_1_1 4
/**
* 連接的 MQTT 版本: 5
*/
#define MQTTVERSION_5 5
/**
* 訂閱返回的錯誤代碼，如 3.1.1 規范中所定義
*/
#define MQTT_BAD_SUBSCRIBE 0x80
/**
* 初始化選項
*/
typedef struct
{
/** 此結構的醒目部分。必須是 MQTG。*/
char struct_id[4];
/** 此結構的版本號。必須為 0 */
int struct_version;
/** 1 = 我們執行 openssl init，0 = 將其留給應用程序 */
int do_openssl_init;
} MQTTAsync_init_options;
#define MQTTAsync_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
/**MQTT 庫的全局初始化。程序啟動時調用一次即可設置全局行為。
* handle_openssl_init - MQTT 庫是否應該處理 OpenSSL 初始化 (1) 或依賴調用者在使用 MQTT 之前初始化 (0)
*/
LIBMQTT_API void MQTTAsync_global_init(MQTTAsync_init_options* inits);
/**表示 MQTT 客戶端的句柄。成功調用 MQTTAsync_create() 后，將獲得一個有效的客戶端句柄。
*
*/
typedef void* MQTTAsync;
/**
* 表示 MQTT 消息的值。消息發布后，會向
* 客戶端應用程序返回一個令牌。然后，該令牌可用于
* 檢查消息是否已成功送達目的地（參見
* MQTTAsync_publish()、MQTTAsync_publishMessage()、
* MQTTAsync_deliveryComplete() 和 MQTTAsync_getPendingTokens()）
*/
typedef int MQTTAsync_token;
/**表示 MQTT 消息的有效負載和屬性的結構體。
* 消息主題不屬于此結構體（請參閱 MQTTAsync_publishMessage()、
* MQTTAsync_publish()、MQTTAsync_receive()、MQTTAsync_freeMessage()
* 和 MQTTAsync_messageArrived()）。
*/
typedef struct
{
/** 這個結構的亮點一定是 MQTM。 */
char struct_id[4];
/** 此結構的版本號。必須為 0 或 1。
* 0 表示沒有消息屬性 */
int struct_version;
/** MQTT 消息有效負載的長度（以字節為單位）。 */
int payloadlen;
/** 指向 MQTT 消息有效負載的指針。 */
void* payload;
/**
* 分配給消息的服務質量 (QoS)。
* QoS 分為三個級別：
* QoS0 “發射后不管” - 消息可能不會被投遞
* QoS1 “至少一次” - 消息將被投遞，但在某些情況下可能會被投遞多次。
* QoS2 “一次且僅一次” - 消息只會被投遞一次.
*/
int qos;
/**
* Retained 標志有兩個用途，具體取決于與其關聯的消息是正在發布還是正在接收。
*
* <b>retained = true</b><br>
* 對于正在發布的消息，設置為 true 表示 MQTT 服務器應保留該消息的副本。然后，該消息將傳輸給與該消息主題匹配的新訂閱者。
* 對于注冊新訂閱的訂閱者，該標志為 true 表示收到的消息不是新消息，而是已被 MQTT 服務器保留的消息。
*
* <b>retained = false</b> <br>
* 對于發布者，這表示該消息不應被 MQTT 服務器保留。
* 對于訂閱者，設置為 false 表示這是一條普通消息，由于已發布到服務器而收到。
*/
int retained;
/**
* dup 標志指示此消息是否重復。
* 該標志僅在接收 QoS1 消息時才有意義。當該標志為 true 時，
* 客戶端應用程序應采取適當的措施來處理重復消息。這僅是一個輸出參數。
*/
int dup;
/** 消息標識符保留供
* MQTT 客戶端和服務器內部使用。它只是一個輸出參數 - 寫入
* 它將毫無意義。它包含傳入發布消息的 MQTT 消息 ID。
*/
int msgid;
/**
* 與消息相關的 MQTT V5 屬性。
*/
MQTTProperties properties;
} MQTTAsync_message;
#define MQTTAsync_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer }
/**這是一個回調函數?？蛻舳藨贸绦虮仨毺峁┐撕瘮档膶崿F才能啟用異步消息接收。
* 該函數通過將其作為參數傳遞給 MQTTAsync_setCallbacks() 來注冊到客戶端庫。
* 當從服務器收到與客戶端訂閱匹配的新消息時，客戶端庫會調用此函數。
* 此函數在與客戶端應用程序正在運行的線程不同的線程上執行。
*
* 注意：不應在此回調中調用 MQTTAsync_create() 和 MQTTAsync_destroy()。
* @param context 指向最初傳遞給 MQTTAsync_setCallbacks() 的 context 值的指針，該值包含任何特定于應用程序的上下文。
* @param topicName 與接收消息關聯的主題。
* @param topicLen 如果 topicName 中嵌入了一個或多個 NULL 字符，則為主題的長度；否則為 topicLen。
* 如果 topicLen 為 0，則 strlen(topicName) 返回的值是可信的。
* 如果 topicLen 大于 0，則可以通過訪問長度為 topicLen 的字節數組來檢索完整的主題名稱。
* @param message 接收消息的 MQTTAsync_message 結構。
* 此結構包含消息有效負載和屬性。
* @return 此函數必須返回 0 或 1，以指示消息是否已被客戶端應用程序安全接收。
* 返回 1 表示消息已成功處理。
* 要釋放消息存儲空間，必須調用 ::MQTTAsync_freeMessage。
* 要釋放主題名稱存儲空間，必須調用 ::MQTTAsync_free。
* 返回 0 表示出現問題。在這種情況下，
* 客戶端庫將重新調用 MQTTAsync_messageArrived() 來嘗試再次將消息傳遞給應用程序。
* 返回 0 時請勿釋放消息和主題存儲空間，否則重新傳遞將失敗。
*/
typedef int MQTTAsync_messageArrived(void* context, char* topicName, int topicLen, MQTTAsync_message* message);
/** 這是一個回調函數。客戶端應用程序必須提供此函數的實現，才能啟用異步消息傳遞到服務器的通知。
* 該函數通過將它作為參數傳遞給 MQTTAsync_setCallbacks() 來注冊到客戶端庫。
* 客戶端應用程序向服務器發布消息后，客戶端庫會調用此函數。
* 它指示已完成所需握手和確認（針對所請求的服務質量，請參閱
* MQTTAsync_message.qos）。此函數在與客戶端應用程序運行的線程不同的線程上執行。
*
* 注意：不應在此回調中調用 MQTTAsync_create() 和 MQTTAsync_destroy()。
* @param context 指向最初傳遞給 MQTTAsync_setCallbacks() 的 context 值的指針，該值包含任何特定于應用程序的上下文。
* @param token 與已發布消息關聯的 ::MQTTAsync_token。應用程序可以通過將調用
* MQTTAsync_send() 和 MQTTAsync_sendMessage() 返回的令牌與傳遞給此回調的令牌進行匹配，來檢查所有消息是否已正確發布。
*/
typedef void MQTTAsync_deliveryComplete(void* context, MQTTAsync_token token);
/**
* 這是一個回調函數?？蛻舳藨贸绦虮仨毺峁┐撕瘮档膶崿F，以啟用異步通知與服務器的連接斷開。
* 此函數通過將函數作為參數傳遞給MQTTAsync_setCallbacks() 來注冊到客戶端庫。
* 如果客戶端斷開與服務器的連接，客戶端庫會調用此函數?？蛻舳藨贸绦虮仨毑扇∵m當的措施，
* 例如嘗試重新連接或報告問題。
* 此函數在與客戶端應用程序運行的線程不同的線程上執行。
*
* 注意： 不應在此回調中調用 MQTTAsync_create() 和 MQTTAsync_destroy()。
* @param context 指向最初傳遞給 MQTTAsync_setCallbacks() 的 context 值的指針，該值包含任何特定于應用程序的上下文。
* @param cause 斷開連接的原因。目前，cause 始終設置為 NULL。
*/
typedef void MQTTAsync_connectionLost(void* context, char* cause);
/**
* 這是一個回調函數，當客戶端庫成功連接時將被調用。* 如果連接是響應 MQTTAsync_connect 調用而建立的，則無需調用此函數，
* 因為 onSuccess 回調函數已啟用。此函數旨在用于啟用自動重新連接時，以便當后臺重新連接嘗試成功時，應用程序將收到通知并可以執行任何必要的操作。
*
* 注意： 不應在此回調中調用 MQTTAsync_create() 和 MQTTAsync_destroy()。
* @param context 指向最初傳遞給 MQTTAsync_setCallbacks() 的 context 值的指針，該值包含任何特定于應用程序的上下文。
* @param cause 斷開連接的原因。目前，cause 始終設置為 NULL。
*/
typedef void MQTTAsync_connected(void* context, char* cause);
/**
* 這是一個回調函數，當客戶端庫接收到來自服務器的斷開連接數據包時，該函數將被調用。這僅適用于 MQTT V5 及更高版本。
*
* 注意： MQTTAsync_create() 和 MQTTAsync_destroy() 都不應在此回調中調用。
* @param context 指向最初傳遞給 MQTTAsync_setCallbacks() 的 context 值的指針，該值包含任何特定于應用程序的上下文。
* @param properties 斷開連接數據包中的屬性。
* @param reasonCode 斷開連接數據包的原因代碼。
*/
typedef void MQTTAsync_disconnected(void* context, MQTTProperties* properties, enum MQTTReasonCodes reasonCode);
/**
* 為客戶端設置 MQTTAsync_disconnected() 回調函數。
* @param handle 成功調用 MQTTAsync_create() 后返回的有效客戶端句柄。
*
* 注意：不應在此回調函數中調用 MQTTAsync_create() 和 MQTTAsync_destroy()。
* @param context 指向任何特定于應用程序的上下文的指針。context 指針將傳遞給每個回調函數，
* 以提供對回調函數中上下文信息的訪問。
* @param co 指向 MQTTAsync_connected() 回調函數的指針。NULL 表示刪除回調設置。
* @return ::MQTTASYNC_SUCCESS（如果回調設置正確）；::MQTTASYNC_FAILURE（如果發生錯誤）。
*/
LIBMQTT_API int MQTTAsync_setDisconnected(MQTTAsync handle, void* context, MQTTAsync_disconnected* co);
/** 自動重新連接之前可以更新的連接選項。 */
typedef struct
{
/** 這個結構的亮點是 MQCD。 */
char struct_id[4];
/** 此結構的版本號。將為 0 */
int struct_version;
/**支持 MQTT v3.1 協議的 MQTT 服務器提供身份驗證和通過用戶名和密碼授權的功能。這是用戶名參數。
* 將 data 設置為 NULL 即可刪除。如需更改，請使用 ::MQTTAsync_allocate 分配新的
* 存儲空間 - 該存儲空間稍后將由庫釋放。
*/
const char* username;
/**MQTT 身份驗證的密碼參數。將 data 設置為 NULL 即可刪除。
* 如需更改，請使用 ::MQTTAsync_allocate 分配新的存儲空間 - 該存儲空間稍后將由庫釋放。
*/
struct {
int len; /**< binary password length */
const void* data; /**< binary password data */
} binarypwd;
} MQTTAsync_connectData;
#define MQTTAsync_connectData_initializer {{'M', 'Q', 'C', 'D'}, 0, NULL, {0, NULL}}
/**這是一個回調函數，允許客戶端應用程序更新連接數據。
* @param data 可由應用程序修改的連接數據。
* @return 返回非零值以更新連接數據，返回零則保持數據不變。
*/
typedef int MQTTAsync_updateConnectOptions(void* context, MQTTAsync_connectData* data);
/**
* 為客戶端設置 MQTTAsync_updateConnectOptions() 回調函數。
* @param handle 成功調用 MQTTAsync_create() 后的有效客戶端句柄。
* @param context 指向任何特定于應用程序的上下文的指針。context指針將傳遞給每個回調函數，以
* 提供對回調中上下文信息的訪問。
* @param co 指向 MQTTAsync_updateConnectOptions() 回調函數的指針。NULL 表示刪除回調設置。
*/
LIBMQTT_API int MQTTAsync_setUpdateConnectOptions(MQTTAsync handle, void* context, MQTTAsync_updateConnectOptions* co);
/**為客戶端設置 MQTTPersistence_beforeWrite() 回調函數。
* @param handle 成功調用 MQTTAsync_create() 后的有效客戶端句柄。
* @param context 指向任何特定于應用程序的上下文的指針。context 指針將傳遞給回調函數，以便在回調中訪問上下文信息。
* @param co 指向 MQTTPersistence_beforeWrite() 回調函數的指針。NULL 表示刪除回調設置。
*/
LIBMQTT_API int MQTTAsync_setBeforePersistenceWrite(MQTTAsync handle, void* context, MQTTPersistence_beforeWrite* co);
/**為客戶端設置 MQTTPersistence_afterRead() 回調函數。
* @param handle 成功調用 MQTTAsync_create() 后的有效客戶端句柄。
* @param context 指向任何特定于應用程序的上下文的指針。context 指針將傳遞給回調函數，以便在回調中訪問上下文信息。
* @param co 指向 MQTTPersistence_beforeWrite() 回調函數的指針。NULL 表示刪除回調設置。
*/
LIBMQTT_API int MQTTAsync_setAfterPersistenceRead(MQTTAsync handle, void* context, MQTTPersistence_afterRead* co);
/** 在響應回調 onFailure 中，API 調用失敗后返回的數據。 */
typedef struct{
/** 標識失敗請求的令牌. */
MQTTAsync_token token;
/** 標識錯誤的數字代碼. */
int code;
/** 可選文本，用于解釋錯誤?？梢詾?NULL. */
const char *message;
} MQTTAsync_failureData;
/** 在響應回調 onFailure 中，API 調用失敗后返回的數據。*/
typedef struct
{
/** 此結構最引人注目之處。將是 MQFD。 */
char struct_id[4];
/** 此結構的版本號。將為 0 */
int struct_version;
/** 標識失敗請求的令牌。*/
MQTTAsync_token token;
/** 返回的 MQTT 原因代碼。 */
enum MQTTReasonCodes reasonCode;
/** 確認上的 MQTT 屬性（如果有）。 */
MQTTProperties properties;
/** 標識 MQTT 客戶端庫錯誤的數字代碼。 */
int code;
/** 可選的進一步解釋錯誤的文本。可以為 NULL。 */
const char *message;
/** 發生故障的數據包類型 - 用于發布 QoS 1/2 交換 */
int packet_type;
} MQTTAsync_failureData5;
#define MQTTAsync_failureData5_initializer {{'M', 'Q', 'F', 'D'}, 0, 0, MQTTREASONCODE_SUCCESS, MQTTProperties_initializer, 0, NULL, 0}
/** 在響應回調 onSuccess 中，成功完成 API 調用后返回的數據。*/
typedef struct
{
/** 標識成功請求的令牌?？捎糜谏院笠迷撜埱?。*/
MQTTAsync_token token;
/** subscribe、unsubscribe 和 publish 操作可返回的不同值的聯合體。*/
union
{
/** 對于 subscribe，服務器返回的訂閱的授權 QoS。
* 如果只請求了一個訂閱，則對于 subscribeMany 操作也是如此。*/
int qos;
/** 對于 subscribeMany，如果請求了多個訂閱，服務器返回的訂閱的授權 QoS 列表。*/
int* qosList;
/** 對于 publish，發送至服務器的消息。*/
struct
{
MQTTAsync_message message; /**< 發送至服務器的消息 */
char* destinationName; /**< 消息的主題目標 */
} pub;
/* 對于 connect，連接到的服務器、使用的 MQTT 版本以及 sessionPresent 標志 */
struct
{
char* serverURI; /**< 服務器的連接字符串 */
int MQTTVersion; /**< 正在使用的 MQTT 版本 */
int sessionPresent; /**< 從服務器返回的會話存在標志 */
} connect;
} alt;
} MQTTAsync_successData;
/** 在響應回調 onSuccess 中，成功完成 API 調用后返回的數據。*/
typedef struct
{
char struct_id[4]; /**< 此結構的醒目部分。將為 MQSD。*/
int struct_version; /**< 此結構的版本號。將為 0 */
/** 標識成功請求的令牌。可用于稍后引用該請求。*/
MQTTAsync_token token;
enum MQTTReasonCodes reasonCode; /**< 返回的 MQTT V5 原因代碼 */
MQTTProperties properties; /**< 返回的 MQTT V5 屬性（如果有）*/
/** 可以為訂閱、取消訂閱和發布返回的不同值的聯合。*/
union
{
/** 對于 subscribeMany，為服務器返回的 reasonCodes 列表。*/
struct
{
int reasonCodeCount; /**< reasonCodes 數組中的原因代碼數量 */
enum MQTTReasonCodes* reasonCodes; /**< 一個 reasonCodes 數組 */
} sub;
/** 對于發布，為發送到服務器的消息。 */
struct
{
MQTTAsync_message message; /**< 正在發送到服務器的消息 */
char* destinationName; /**< 消息的主題目標 */
} pub;
/* 對于 connect，返回連接到的服務器、使用的 MQTT 版本以及 sessionPresent 標志 */
struct
{
char* serverURI; /**< 服務器的連接字符串 */
int MQTTVersion; /**< 正在使用的 MQTT 版本 */
int sessionPresent; /**< 服務器返回的 session present 標志 */
} connect;
/** 對于 unsubscribeMany，返回服務器返回的 reasonCodes 列表。 */
struct
{
int reasonCodeCount; /**< reasonCodes 數組中的原因代碼數量 */
enum MQTTReasonCodes* reasonCodes; /**< reasonCodes 數組 */
} unsub;
} alt;
} MQTTAsync_successData5;
#define MQTTAsync_successData5_initializer {{'M', 'Q', 'S', 'D'}, 0, 0, MQTTREASONCODE_SUCCESS, MQTTProperties_initializer, {.sub={0,0}}}
/**
* 這是一個回調函數?？蛻舳藨?* 必須提供此函數的實現，才能啟用異步
* API 調用成功完成的通知。此函數
* 通過將參數傳遞給
* ::MQTTAsync_responseOptions 來注冊到客戶端庫。
*
* <b>注意：</b> 不應在此回調中調用 MQTTAsync_create() 和 MQTTAsync_destroy()。
* @param context 指向最初傳遞給
* ::MQTTAsync_responseOptions 的 <i>context</i> 值的指針，其中包含任何特定于應用的上下文。
* @param respond 與 API 完成相關的任何成功數據。
*/
typedef void MQTTAsync_onSuccess(void* context, MQTTAsync_successData* response);
/**
* 這是一個回調函數，是 MQTT V5 版本的 ::MQTTAsync_onSuccess。
* 客戶端應用程序
* 必須提供此函數的實現，才能啟用異步
* API 調用成功完成的通知。此函數
* 通過將它作為參數傳遞給
* ::MQTTAsync_responseOptions 來注冊到客戶端庫。
*
* <b>注意：</b> 不應在此回調中調用 MQTTAsync_create() 和 MQTTAsync_destroy()。
* @param context 指向最初傳遞給
* ::MQTTAsync_responseOptions 的 <i>context</i> 值的指針，其中包含任何特定于應用程序的上下文。
* @param respond 任何與 API 完成相關的成功數據。
*/
typedef void MQTTAsync_onSuccess5(void* context, MQTTAsync_successData5* response);
/**
* 這是一個回調函數?？蛻舳藨?* 必須提供此函數的實現，才能啟用異步
* API 調用失敗通知。此函數
* 通過將參數傳遞給
* ::MQTTAsync_responseOptions 來注冊到客戶端庫。
*
* <b>注意：</b> 不應在此回調中調用 MQTTAsync_create() 和 MQTTAsync_destroy()。
* @param context 指向最初傳遞給
* ::MQTTAsync_responseOptions 的 <i>context</i> 值的指針，該值包含任何特定于應用的上下文。
* @param respond 與 API 完成相關的失敗數據。
*/
typedef void MQTTAsync_onFailure(void* context, MQTTAsync_failureData* response);
/**
* 這是一個回調函數，是 MQTT V5 版本的 ::MQTTAsync_onFailure。
* 應用程序必須提供此函數的實現，才能啟用異步
* API 調用失敗通知。此函數
* 通過將它作為參數傳遞給
* ::MQTTAsync_responseOptions 來注冊到客戶端庫。
*
* <b>注意：</b> 不應在此回調中調用 MQTTAsync_create() 和 MQTTAsync_destroy()。
* @param context 指向最初傳遞給
* ::MQTTAsync_responseOptions 的 <i>context</i> 值的指針，該值包含任何特定于應用程序的上下文。
* @param respond 與 API 完成相關的失敗數據。
*/
typedef void MQTTAsync_onFailure5(void* context, MQTTAsync_failureData5* response);
/** 用于定義調用選項的結構。對于 MQTT 5.0，除了描述響應方法的數據外，還包含輸入數據。
* 因此，現在還有一個同義詞 ::MQTTAsync_callOptions，以更好地反映其用途。保留此“responseOptions”名稱是為了向后兼容。
*
typedef struct MQTTAsync_responseOptions
{
/** 此結構的醒目部分。必須是 MQTR */
char struct_id[4];
/** 此結構的版本號。必須為 0 或 1
* 如果為 0，則表示無 MQTTV5 選項 */
int struct_version;
/**
* 指向回調函數的指針，當 API 調用成功完成時，該函數將被調用。
* 可以設置為 NULL，在這種情況下，將不會收到任何成功完成的指示。
*/
MQTTAsync_onSuccess* onSuccess;
/**
* 指向 API 調用失敗時要調用的回調函數的指針。
* 可以設置為 NULL，在這種情況下，不會收到任何失敗的指示。
* 完成。
*/
MQTTAsync_onFailure* onFailure;
/**
* 指向任何特定于應用程序的上下文的指針。
* <i>context</i> 指針將傳遞給成功或失敗回調函數，以
* 提供對回調中上下文信息的訪問。
*/
void* context;
/**
* 調用會返回一個令牌。它可用于跟蹤
* 此請求的狀態，無論是在回調中還是在將來的調用中
* 例如 ::MQTTAsync_waitForCompletion。這僅作為輸出 - 應用程序的任何
* 更改都將被忽略。
*/
MQTTAsync_token token;
/**
* 指向回調函數的指針，當 API 調用成功完成時，該函數將被調用。
* 可以設置為 NULL，在這種情況下，將不會收到任何成功完成的指示。
*/
MQTTAsync_onSuccess5* onSuccess5;
/**
* 指向回調函數的指針，當 API 調用成功完成時，該函數將被調用。
* 可以設置為 NULL，在這種情況下，將不會收到任何成功完成的指示。
*/
MQTTAsync_onFailure5* onFailure5;
/** MQTT V5 輸入屬性*/
MQTTProperties properties;
/** MQTT V5 訂閱選項，僅與訂閱一起使用時。*/
MQTTSubscribe_options subscribeOptions;
/** MQTT V5 訂閱選項計數，僅與 subscribeMany 一起使用時。
* subscribe_options_list 數組中的條目數。
*/
int subscribeOptionsCount;
/** MQTT V5 訂閱選項數組，僅與 subscribeMany 一起使用時。
*/
MQTTSubscribe_options* subscribeOptionsList;
} MQTTAsync_responseOptions;
#define MQTTAsync_responseOptions_initializer { {'M', 'Q', 'T', 'R'}, 1, NULL, NULL, 0, 0, NULL, NULL, MQTTProperties_initializer, MQTTSubscribe_options_initializer, 0, NULL}
/** 自 MQTT 5.0 以來，responseOptions 的同義詞，以更好地反映其用法 */
typedef struct MQTTAsync_responseOptions MQTTAsync_callOptions;
#define MQTTAsync_callOptions_initializer MQTTAsync_responseOptions_initializer
/**
* 此函數為特定客戶端設置全局回調函數。
* 如果您的客戶端應用程序未使用特定回調函數，請將
* 相關參數設置為 NULL（消息到達參數除外，該參數必須指定）。
* 任何必要的消息確認和狀態通信都將在后臺處理，
* 無需客戶端應用程序干預。
*
* <b>注意：</b> 調用此函數時，MQTT 客戶端必須斷開連接。
* @param handle 成功調用 MQTTAsync_create() 后的有效客戶端句柄。
* @param context 指向任何特定于應用程序的上下文的指針。
* <i>context</i> 指針將傳遞給每個回調函數，以
* 提供對回調中上下文信息的訪問。
* @param cl 指向 MQTTAsync_connectionLost() 回調函數的指針。
* 如果您的應用程序不處理連接斷開，可以將其設置為 NULL。
* * @param ma 指向 MQTTAsync_messageArrived() 回調函數的指針。
* 如果未設置此回調，則會返回錯誤。
* 您必須設置此回調，否則將無法傳遞任何傳入消息。
* @param dc 指向 MQTTAsync_deliveryComplete() 回調函數的指針。
* 如果您不想檢查是否成功傳遞，可以將其設置為 NULL。
* @return ::MQTTASYNC_SUCCESS（如果回調設置正確）
* ::MQTTASYNC_FAILURE（如果發生錯誤）。
*/
LIBMQTT_API int MQTTAsync_setCallbacks(MQTTAsync handle, void* context, MQTTAsync_connectionLost* cl, MQTTAsync_messageArrived* ma, MQTTAsync_deliveryComplete* dc);
/**
* 此函數為特定客戶端設置連接丟失事件的回調函數。任何必要的消息確認和狀態通信均在后臺處理，無需客戶端應用程序干預。
*
* <b>注意：</b> 調用此函數時，MQTT 客戶端必須斷開連接。
* @param handle 成功調用 MQTTAsync_create() 后返回的有效客戶端句柄。
* @param context 指向任何特定于應用程序的上下文的指針。
* <i>context</i> 指針將傳遞給回調函數，以便在回調中訪問上下文信息。
* @param cl 指向 MQTTAsync_connectionLost() 回調函數的指針。
* 如果您的應用程序不處理連接斷開，可以將其設置為 NULL。
* @return ::MQTTASYNC_SUCCESS（如果回調設置正確）;
* ::MQTTASYNC_FAILURE（如果發生錯誤）。
*/
LIBMQTT_API int MQTTAsync_setConnectionLostCallback(MQTTAsync handle, void* context,
MQTTAsync_connectionLost* cl);
/**
* 此函數為特定客戶端設置消息到達事件的回調函數。任何必要的消息確認和狀態通信均在后臺處理，無需客戶端應用程序干預。如果您未設置 messageArrived 回調函數，則不會收到任何訂閱消息的通知。
*
* <b>注意：</b> 調用此函數時，MQTT 客戶端必須斷開連接。
* @param handle 成功調用 MQTTAsync_create() 后返回的有效客戶端句柄。
* @param context 指向任何特定于應用程序的上下文的指針。<i>context</i> 指針將傳遞給回調函數，以便訪問回調中的上下文信息。
* @param ma 指向 MQTTAsync_messageArrived() 回調函數的指針。
* 如果您的應用程序不處理消息接收，可以將其設置為 NULL。
* * @return ::MQTTASYNC_SUCCESS（如果回調設置正確）;
* ::MQTTASYNC_FAILURE（如果發生錯誤）。
*/
LIBMQTT_API int MQTTAsync_setMessageArrivedCallback(MQTTAsync handle, void* context, MQTTAsync_messageArrived* ma);
/**
* 此函數為特定客戶端設置投遞完成事件的回調函數。
* 任何必要的消息確認和狀態
* 通信均在后臺處理，無需客戶端應用程序干預。
*
* <b>注意：</b> 調用此函數時，MQTT 客戶端必須斷開連接。
*
* @param handle 成功調用 MQTTAsync_create() 后返回的有效客戶端句柄。
* @param context 指向任何特定于應用程序的上下文的指針。 <i>context</i> 指針將傳遞給回調函數，以便
* 訪問回調中的上下文信息。
* @param dc 指向 MQTTAsync_deliveryComplete() 回調函數的指針。
* 如果您不想檢查是否成功交付，可以將其設置為 NULL。
* @return ::MQTTASYNC_SUCCESS（如果回調設置正確）
* ::MQTTASYNC_FAILURE（如果發生錯誤）。
*/
LIBMQTT_API int MQTTAsync_setDeliveryCompleteCallback(MQTTAsync handle, void* context, MQTTAsync_deliveryComplete* dc);
/**
* 為客戶端設置 MQTTAsync_connected() 回調函數。
* @param handle 成功調用 MQTTAsync_create() 后返回的有效客戶端句柄。
* @param context 指向任何特定于應用程序的上下文的指針。
* <i>context</i> 指針將傳遞給每個回調函數，以便
* 在回調中提供對上下文信息的訪問。
* @param co 指向 MQTTAsync_connected() 回調函數的指針。NULL 表示刪除回調設置。
* @return ::MQTTASYNC_SUCCESS（如果回調設置正確）；
* ::MQTTASYNC_FAILURE（如果發生錯誤）。
*/
LIBMQTT_API int MQTTAsync_setConnected(MQTTAsync handle, void* context, MQTTAsync_connected* co);
/**
* 使用之前使用的連接選項重新連接客戶端。連接
* 必須先前調用過才能正常工作。
* @param handle 成功調用
* MQTTAsync_create() 后的有效客戶端句柄。
* @return ::MQTTASYNC_SUCCESS（如果回調設置正確）
* ::MQTTASYNC_FAILURE（如果發生錯誤）。
*/
LIBMQTT_API int MQTTAsync_reconnect(MQTTAsync handle);
/** 需要名稱/值對的實用程序結構 */
typedef struct
{
const char* name; /**< name string */
const char* value; /**< value string */
} MQTTAsync_nameValue;
/**
* MQTTAsync_connectOptions 定義了幾個設置，用于控制客戶端連接到 MQTT 服務器的方式。
*
* 以下初始化器中設置了合適的默認值：
* - MQTTAsync_connectOptions_initializer：適用于 MQTT 3.1.1 非 WebSocket 協議
* - MQTTAsync_connectOptions_initializer5：適用于 MQTT 5.0 非 WebSocket 協議
* - MQTTAsync_connectOptions_initializer_ws：適用于 MQTT 3.1.1 WebSocket 協議
* - MQTTAsync_connectOptions_initializer5_ws：適用于 MQTT 5.0 WebSocket 協議
*/
typedef struct
{
/** 這個結構的顯著特征,必須是MQTC */
char struct_id[4];
/** 此結構的版本號。必須為 0,1,2,3,4,5,6,7,8.
* 0 表示沒有 SSL options 并且沒有 serverURIs
* 1 表示沒有 serverURIs
* 2 表示沒有 MQTTVersion
* 3 表示沒有 automatic reconnect options(自動重連選項)
* 4 表示沒有 binary password option (just string)
* 5 表示沒有 MQTTV5 properties
* 6 表示沒有 HTTP headers option
* 7 表示沒有 HTTP proxy and HTTPS proxy options
*/
int struct_version;
/** “保持連接”間隔（以秒為單位）定義了客戶端和服務器之間應保持無通信的最長時間。
* 客戶端將確保在每個保持連接周期內至少有一條消息在網絡中傳輸。
* 如果在該周期內沒有數據相關的消息，客戶端將發送一個非常小的 MQTT“ping”消息，
* 服務器將確認該消息。保持連接間隔使客戶端能夠檢測到服務器何時不再可用，
* 而無需等待漫長的 TCP/IP 超時。如果您不想進行任何保持連接處理，請設置為 0。
*/
int keepAliveInterval;
/**
* 這是一個布爾值。cleansession 設置控制客戶端和服務器在連接和斷開連接時的行為。
* 客戶端和服務器都維護會話狀態信息。此信息用于確保消息的“至少一次”和“恰好一次”傳遞，
* 以及“恰好一次”接收。會話狀態還包含 MQTT 客戶端創建的訂閱。您可以選擇在會話之間維護或丟棄狀態信息。
*
* 當 cleansession 為 true 時，狀態信息會在連接和斷開連接時被丟棄。將 cleansession 設置為 false 可保留狀態信息。
* 當您使用 MQTT 客戶端應用程序連接時，客戶端會使用客戶端標識符和服務器地址來識別連接。
* 服務器會檢查此客戶端的會話信息是否已從先前與服務器的連接中保存。如果先前的會話仍然存在，并且 cleansession=true，
* 則客戶端和服務器上的先前會話信息將被清除。如果 cleansession=false，
* 則恢復之前的會話。如果之前的會話不存在，則啟動一個新的會話。
*/
int cleansession;
/**
* 這控制著可以同時傳輸的消息數量。
*/
int maxInflight;
/**
* 這是一個指向 MQTTAsync_willOptions 結構的指針。如果您的
* 應用程序不使用“遺囑”功能，請將此指針設置為 NULL。
*/
MQTTAsync_willOptions* will;
/**
* 支持 MQTT v3.1 協議的 MQTT 服務器提供身份驗證
* 和通過用戶名和密碼授權的功能。這是用戶名參數。
*/
const char* username;
/**
* 支持 MQTT v3.1 協議的 MQTT 服務器提供身份驗證
* 和通過用戶名和密碼授權的功能。這是密碼參數。
*/
const char* password;
/**
* 允許連接完成的時間間隔（以秒為單位）。
*/
int connectTimeout;
/**
* TCP 會話期間，未確認的發布請求將在此時間間隔（以秒為單位）后重試。
* 對于 MQTT 3.1.1 及更高版本，除重新連接外，無需重試。
* 0 會關閉會話內重試，并且是推薦的設置。在已經過載的網絡中增加重試只會加劇問題。
*/
int retryInterval;
/**
* 這是一個指向 MQTTAsync_SSLOptions 結構的指針。如果您的應用程序不使用 SSL，請將此指針設置為 NULL。
*/
MQTTAsync_SSLOptions* ssl;
/**
* 指向連接成功完成時要調用的回調函數的指針。
* 可以設置為 NULL，在這種情況下將不會收到任何成功完成的指示。
*/
MQTTAsync_onSuccess* onSuccess;
/**
* 指向連接失敗時要調用的回調函數的指針。
* 可以設置為 NULL，在這種情況下，不會收到任何失敗的指示。
*/
MQTTAsync_onFailure* onFailure;
/**
* 指向任何特定于應用程序的上下文的指針。
* <i>context</i> 指針將傳遞給成功或失敗回調函數，以
* 提供對回調中上下文信息的訪問。
*/
void* context;
/**
* serverURIs 數組中的條目數。
*/
int serverURIcount;
/**
* 一個以空字符結尾的字符串數組，用于指定客戶端將連接到的服務器。
* 每個字符串的格式為 <i>protocol://host:port</i>。
* <i>protocol</i> 必須是 <i>tcp</i>、<i>ssl</i>、<i>ws</i> 或 <i>wss</i>。
* 啟用 TLS 的前綴 (ssl、wss) 僅在鏈接了 TLS 版本的庫時有效。
* 對于 <i>host</i>，您可以指定 IP 地址或域名。例如，要連接到
* 在本地計算機上使用默認 MQTT 端口運行的服務器，請指定 <i>tcp://localhost:1883</i>。
*/
char* const* serverURIs;
/**
* 設置連接時使用的 MQTT 版本。
* MQTTVERSION_DEFAULT (0) = 默認：從 3.1.1 開始，如果失敗，則回退到 3.1
* MQTTVERSION_3_1 (3) = 僅嘗試 3.1 版本
* MQTTVERSION_3_1_1 (4) = 僅嘗試 3.1.1 版本
*/
int MQTTVersion;
/**
* 連接丟失時自動重新連接。0=false，1=true
*/
int automaticReconnect;
/**
* 自動重新連接的最小重試間隔（以秒為單位）。每次重試失敗時，間隔加倍。
*/
int minRetryInterval;
/**
* 自動重新連接的最大重試間隔（以秒為單位）。重試失敗后，加倍將在此停止。
*/
int maxRetryInterval;
/**
* 可選二進制密碼。僅當密碼選項為 NULL 時才檢查并使用。
*/
struct {
int len; /**< binary password length */
const void* data; /**< binary password data */
} binarypwd;
/*
* MQTT V5 清理啟動標志。僅在會話開始時清除狀態。
*/
int cleanstart;
/**
* MQTT V5 連接屬性
*/
MQTTProperties *connectProperties;
/**
* MQTT V5 中連接中遺囑消息的屬性
*/
MQTTProperties *willProperties;
/**
* 指向連接成功完成時要調用的回調函數的指針。
* 可以設置為 NULL，在這種情況下將不會收到任何成功完成的指示。
*/
MQTTAsync_onSuccess5* onSuccess5;
/**
* 指向連接失敗時要調用的回調函數的指針。
* 可以設置為 NULL，在這種情況下，不會收到任何失敗的指示。
*/
MQTTAsync_onFailure5* onFailure5;
/**
* WebSocket 的 HTTP 標頭
*/
const MQTTAsync_nameValue* httpHeaders;
/**
* HTTP 代理的字符串值。示例：
* - http://your.proxy.server:8080/
* - http://user:pass@my.proxy.server:8080/
*/
const char* httpProxy;
/**
* HTTPS 代理設置。請參閱 ::MQTTAsync_connectOptions.httpProxy 和 @ref HTTP_proxies 部分。
*/
const char* httpsProxy;
} MQTTAsync_connectOptions;
/** MQTT 3.1.1 非 WebSocket 連接的連接選項初始化程序 */
#define MQTTAsync_connectOptions_initializer { {'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}
/** MQTT 5.0 非 WebSocket 連接的連接選項初始化程序 */
#define MQTTAsync_connectOptions_initializer5 { {'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}
/** MQTT 3.1.1 WebSockets 連接選項的初始化程序。
* 保持連接間隔設置為 45 秒，以避免 Web 服務器 60 秒不活動超時。
*/
#define MQTTAsync_connectOptions_initializer_ws { {'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}
/** MQTT 5.0 WebSockets 連接選項的初始化程序。
* 保持連接間隔設置為 45 秒，以避免 Web 服務器 60 秒不活動超時。
*/
#define MQTTAsync_connectOptions_initializer5_ws { {'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}
/**MQTTAsync_willOptions 定義了客戶端的 MQTT“遺囑”(LWT) 設置。
* 如果客戶端意外斷開與服務器的連接，
* 服務器將代表客戶端將 LWT 消息發布到 LWT 主題。
* 這樣，其他客戶端（訂閱了 LWT 主題）
* 就可以知道該客戶端已斷開連接。要為特定客戶端啟用 LWT
* 功能，需要在 MQTTAsync_connectOptions 結構體中傳遞一個指向 MQTTAsync_willOptions 結構體的有效指針，
* 該結構體用于將客戶端連接到服務器的
* MQTTAsync_connect() 調用。如果 LWT 函數不是必需的，則可以將指向 MQTTAsync_willOptions 結構的指針設置為 NULL。
*/
typedef struct
{
/** 此結構的 eyecatcher 必須是 MQTW. */
char struct_id[4];
/** 此結構的版本號。必須為 0 或 1, 0 表示沒有二進制文件將支持消息. */
int struct_version;
/** 將發布 LWT 消息的 LWT 主題. */
const char* topicName;
/** LWT payload. */
const char* message;
/** LWT 消息的保留標志(參見 MQTTAsync_message.retained). */
int retained;
/** LWT 消息的服務質量設置(參見 MQTTAsync_message.qos 和 @ref qos). */
int qos;
/** 二進制形式的 LWT 有效負載。僅當消息選項為 NULL 時才檢查和使用此項. */
struct
{
int len; /**< binary payload length */
const void* data; /**< binary payload data */
} payload;
} MQTTAsync_willOptions;
#define MQTTAsync_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, { 0, NULL } }
#define MQTT_SSL_VERSION_DEFAULT 0
#define MQTT_SSL_VERSION_TLS_1_0 1
#define MQTT_SSL_VERSION_TLS_1_1 2
#define MQTT_SSL_VERSION_TLS_1_2 3
/**
* 此函數創建一個 MQTT 客戶端，準備連接到指定的服務器并使用指定的持久存儲（請參閱MQTTAsync_persistence）。
* 另請參閱 MQTTAsync_destroy()。
* @param handle ::MQTTAsync 句柄的指針。此函數成功返回后，句柄將填充有效的客戶端引用。
* @param serverURI 以空字符結尾的字符串，指定客戶端將連接到的服務器。其格式為：
* <i>protocol://host:port</i> where <i>protocol</i> must be:
* <br>
* @em tcp:// or @em mqtt:// - Insecure TCP
* <br>
* @em ssl:// or @em mqtts:// - Encrypted SSL/TLS
* <br>
* @em ws:// - Insecure websockets
* <br>
* @em wss:// - Secure web sockets
* <br>
* 僅當鏈接了 TLS 版本的庫時，啟用 TLS 的前綴 (ssl、mqtts、wss) 才有效。
*
* 對于 <i>host</i>，您可以指定 IP 地址或主機名。例如，要使用
* 默認 MQTT 端口連接到在本地計算機上運行的服務器，請指定 <i>tcp://localhost:1883</i>。
*
* @param clientId 當客戶端連接到服務器時傳遞給服務器的客戶端標識符。它是一個以空字符結尾的 UTF-8 編碼字符串。
* @param persistence_type 客戶端要使用的持久性類型：
* <br>
* ::MQTTCLIENT_PERSISTENCE_NONE：使用內存持久性。如果運行客戶端的設備或系統發生故障或關閉，則任何正在傳輸的消息的當前
* 狀態都會丟失，并且即使在 QoS1 和 QoS2 下，某些消息也可能無法傳遞。
* <br>
* ::MQTTCLIENT_PERSISTENCE_DEFAULT：使用默認（基于文件系統）
* 持久性機制。有關正在傳輸的消息的狀態將保存在持久存儲中，并在發生意外故障時提供一些防止消息丟失的保護。
* <br>
* ::MQTTCLIENT_PERSISTENCE_USER：使用特定于應用程序的持久性
* 實現。使用這種類型的持久性可將持久性機制的控制權交給應用程序。應用程序必須實現
* MQTTClient_persistence 接口。
* @param persistence_context 如果應用程序使用::MQTTCLIENT_PERSISTENCE_NONE 持久性，則此參數未使用，應設置為 NULL。
* 對于 ::MQTTCLIENT_PERSISTENCE_DEFAULT 持久性，它
* 應設置為持久性目錄的位置（如果設置為
* NULL，則使用的持久性目錄是工作目錄）。
* 使用 ::MQTTCLIENT_PERSISTENCE_USER 持久性的應用程序將此
* 參數設置為指向有效的 MQTTClient_persistence 結構。
* @return ::MQTTASYNC_SUCCESS 如果客戶端創建成功，否則返回錯誤代碼。
*/
LIBMQTT_API int MQTTAsync_create(MQTTAsync* handle, const char* serverURI, const char* clientId, int persistence_type, void* persistence_context);
/** ::MQTTAsync_createWithOptions 調用的選項 */
typedef struct
{
/** 這個結構的亮點一定是 MQCO。 */
char struct_id[4];
/** 此結構的版本號。必須為 0、1、2 或 3
* 0 表示無 MQTTVersion
* 1 表示無 allowDisconnectedSendAtAnyTime、deleteOldestMessages 和 restoreMessages
* 2 表示無 persistQoS0
*/
int struct_version;
/** 是否允許在客戶端庫未連接時發送消息。 */
int sendWhileDisconnected;
/** 允許緩沖的最大消息數。此參數旨在用于
* 限制客戶端未連接時排隊的消息數。它也適用于
* 客戶端已連接的情況，因此必須大于 0。*/
int maxBufferedMessages;
/** MQTT 版本是 3.1、3.1.1 還是 5。要使用 V5，必須設置此項。
* 此處必須選擇 MQTT V5，因為在 create 調用期間會初始化消息持久性，
* 并且我們想知道任何持久化消息的格式是否
* 適合我們要連接的 MQTT 版本。選擇 3.1 或
* 3.1.1 并嘗試讀取 5.0 持久化消息將導致 create 時出錯。*/
int MQTTVersion;
/**
* 允許在首次成功連接之前斷開連接時發送消息。
*/
int allowDisconnectedSendAtAnyTime;
/** 當達到緩沖消息的最大數量時，刪除最舊的消息，而不是最新的消息。
*/
int deleteOldestMessages;
/** 創建時從持久化中恢復消息 - 或者清除它。
*/
int restoreMessages;
/** 保留 QoS0 發布命令 - 可選擇不保留它們。
*/
int persistQoS0;
} MQTTAsync_createOptions;
#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}
LIBMQTT_API int MQTTAsync_createWithOptions(MQTTAsync* handle, const char* serverURI, const char* clientId, int persistence_type,
void* persistence_context, MQTTAsync_createOptions* options);
/**
* MQTTAsync_sslProperties 定義了使用 OpenSSL 庫建立 SSL/TLS 連接的設置。
* 它涵蓋以下場景：
* - 服務器身份驗證：客戶端需要服務器的數字證書。該證書包含在
* 包含可信資料的存儲庫（也稱為“信任存儲庫”）中。
* - 相互身份驗證：客戶端和服務器在 SSL 握手期間都會進行身份驗證。除了信任存儲庫中的服務器數字證書外，客戶端還需要自己的
* 數字證書以及存儲在“密鑰存儲庫”中的用于簽署其數字證書的私鑰。
* - 匿名連接：客戶端和服務器均無需身份驗證，也無需任何憑據即可建立 SSL 連接。
* 請注意，此場景并非完全安全，因為它容易受到中間人攻擊。
*/
typedef struct
{
/** 此結構的醒目部分。必須是 MQTS */
char struct_id[4];
/** 此結構的版本號。必須為 0、1、2、3、4 或 5。
* 0 表示無 sslVersion
* 1 表示無 verify、CApath
* 2 表示無 ssl_error_context、ssl_error_cb
* 3 表示無 ssl_psk_cb、ssl_psk_context 和 disableDefaultTrustStore
* 4 表示無 protos、protos_len
*/
int struct_version;
/** 包含客戶端信任的公共數字證書的 PEM 格式的文件。 */
const char* trustStore;
/** PEM 格式的文件，包含客戶端的公共證書鏈。它還可能包含客戶端的私鑰。*/
const char* keyStore;
/** 如果 sslKeyStore 中未包含此設置，則此設置指向包含客戶端私鑰的 PEM 格式的文件。客戶端私鑰。*/
const char* privateKey;
/** 如果加密則加載客戶端私鑰的密碼。 */
const char* privateKeyPassword;
/**
* 客戶端在 SSL 握手期間將向服務器提供的密碼套件列表。有關密碼列表格式的完整說明，請參閱 OpenSSL 在線文檔：
* http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT
* 如果省略此設置，則其默認值為“ALL”，即所有密碼套件（不包括
* 不提供加密的密碼套件）都將被考慮。
* 此設置可用于設置 SSL 匿名連接（例如，“aNULL”字符串值）。
*/
const char* enabledCipherSuites;
/** True/False 選項用于啟用服務器證書驗證 **/
int enableServerCertAuth;
/** 要使用的 SSL/TLS 版本。請指定 MQTT_SSL_VERSION_DEFAULT (0)、
* MQTT_SSL_VERSION_TLS_1_0 (1)、MQTT_SSL_VERSION_TLS_1_1 (2) 或 MQTT_SSL_VERSION_TLS_1_2 (3) 之一。
* 僅當 struct_version >= 1 時使用。
*/
int sslVersion;
/*** 是否執行連接后檢查，包括證書是否
* 與給定的主機名匹配。
* 僅當 struct_version >= 2 時才存在
*/
int verify;
/**摘自 OpenSSL 文檔：
* 如果 CApath 不為 NULL，則指向包含 PEM 格式 CA 證書的目錄。
* 僅當 struct_version >= 2 時才存在
*/
const char* CApath;
/**
* OpenSSL 錯誤處理程序 ERR_print_errors_cb 的回調函數
* 僅當 struct_version >= 3 時存在
*/
int (*ssl_error_cb) (const char *str, size_t len, void *u);
/**
* OpenSSL 錯誤處理程序 ERR_print_errors_cb 的特定于應用程序的上下文
* 僅當 struct_version >= 3 時存在
*/
void* ssl_error_context;
/**
* 用于設置 TLS-PSK 選項的回調函數。參數與 SSL_CTX_set_psk_client_callback 的參數相對應，但 u 指向的是 ssl_psk_context 指針。
* 僅當 struct_version >= 4 時才存在
*/
unsigned int (*ssl_psk_cb) (const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len, void *u);
/** * ssl_psk_cb 的應用程序特定上下文 * 僅當結構版本 >= 4 時才存在 */
void* ssl_psk_context;
/**
* 不加載默認 SSL CA。應與 PSK 一起使用，以確保
* 已安裝證書的常規服務器不被接受。
* 僅當 struct_version >= 4 時才存在
*/
int disableDefaultTrustStore;
/**
* 協議列表必須采用線路格式，該格式定義為一個非空的、帶有 8 位長度前綴的字節字符串向量。
* 長度前綴字節不包含在長度中。每個字符串的長度限制為 255 個字節。長度為 0 的字節字符串無效。
* 截斷的字節字符串無效。
* 請查看 SSL_CTX_set_alpn_protos 的文檔。
* 僅當 struct_version >= 5 時才存在。
*/
const unsigned char *protos;
/**
* protos 向量的長度
* 僅當 struct_version >= 5 時存在
*/
unsigned int protos_len;
} MQTTAsync_SSLOptions;
#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 }
/**
* 為客戶端設置 MQTTAsync_connected() 回調函數。
* @param handle 成功調用MQTTAsync_create() 后獲得的有效客戶端句柄。
* @param context 指向任何特定于應用程序的上下文的指針。context 指針被傳遞給每個回調函數，以提供對回調中的上下文信息的訪問。
* @param co 指向 MQTTAsync_connected() 回調函數的指針。NULL 將刪除回調設置。
* @return ::MQTTASYNC_SUCCESS 如果回調設置正確，::MQTTASYNC_FAILURE 如果發生錯誤。
* @note: 1.初次連接成功時觸發:調用 MQTTAsync_connect()，連接成功（即 broker 返回 CONNACK）后，會在 onSuccess 回調之后 異步 調用 MqttAsyncConnected()
* 2.斷線自動重連成功后觸發:啟用了自動重連（MQTTAsync_connectOptions.automaticReconnect = 1），當客戶端從斷線狀態重新連上 broker 時，會調用 MqttAsyncConnected()
* 3.斷開連接時不會觸發: 斷開連接時會調用 connectionLost() 回調，而不是 connected()。
* 4. 調用 setConnected() 時不會立即觸發: 調用 MQTTAsync_setConnected() 只是注冊回調，不會立即觸發.
*/
LIBMQTT_API int MQTTAsync_setConnected(MQTTAsync handle, void* context, MQTTAsync_connected* co);
/**
* 此函數嘗試使用指定的選項將先前創建的客戶端（請參閱MQTTAsync_create()）連接到 MQTT 服務器。如果您
* 想要啟用異步消息和狀態通知，則必須在 MQTTAsync_connect() 之前調用MQTTAsync_setCallbacks()。
* @param handle 成功調用MQTTAsync_create() 后獲得的有效客戶端句柄。
* @param options 指向有效 MQTTAsync_connectOptions 結構的指針。
* @return ::MQTTASYNC_SUCCESS 客戶端連接請求被接受。
* 如果客戶端無法連接到服務器，則會通過 onFailure 回調（如果已設置）返回錯誤代碼。
* MQTT 協議會返回大于 0 的錯誤代碼：
* <b>1</b>: Connection refused: 協議版本不可接受
* <b>2</b>: Connection refused: 標識符被拒絕
* <b>3</b>: Connection refused: 服務器不可用
* <b>4</b>: Connection refused: 用戶名或密碼錯誤
* <b>5</b>: Connection refused: 未授權
* <b>6-255</b>: 保留以供將來使用
*/
LIBMQTT_API int MQTTAsync_connect(MQTTAsync handle, const MQTTAsync_connectOptions* options);
/** ::MQTTAsync_disconnect 調用的選項 */
typedef struct
{
/** 此結構的醒目元素。必須是 MQTD。*/
char struct_id[4];
/** 此結構的版本號。必須為 0 或 1。0 表示沒有 V5 屬性 */
int struct_version;
/**客戶端將斷開連接延遲最多此時間（以
* 毫秒為單位），以便完成正在進行的消息傳輸。
*/
int timeout;
/**指向一個回調函數的指針，當斷開連接成功完成時，該函數將被調用。
* 可以設置為 NULL，在這種情況下，將不會收到任何成功完成的指示。
*/
MQTTAsync_onSuccess* onSuccess;
/**指向斷開連接失敗時要調用的回調函數的指針。
* 可以設置為 NULL，在這種情況下，不會收到任何失敗的指示。
* 完成。
*/
MQTTAsync_onFailure* onFailure;
/**指向任何特定于應用程序的上下文的指針。
* <i>context</i> 指針將傳遞給成功或失敗回調函數，以
* 提供對回調中上下文信息的訪問。
*/
void* context;
/**MQTT V5 輸入屬性*/
MQTTProperties properties;
/**MQTTV5 斷開連接的原因代碼*/
enum MQTTReasonCodes reasonCode;
/**指向一個回調函數的指針，當斷開連接成功完成時，該函數將被調用。
* 可以設置為 NULL，在這種情況下，將不會收到任何成功完成的指示。
*/
MQTTAsync_onSuccess5* onSuccess5;
/**
* 指向斷開連接失敗時要調用的回調函數的指針。
* 可以設置為 NULL，在這種情況下，不會收到任何失敗的指示。
*/
MQTTAsync_onFailure5* onFailure5;
} MQTTAsync_disconnectOptions;
#define MQTTAsync_disconnectOptions_initializer { {'M', 'Q', 'T', 'D'}, 0, 0, NULL, NULL, NULL,\
MQTTProperties_initializer, MQTTREASONCODE_SUCCESS, NULL, NULL }
#define MQTTAsync_disconnectOptions_initializer5 { {'M', 'Q', 'T', 'D'}, 1, 0, NULL, NULL, NULL,\
MQTTProperties_initializer, MQTTREASONCODE_SUCCESS, NULL, NULL }
/**
* 此函數為特定客戶端設置全局回調函數。如果您的客戶端應用程序不使用特定回調，請將相關參數設置為 NULL（消息到達除外，必須提供該參數）。
* 任何必要的消息確認和狀態通信均在后臺處理，無需客戶端應用程序進行任何干預。
*
* Note: 調用此函數時，MQTT 客戶端必須斷開連接。
* @param handle 成功調用 MQTTAsync_create() 后獲得的有效客戶端句柄。
* @param context 指向任何特定于應用程序的上下文的指針。context 指針被傳遞給每個回調函數，以提供對回調中的上下文信息的訪問。
* @param cl 指向 MQTTAsync_connectionLost() 回調函數的指針。如果您的應用程序不處理斷開連接，您可以將其設置為 NULL。
* @param ma 指向 MQTTAsync_messageArrived() 回調函數的指針。如果未設置此回調，則會返回錯誤。您必須設置此回調，否則將無法傳遞任何傳入消息。
* @param dc 指向 MQTTAsync_deliveryComplete() 回調函數的指針。如果您不想檢查是否成功交付，可以將其設置為 NULL。
* @return ::MQTTASYNC_SUCCESS 如果回調設置正確，
* ::MQTTASYNC_FAILURE 如果發生錯誤。
*/
LIBMQTT_API int MQTTAsync_setCallbacks(MQTTAsync handle, void* context, MQTTAsync_connectionLost* cl, MQTTAsync_messageArrived* ma, MQTTAsync_deliveryComplete* dc);
/**
* 此函數允許客戶端應用程序測試客戶端當前是否已連接到 MQTT 服務器。
* @param handle 成功調用 MQTTAsync_create() 后有效的客戶端句柄。
* @return Boolean 如果客戶端已連接，則返回 true，否則返回 false。
*/
LIBMQTT_API int MQTTAsync_isConnected(MQTTAsync handle);
/**
* 嘗試讓客戶端訂閱單個主題，該主題可能包含通配符（請參閱@ref wildcard。
* contain wildcards (see @ref wildcard).
* 此調用還指定了 @ref 為訂閱請求的 qos（另請參閱 MQTTAsync_subscribeMany()）。
* @param handle 成功調用 MQTTAsync_create() 后獲得的有效客戶端句柄。
* @param topic 訂閱主題，可能包含通配符。
* @param qos 請求的訂閱服務質量。
* @param response 指向響應選項結構的指針。用于設置回調函數。
* @return ::MQTTASYNC_SUCCESS 如果訂閱請求成功。如果注冊訂閱時出現問題，則會返回錯誤代碼。
*
*/
LIBMQTT_API int MQTTAsync_subscribe(MQTTAsync handle, const char* topic, int qos, MQTTAsync_responseOptions* response);
/**
* 此函數嘗試將客戶端訂閱到一系列主題，這些主題可能
* 包含通配符（請參閱 @ref wildcard）。此調用還指定了
* @ref 為每個主題請求的 QoS（另請參閱 MQTTAsync_subscribe()）。
* @param handle 成功調用
* MQTTAsync_create() 后返回的有效客戶端句柄。
* @param count 客戶端請求訂閱的主題數量。
* @param topic 一個長度為 <i>count</i> 的數組，其中包含指向
* 主題的指針，每個主題可能包含通配符。
* @param qos 一個長度為 <i>count</i> 的數組，其中包含 @ref qos
* 值。qos[n] 是為 topic[n] 請求的 QoS。
* @param respond 一個指向響應選項結構的指針。用于設置回調函數。
* @return ::MQTTASYNC_SUCCESS（如果訂閱請求成功）。
* 如果注冊訂閱時出現問題，則會返回錯誤代碼。
*/
LIBMQTT_API int MQTTAsync_subscribeMany(MQTTAsync handle, int count, char* const* topic, const int* qos, MQTTAsync_responseOptions* respond);
/**
* 此函數嘗試刪除由指定客戶端做出的現有訂閱。
* @param handle 成功調用 MQTTAsync_create() 后獲得的有效客戶端句柄。
* @param topic 要刪除的訂閱的主題，可能包含通配符（請參閱@ref wildcard）。
* @param response 指向響應選項結構的指針。用于設置回調函數。
* @return ::MQTTASYNC_SUCCESS 如果刪除訂閱。如果刪除訂閱時出現問題，則會返回錯誤代碼。
*/
LIBMQTT_API int MQTTAsync_unsubscribe(MQTTAsync handle, const char* topic, MQTTAsync_responseOptions* response);
/**
* 此函數嘗試移除指定客戶端對一系列主題的現有訂閱。
* @param handle 成功調用 MQTTAsync_create() 后返回的有效客戶端句柄。
* @param count 待移除的訂閱數量。
* @param topic 指向待移除訂閱主題的指針數組（長度為 <i>count</i>），每個指針可以包含通配符。
* @param respond 指向響應選項結構的指針，用于設置回調函數。
* @return ::MQTTASYNC_SUCCESS（如果訂閱已移除）。
* 如果移除訂閱時出現問題，則返回錯誤代碼。
*/
LIBMQTT_API int MQTTAsync_unsubscribeMany(MQTTAsync handle, int count, char* const* topic, MQTTAsync_responseOptions* respond);
/**
* 此函數嘗試將消息發布到給定主題（另請參閱
* ::MQTTAsync_sendMessage()）。如果 QoS 大于 0，則此函數成功返回時會發出 ::MQTTAsync_token。
* 如果客戶端應用程序需要
* 測試消息是否成功送達，則應設置回調函數
* （請參閱 ::MQTTAsync_onSuccess() 和 ::MQTTAsync_deliveryComplete()）。
* @param handle 成功調用
* MQTTAsync_create() 后的有效客戶端句柄。
* @param destinationName 與此消息關聯的主題。
* @param payloadlen 有效負載的長度（以字節為單位）。
* @param payload 指向消息有效負載字節數組的指針。
* @param qos 消息的 @ref qos。
* @param retained 消息的 retained 標志。
* @param respond 指向 ::MQTTAsync_responseOptions 結構的指針。用于設置回調函數。
* 此參數為可選參數，可設置為 NULL。
* 如果消息被接受發布，則返回 ::MQTTASYNC_SUCCESS。
* 如果接受消息時出現問題，則返回錯誤代碼。
*/
LIBMQTT_API int MQTTAsync_send(MQTTAsync handle, const char* destinationName, int payloadlen, const void* load, int qos,
int retained, MQTTAsync_responseOptions* respond);
/**
* 此函數嘗試將消息發布到給定主題（另請參閱
* MQTTAsync_publish()）。當以下情況發生時，會發出 ::MQTTAsync_token：
* 如果 QoS 大于 0，則此函數成功返回。
* 如果客戶端應用程序需要
* 測試消息是否成功送達，則應設置回調函數
* （請參閱 ::MQTTAsync_onSuccess() 和 ::MQTTAsync_deliveryComplete()）。
* @param handle 成功調用 MQTTAsync_create() 后的有效客戶端句柄。
* @param destinationName 與此消息關聯的主題。
* @param msg 指向有效 MQTTAsync_message 結構的指針，該結構包含
* 待發布消息的有效負載和屬性。
* @param respond 指向 ::MQTTAsync_responseOptions 結構的指針。用于設置回調函數。
* 如果消息被接受發布，則返回 ::MQTTASYNC_SUCCESS。
* 如果接受消息時出現問題，則返回錯誤代碼。
*/
LIBMQTT_API int MQTTAsync_sendMessage(MQTTAsync 句柄, const char* 目標名稱, const MQTTAsync_message* 消息, MQTTAsync_responseOptions* 響應);
/**
* 此函數設置一個指向令牌數組的指針，該數組包含當前正在傳輸（待完成）的消息。
*
* <b>重要提示：</b>用于保存令牌數組的內存在此函數中已通過 malloc() 分配。客戶端應用程序負責在不再需要時釋放此內存。
* @param handle 成功調用 MQTTAsync_create() 后生成的有效客戶端句柄。
* @param tokens 指向 ::MQTTAsync_token 的指針地址。
* 當函數成功返回時，該指針指向一個
* 表示待完成消息的令牌數組。數組的最后一個成員設置為 -1，表示沒有其他令牌。如果沒有待完成的令牌，則指針設置為 NULL。
* 如果函數成功返回，則返回 ::MQTTASYNC_SUCCESS。
* 如果獲取待處理令牌列表時出現問題，則返回錯誤代碼。
*/
LIBMQTT_API int MQTTAsync_getPendingTokens(MQTTAsync handle, MQTTAsync_token **tokens);
/**
* 測試與令牌對應的請求是否完成。
*
* @param handle 成功調用 MQTTAsync_create() 后的有效客戶端句柄。
* @param token 與請求關聯的 ::MQTTAsync_token。
* @return 如果請求已完成，則返回 1；否則返回 0。
*/
#define MQTTASYNC_TRUE 1
LIBMQTT_API int MQTTAsync_isComplete(MQTTAsync handle, MQTTAsync_token token);
/**
* 等待與令牌對應的請求完成。這僅適用于
* QoS 大于 0 的消息。QoS 0 消息沒有 MQTT 令牌。
* 對于 QoS 0 消息，此函數始終返回 ::MQTTASYNC_SUCCESS。
*
* @param handle 成功調用 MQTTAsync_create() 后的有效客戶端句柄。
* @param token 與請求關聯的 ::MQTTAsync_token。
* @param timeout 等待完成的最長時間，以毫秒為單位。
* @return ::MQTTASYNC_SUCCESS（如果請求已在分配的時間內完成）；
* 否則，返回 ::MQTTASYNC_FAILURE 或 ::MQTTASYNC_DISCONNECTED。
*/
LIBMQTT_API int MQTTAsync_waitForCompletion(MQTTAsync handle, MQTTAsync_token token, unsigned long timeout);
/**
* 此函數釋放分配給 MQTT 消息的內存，包括
* 分配給消息有效負載的額外內存?？蛻舳藨贸绦?* 在消息完全處理后調用此函數。<b>重要提示：</b>此函數不會釋放分配給消息主題字符串的內存。客戶端應用程序需要使用 MQTTAsync_free() 庫函數釋放此內存。
* @param msg 指向待釋放的 ::MQTTAsync_message 結構體的指針地址。
*/
LIBMQTT_API void MQTTAsync_freeMessage(MQTTAsync_message** msg);
/**
* 此函數釋放由 MQTT C 客戶端庫分配的內存，尤其是
* 主題名稱。在 Windows 上，當客戶端庫和應用程序
* 使用不同版本的 C 編譯器編譯時，需要使用此函數。因此，在釋放任何 MQTT C 客戶端分配的內存時，始終使用此函數是一個好策略。
?? @param ptr 指向要釋放的客戶端庫存儲的指針。
*/
LIBMQTT_API void MQTTAsync_free(void* ptr);
/**
* 此函數用于分配內存以供 MQTT C 客戶端庫使用或釋放??，
* 尤其是 ::MQTTPersistence_afterRead 和 ::MQTTPersistence_beforeWrite
* 回調中的數據。在 Windows 上，當客戶端庫和應用程序
* 使用不同版本的 C 編譯器編譯時，需要使用此函數。
* @param size 待分配內存的大小。
*/
LIBMQTT_API void* MQTTAsync_malloc(size_t size);
/**
* 此函數釋放分配給 MQTT 客戶端的內存（參見
* MQTTAsync_create()）。當客戶端不再需要時，應調用此函數。
* @param handle 指向要釋放的 ::MQTTAsync 結構的句柄的指針。
*/
LIBMQTT_API void MQTTAsync_destroy(MQTTAsync* handle);
/**
* 此函數設置將在跟蹤回調中返回的跟蹤信息級別。
* @param level 所需的跟蹤級別
*/
LIBMQTT_API void MQTTAsync_setTraceLevel(enum MQTTASYNC_TRACE_LEVELS level);
/**
* 如果您想要接收跟蹤信息，則必須實現此回調函數原型。
* 請勿在此回調函數中調用任何其他 Paho API 調用 - 否則可能會導致不可預測的行為。
* @param level 返回消息的跟蹤級別。
* @param message 跟蹤消息。這是一個指向靜態緩沖區的指針，
* 該緩沖區將在每次調用時被覆蓋。如果您想保留此數據以備后用，則必須復制此數據。
*/
typedef void MQTTAsync_traceCallback(enum MQTTASYNC_TRACE_LEVELS level, char* message);
/**
* 此函數根據需要設置跟蹤回調。如果設置為 NULL，
* 將不會返回任何跟蹤信息。默認跟蹤級別為
* MQTTASYNC_TRACE_MINIMUM。
* @param callback 指向處理跟蹤信息的函數的指針。
*/
LIBMQTT_API void MQTTAsync_setTraceCallback(MQTTAsync_traceCallback* callback);
/**
* 此函數返回庫的版本信息。
* 將不會返回任何跟蹤信息。默認跟蹤級別為
* MQTTASYNC_TRACE_MINIMUM
* @return 一個描述庫的字符串數組。最后一項為 NULL 指針。
*/
LIBMQTT_API MQTTAsync_nameValue* MQTTAsync_getVersionInfo(void);
/**
* 返回指向錯誤代碼字符串表示形式的指針，或 NULL。
* 使用后不釋放。如果錯誤代碼未知，則返回 NULL。
* @param code MQTTASYNC_ 返回代碼。
* @return 錯誤代碼的靜態字符串表示。
*/
LIBMQTT_API const char* MQTTAsync_strerror(int code);
/**
* 此函數嘗試斷開客戶端與 MQTT 服務器的連接。為了允許客戶端有時間完成處理調用此函數時正在傳輸的消息，需要指定超時期限。
* 超時期限到期后，即使仍有未完成的消息確認，客戶端也會斷開連接。
* 客戶端下次連接到同一服務器時，任何未完成的 QoS 1 或 2
* 消息都將根據上一個連接和新連接的 cleansession 設置進行重試（請參閱
* MQTTAsync_connectOptions.cleansession 和 MQTTAsync_connect()）。
* @param handle 成功調用 MQTTAsync_create() 后獲得的有效客戶端句柄。
* @param options 客戶端最多會延遲斷開連接此時間（以毫秒為單位），以允許正在進行的消息傳輸完成。
* @return ::MQTTASYNC_SUCCESS（如果客戶端成功斷開與服務器的連接）。如果客戶端無法斷開與服務器的連接，則返回錯誤代碼
****/
LIBMQTT_API int MQTTAsync_disconnect(MQTTAsync handle, const MQTTAsync_disconnectOptions* options);
/**
* 此函數釋放分配給 MQTT 客戶端的內存（請參閱
* MQTTAsync_create()）。當客戶端不再需要時，應調用此函數。
* @param handle 成功調用 MQTTAsync_create() 后獲得的有效客戶端句柄。
*/
LIBMQTT_API void MQTTAsync_destroy(MQTTAsync* handle);
/*****************************************************************************************
* @cond MQTTAsync_main
* @page 異步線程
* 客戶端應用程序在多個線程上運行。
* 握手和網絡連接維護的處理在后臺執行。
* 此 API 是線程安全的：函數可以被多個應用程序調用。
* 線程。
* 通過調用在庫中注冊的回調函數，向客戶端提供狀態和消息接收通知。
* 應用程序可以通過調用
* MQTTAsync_setCallbacks()（參見 MQTTAsync_messageArrived()、
* MQTTAsync_connectionLost() 和 MQTTAsync_deliveryComplete()）。
* 此外，某些函數允許在 ::MQTTAsync_responseOptions 結構中為單個請求設置成功和失敗回調。
* 應用程序可以編寫為回調函數鏈。
*
* @page 回調 回調
* 此 API 中的任何函數都可以在回調中使用。但是，不建議在回調中使用 ::MQTTAsync_waitForCompletion，因為它是唯一一個可能需要一些時間才能完成的 API 調用，這可能會導致不可預測的行為。所有其他 API 調用都旨在快速完成，并在后臺啟動請求，并通過其他回調通知成功或失敗。
*
* 如果沒有分配回調，則將包含消息到達回調。
* 如果應用程序是純發布者，并且未訂閱任何主題，則可以執行此操作。但是，如果收到了消息，但未設置消息到達回調，則這些消息將累積并占用內存，因為沒有空間可以傳遞它們。
* 系統將寫入一條日志消息以突出顯示問題，但這取決于應用程序是否能夠防止這種情況發生。
*
* @page auto_reconnect 自動重新連接
* 客戶端庫在連接失敗時自動重新連接的功能已在 1.1 版中添加。連接丟失回調
* 允許靈活地響應連接丟失，因此幾乎任何
* 行為都可以通過這種方式實現。自動重新連接的優勢在于
* 使用起來更簡單。
*
* 要啟用自動重新連接，請將連接選項字段
* 中的automaticReconnect設置為非零值。下次連接嘗試前的最小和最大時間
* 也可以設置，默認值分別為 1 秒和
* 60 秒。每次重新連接失敗時，重試間隔都會加倍，直到
* 達到最大值，并一直保持到連接
* 成功重新建立后重置。
*
* 重新連接嘗試成功后，將調用 ::MQTTAsync_connected 回調
* 函數（如果通過調用 ::MQTTAsync_setConnected 設置了該函數）。這允許
* 應用程序執行任何必要的操作，例如修改訂閱。
*
* @page offline_publish 斷開連接時發布
* 此功能最初不可用，因為啟用持久性后，
* 消息可能會存儲在本地，而無需知道是否可以發送。
* 客戶端應用程序可能創建了錯誤的代理，
* 例如，代理地址或端口。
*
* 要在應用程序斷開連接時也能發布消息，
* 必須使用 ::MQTTAsync_createWithOptions 而不是 ::MQTTAsync_create 來
* 創建客戶端對象。::MQTTAsync_createOptions 字段的 sendWhileDisconnected
* 必須設置為非零值，并且 maxBufferedMessages 字段必須根據需要設置 -
* 默認值為 100。
*
* 可以調用 ::MQTTAsync_getPendingTokens 來返回等待發送或發送過程尚未完成的消息 ID。
*
* @page wildcard 訂閱通配符
* 每條 MQTT 消息都包含一個對其進行分類的主題。MQTT 服務器使用
* 主題來確定哪些訂閱者應該接收發布到
* 服務器的消息。
*
* 假設服務器接收來自多個環境傳感器的消息。
* 每個傳感器都將其測量數據作為一條消息發布，并關聯一個
* 主題。訂閱應用程序需要知道最初是哪個傳感器
* 發布了每條收到的消息。因此，使用唯一的主題來標識
* 每個傳感器和測量類型。諸如 SENSOR1TEMP、
* SENSOR1HUMIDITY、SENSOR2TEMP 等主題可以實現這一點，但靈活性不夠。
* 如果以后系統中添加了其他傳感器，則必須修改訂閱應用程序才能接收這些傳感器。
*
* 為了提供更大的靈活性，MQTT 支持分層主題命名空間。
* 這使得應用程序設計人員可以組織主題以簡化其管理。
* 層次結構中的級別由“/”字符分隔，
* 例如 SENSOR/1/HUMIDITY。發布者和訂閱者使用這些
* 分層主題，如上所述。
*
* 對于訂閱，支持兩個通配符：
* <ul>
* <li>“#”字符表示層次結構的完整子樹，
* 因此必須是訂閱主題字符串中的最后一個字符，例如
* SENSOR/#。這將匹配任何以 SENSOR/ 開頭的主題，例如
* SENSOR/1/TEMP 和 SENSOR/2/HUMIDITY。</li>
* <li>“+”字符表示層次結構的單個級別，用于分隔符之間。例如，SENSOR/+/TEMP 將匹配
* SENSOR/1/TEMP 和 SENSOR/2/TEMP。</li>
* </ul>
* 發布者不得在其主題名稱中使用通配符。
* 確定主題層次結構是系統設計中的重要一步。
*
* @page qos 服務質量
* MQTT 協議為在客戶端和服務器之間傳遞消息提供了三種服務質量：
* “最多一次”、“至少一次”和
* “恰好一次”。
*
* 服務質量 (QoS) 是正在發布的單個消息的屬性。
* 應用程序通過將 MQTTAsync_message.qos 字段設置為所需值來設置特定消息的 QoS。
*
* 訂閱客戶端可以設置服務器用于發送與客戶端訂閱匹配的消息的最大服務質量。
* MQTTAsync_subscribe() 和 MQTTAsync_subscribeMany() 函數設置此
* 最大值。因此，轉發給訂閱者的消息的 QoS 可能與
* 原始發布者賦予該消息的 QoS 不同。
* 將使用這兩個值中較低的一個值來轉發消息。
* *
* 這三個級別分別是：
*
* <b>QoS0，最多一次</b>：消息最多傳遞一次，否則可能根本不傳遞。消息在網絡上的傳遞不會被確認。消息不會被存儲。如果客戶端斷開連接或服務器發生故障，消息可能會丟失。QoS0 是最快的傳輸模式。有時也稱為“發射后不管”。
*
* MQTT 協議不要求服務器將 QoS0 的發布轉發給客戶端。如果客戶端在服務器接收發布時斷開連接，則發布可能會被丟棄，具體取決于服務器的實現。
*
* <b>QoS1，至少一次</b>：消息始終至少傳遞一次。如果在發送方收到確認之前發生故障，則消息可能會被傳遞多次。消息必須存儲在發送方本地，
* 直到發送方收到接收方已發布的確認。
* 消息將被存儲，以防需要再次發送。
*
* <b>QoS2，恰好一次：</b> 消息始終只傳遞一次。
* 消息必須存儲在發送方本地，直到發送方收到接收方已發布的確認。
* 消息將被存儲，以防需要再次發送。QoS2 是最安全但速度最慢的傳輸模式。與 QoS1 相比，QoS2 使用更復雜的握手和確認序列，以確保不會發生消息重復。
* @page publish 發布示例
*****************************************************************************************/
浙公網安備 33010602011771號