介紹一下常用的MQTT的C函數。MQTT系列函數有很多，在paho-mqtt.c庫中的src路徑下有大量函數的定義和聲明，這裏只介紹比較常用的函數解耦提和結構體：
1.結構體MQTTClient
定義:typedef void* MQTTClient;
含義：代表MQTT客戶端的句柄，成功調用MQTTClient_create函數後會得到有效的客戶端句柄。
（這裏可以做一個對比，我並不是很瞭解這種句柄機制，但是在網絡socket編程中，一系列函數會返回或者使用我認爲類似句柄的東西----文件描述符，在socket編程中的服務器程序有socket初始化文件描述符socket_fd,這個文件描述符在之後會bind服務器的一些標誌信息ip和端口以及協議族，讓它成爲和客戶端連接的標誌，函數accept也會返回一個文件描述符，這個文件描述符成爲s/c通信的“橋樑”，文件描述符本身只是一個整型數字，但是當綁定一系列的條件之後，就會有更多作用（我認爲宏也是這樣的）。我認爲這裏的句柄也是這樣。）
2.結構體MQTTClient_connectOptions
定義：
typedef struct
{
char struct_id[4];//結構體的識別序列，必須爲MQTC
int struct_version;//結構體版本
/**
在0,1,2,3,4,5中取值：
0-表示沒有SSL選項且沒有serverURIs；
1-表示沒有serverURIs；
2-表示沒有MQTTVersion
3-表示沒有返回值；
4-表示沒有二進制密碼選項
*/
int keepAliveInterval;
/**
在這段時間內沒有數據相關的消息時，客戶端發送一個非常小的MQTT“ping”消息，服務器將會確認這個消息
*/
int cleansession;
/**
當cleansession爲true時，會話狀態信息在連接和斷開連接時被丟棄。 將cleansession設置爲false將保留會話狀
態信息
*/
int reliable;
/*
將該值設置爲true意味着必須完成發佈的消息（已收到確認），才能發送另一個消息
*/
MQTTClient_willOptions* will;
/*
如果程序不使用最後的意願和遺囑功能，請將此指針設置爲NULL。
*/
const char* username;//用戶名
const char* password;//密碼
int connectTimeout;//允許嘗試連接的過時時間
int retryInterval;//嘗試重連的時間
MQTTClient_SSLOptions* ssl;
/*
如果程序不使用最後的ssl,請將此指針設置爲NULL。
*/
int serverURIcount;
char* const* serverURIs;
/*
連接服務器的url，以protocol：// host：port爲格式
*/
int MQTTVersion;
/*
MQTT的版本,MQTTVERSION_3_1（3），MQTTVERSION_3_1_1 (4)
*/
struct
{
const char* serverURI;
int MQTTVersion;
int sessionPresent;
} returned;
struct {
int len;
const void* data;
} binarypwd;
} MQTTClient_connectOptions;
3.MQTTClient_message
typedef struct
{
char struct_id[4];//結構體的識別序列，必須爲MQTM
int struct_version;//結構體的版本，必須爲0
int payloadlen;//MQTT信息的長度
void* payload;//指向消息負載的指針
int qos;//服務質量
int retained;//保留標誌
int dup;dup//標誌指示這個消息是否是重複的。 只有在收到QoS1消息時纔有意義。 如果爲true，則客戶端應用程序應採取適當的措施來處理重複的消息。
int msgid;//消息標識符通常保留供MQTT客戶端和服務器內部使用。
} MQTTClient_message;
4.MQTTClient_create
DLLExport int MQTTClient_create(
MQTTClient * handle,
const char * serverURI,
const char * clientId,
int persistence_type,
void * persistence_context
)
作用：該函數創建了一個用於連接到特定服務器，使用特定持久存儲的MQTT客戶端。
作用：該函數創建了一個用於連接到特定服務器，使用特定持久存儲的MQTT客戶端。
參數 含義
handle 指向MQTT客戶端句柄的指針。句柄被成功從函數中返回的客戶端引用所填充
serverURI 以空結尾的字符串，其指定客戶端將連接到的服務器。其格式爲protocol://host:port。現在的（protocol）
協議必須是tcp或ssl，而host可以指定爲IP地址或域名。例如, 要使用默認 MQTT 端口連接到本地計算機上運行的服務
器, 請指定爲 tcp://localhost:1883。
clientId 客戶端標識符（clientId）是一個以空結尾的 UTF-8 編碼字符串，客戶端連接到服務器時將它傳遞過去。
persistence_type 客戶端所使用的持久類型。MQTTCLIENT_PERSISTENCE_NONE-使用內存持久化。如果客戶端運
行的設備或系統出故障或關閉, 則任何正在運行的消息的當前狀態都將丟失, 甚至在 QoS1 和 QoS2 中也可能無法傳遞
某些消息; MQTTCLIENT_PERSISTENCE_DEFAULT-使用默認的持久化機制（文件系統）。正在運行消息的狀態被保
存在持久存儲中，以便在意外出現時對消息的丟失提供一些保護; MQTTCLIENT_PERSISTENCE_USER-使用程序指
定的持久化實現。使用這種類型，應用程序可對持久化機制進行控制，應用程序必須實現MQTTClient_persistence 接
口。
persistence_context 如果應用程序使用的是MQTTCLIENT_PERSISTENCE_NONE持久化，該參數不使用，而且值
應該設置爲NULL。對於MQTTCLIENT_PERSISTENCE_DEFAULT持久化，應該設置持久化目錄的位置（如果設置爲
NULL，則使用工作目錄作爲持久化目錄）。使用MQTTCLIENT_PERSISTENCE_USER持久化，則將此參數指向有效
的MQTTClient_persistence結構。
5.MQTTClient_setCallbacks
DLLExport int MQTTClient_setCallbacks (
MQTTClient handle,
void * context,
MQTTClient_connectionLost * cl,
MQTTClient_messageArrived * ma,
MQTTClient_deliveryComplete * dc
)
作用：該函數爲特定的客戶端創建回調函數。如果您的客戶端應用程序不使用特定的回調函數，請將相關參數設置爲
NULL。 調用MQTTClient_setCallbacks（）使客戶端進入多線程模式。 任何必要的消息確認和狀態通信都在後臺處
理，而不需要客戶端應用程序的任何干預。
注意：在調用該函數時，MQTT客戶端必須斷開連接。（即先要調用該函數在連接客戶端）。
| 參數 | 含義 |
| ---|-------------|
| handle | 指向MQTT客戶端句柄的指針。句柄被成功從函數中返回的客戶端引用所填充 |
| context| 指向任何應用程序特定上下文的指針。 上下文指針被傳遞給每個回調函數，以提供對回調中的上下文信息的
訪問。|
|cl|指向MQTTClient_connectionLost()回調函數的指針。 如果您的應用程序不處理斷開連接，您可以將其設置爲
NULL。|
|ma|指向MQTTClient_messageArrived()回調函數的指針。 當您調用MQTTClient_setCallbacks()時，必須指定此回調
函數。|
|dc|指向MQTTClient_deliveryComplete()回調函數的指針。 如果您的應用程序同步發佈，或者您不想檢查是否成功發
送，則可以將其設置爲NULL。|
6.MQTTClient_connect
DLLExport int MQTTClient_connect (
MQTTClient handle,
MQTTClient_connectOptions * options
)
作用：此函數嘗試使用指定的選項將先前創建的客戶端連接到MQTT服務器。
參數 含義
handle 指向MQTT客戶端句柄的指針。句柄被成功從函數中返回的客戶端引用所填充
options 指向有效的MQTTClient_connectOptions結構的指針。
> 返回值
0 連接成功
1 拒絕連接：不可接受的協議版本。
2 拒絕連接：標識符被拒絕。
3 拒絕連接：服務器不可用。
4 拒絕連接：用戶名或密碼錯誤。
5 拒絕連接：未經授權。
6 保留給未來用。
MQTTClient_subscribe
定義：
DLLExport int MQTTClient_subscribe (
MQTTClient handle,
const char * topic,
int qos
)
作用：此功能嘗試將客戶訂閱到單個主題，該主題可能包含通配符。 此函數還指定服務質量。
參數 含義
handle 指向MQTT客戶端句柄的指針。句柄被成功從函數中返回的客戶端引用所填充
topic 訂閱的主題，可使用通配符。
qos 訂閱的請求服務質量
7.MQTTClient_publishMessage
DLLExport int MQTTClient_publishMessage (
MQTTClient handle,
const char * topicName,
MQTTClient_message * msg,
MQTTClient_deliveryToken * dt
)
作用：此功能嘗試將客戶訂閱到單個主題，該主題可能包含通配符。 此函數還指定服務質量。
參數 含義
handle 指向MQTT客戶端句柄的指針。句柄被成功從函數中返回的客戶端引用所填充
topicName 與信息相關的主題。
msg 指向有效的 MQTTClient_message 結構的指針, 其中包含要發佈消息的有效負載和屬性
dt 指向MQTTClient_deliveryToken的指針。當函數成功返回時，dt會被賦值爲代表消息的token。如果程序中沒有使用
傳遞token，將其設置爲NULL。
8.MQTTClient_waitForCompletion
DLLExport int MQTTClient_waitForCompletion (
MQTTClient handle,
MQTTClient_deliveryToken dt,
unsigned long timeout
)
作用：客戶端應用程序調用此函數來將主線程的執行與消息的完成發佈同步。 被調用時，
MQTTClient_waitForCompletion()阻塞執行，直到消息成功傳遞或已超過指定的時間。
參數 含義
handle 指向MQTT客戶端句柄的指針。句柄被成功從函數中返回的客戶端引用所填充
dt 代表消息的MQTTClient_deliveryToken用來檢測是否成功傳遞。傳遞token由發佈函數MQTTClient_publish () 和
MQTTClient_publishMessage ()所產生。
timeout 等待的最大毫秒數。
返回值：
消息成功傳遞則返回MQTTCLIENT_SUCCESS(0) ，如果時間已過期或檢測token時出問題，則返回錯誤碼。
9.MQTTClient_receive
int MQTTClient_receive(
MQTTClient handle,
char** topicName,
int* topicLen,
MQTTClient_message** message,
unsigned long timeout)
僅當客戶端應用程序未設置回調方法爲
支持異步接收消息。使用此函數允許單線程
要編寫的客戶端訂閱程序。當調用這個函數時
阻塞，直到下一條消息到達或指定超時過期
重要提示:當處理完成時，應用程序必須釋放()分配給主題和消息的內存(請參閱
MQTTClient_freeMessage ())。
handle是執行函數MQTTClient_create函數返回的有效句柄
topicName指向主題的指針的地址。這個函數
爲主題分配內存並將其返回給應用程序
通過設置topicName指向主題。
topicLen主題的長度。如果從這個返回代碼
函數是::MQTTCLIENT_TOPICNAME_TRUNCATED，主題包含嵌入式
應使用以下命令檢索空字符和完整主題
topicLen
指向接收到的消息的指針的地址。該函數爲消息分配內存，並通過設置message指向接收到的消息，將其返回給應用程序。如果超時超時，指針將被設置爲NULL。超時等待消息的時間(以毫秒爲單位)。