1 MQTTClient_message 结构体

很重要的结构体，客户端应用程序发布消息和接收消息都是围绕这这个结构体展开的。
该结构体描述了MQTT消息的负载和属性等相关信息，例如消息的负载、负载长度、qos等。
结构体部分内容如下：

typedef struct
{int payloadlen;		// 负载长度void* payload;		// 负载int qos;			// 消息的qos等级int retained;		// 消息的保留标志int dup;			//  dup 标志int msgid;			// 消息标识符......
}

客户端发布消息时需要实例化一个MQTTClient_message对象，接收消息时，也是接收到一个MQTTClient_message对象。

2 创建客户端对象

在连接服务端之前，需要创建一个客户端对象，创建客户端对象使用函数MQTTClient_create，函数原型如下：

int MQTTClient_create(MQTTClient *handle,				// MQTT客户端句柄const char *serverURL,			// MQTT服务端IP地址const char *clientID,			// 客户端IDint persustence_type,			// 客户端使用的持久化类型void *persistence_context		// 持久化目录
)

返回值

成功：MQTTCLIENT_SUCCESS
失败：返回一个错误码

持久化类型：

• MQTTCLIENT_PERSISTENCE_NONE：使用内存持久性。如果运行客户端的设备或系统出现故障或关闭，则任何传输中消息的当前状态都会丢失，并且即使在 QoS1 和 QoS2 下也可能无法传递某些消息。
• MQTTCLIENT_PERSISTENCE_DEFAULT：使用默认的（基于文件系统）持久性机制。传输中消息的状态保存在文件系统中，并在意外故障的情况下提供一些防止消息丢失的保护。
• MQTTCLIENT_PERSISTENCE_USER：使用特定于应用程序的持久性实现。使用这种类型的持久性可以控制应用程序的持久性机制。应用程序必须实现 MQTTClient_persistence 接口。

persistence_context：
如果使用 MQTTCLIENT_PERSISTENCE_NONE 持久化类型，则该参数应设置为NULL。如果选择的是 MQTTCLIENT_PERSISTENCE_DEFAULT 持久化类型，则该参数应设置为持久化目录的位置，如果设置为 NULL，则持久化目录就是客户端应用程序的工作目录。

3 连接服务端

客户端创建之后，就可以连接服务端了，连接服务端函数：MQTTClient_connect
函数原型

int MQTTClient_connect(MQTTClient handle,						// 客户端句柄MQTTClient_connetOption *options		// 
)

结构体中包含了keepAlive、cleanSessiion以及一个指向MQTTClient_willOption结构体对象的指针will_opts；MQTTClient_willOption结构体中包含了客户端遗嘱信息，遗嘱主题、遗嘱内容、遗嘱消息的Qos等级、遗嘱消息的保留标志等。

返回值

成功：MQTTCLIENT_SUCCESS
失败：1：连接被拒绝。不可接受的协议版本，不支持客户端的 MQTT 协议版本2：连接被拒绝：标识符被拒绝3：连接被拒绝：服务器不可用4：连接被拒绝：用户名或密码错误5：连接被拒绝：未授权6-255：保留以备将来使用

MQTTClient_connectOptions结构体

typedef struct
{int keepAliveInterval; 			//keepAliveint cleansession; 				//cleanSessionMQTTClient_willOptions *will; 	//遗嘱相关const char *username; 			//用户名const char *password; 			//密码int reliable; 					//控制同步发布消息还是异步发布消息............
} MQTTClient_connectOptions;

通常在定义 MQTTClient_connectOptions 对象时会使用MQTTClient_connectOptions_initializer 宏对其进行初始化操作；而在定义 MQTTClient_willOptions 对象时使用 MQTTClient_willOptions_initializer 宏对其初始化。

3 设置回调函数

使用MQTTClient_setCallbacks函数为应用程序设置回调函数。可以设置多个回调函数，包括：

• 断开连接时的回调函数cl：当客户端检测到自己掉线时会执行该函数，如果将其设置为 NULL
  表示应用程序不处理断线的情况
• 接受消息的回调函数ma：当客户端接收到服务端发送过来的消息时执
  行该函数，必须设置此函数否则客户端无法接收消息
• 发布消息的回调函数dc：当客户端发布的消息已经确认发送时执行该回调函数，如果你的应用程序采用同步方式发布消息或者您不想检查是否成功发送时，您可以将此设置为 NULL

函数原型

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

函数参数

handle: 客户端句柄
context：执行回调函数的时候，会将 context 参数传递给回调函数，因为每一个回调函数都设置了一个参数用来接收 context 参数。
cl:一个 MQTTClient_connectionLost 类型的函数指针，如下：typedef void MQTTClient_connectionLost(void *context, char *cause);参数 cause 表示断线的原因，是一个字符串。ma:一个 MQTTClient_messageArrived 类型的函数指针，如下：typedef int MQTTClient_messageArrived(void *context, char *topicName,int topicLen, MQTTClient_message *message);参数 topicName 表示消息的主题名， topicLen 表示主题名的长度；参数 message 指向一个MQTTClient_message 对象，也就是客户端所接收到的消息。dc：一个 MQTTClient_deliveryComplete 类型的函数指针，如下：typedef void MQTTClient_deliveryComplete(void* context, MQTTClient_deliveryToken dt);参数 dt 表示 MQTT 消息的值，将其称为传递令牌。发布消息时（应用程序通过MQTTClient_publishMessage 函数发布消息，MQTT协议会返回给客户端应用程序一个传递令牌；应用程序可以通过将调用 MQTTClient_publishMessage()返回的传递令牌与传递给此回调的令牌进行匹配来检查消息是否已成功发布。

返回值

成功：MQTTCLIENT_SUCCESS
失败：MQTTCLIENT_FAILURE

注意：调用 MQTTClient_setCallbacks 函数设置回调必须在连接服务器之前完成！

同步消息发送与异步消息发送
前面提到了“同步发布消息”这个概念，既然有同步发布，那必然有异步发布，确实如何！那如何控制是同步发布还是异步发布呢？就是通过 MQTTClient_connectOptions 对象中的 reliable 成员控制的，这是一个布尔值，当 reliable=1 时使用同步方式发布消息，意味着必须完成当前正在发布的消息（收到确认）之后才能发布另一个消息；如果 reliable=0 则使用异步方式发布消息。
当使用 MQTTClient_connectOptions_initializer 宏对 MQTTClient_connectOptions 对象进行初始化时，
reliable 标志被初始化为 1，所以默认是使用了同步方式。

4 发布消息

使用MQTTClient_publishMessage函数发布一个消息
函数原型

int MQTTClient_publishMessage(MQTTClient handle,const char *topicName,MQTTClient_message *msg,MQTTClient_deliveryToken *dt
)

函数参数

handle:客户端句柄
topicName：主题名称，像该主题发布消息
msg：指向一个MQTTClient_message对象指针
dt：返回给应用程序的令牌

返回值

成功：回 MQTTCLIENT_SUCCESS
失败：错误返回码

5 订阅主题和取消订阅主题

5.1 订阅主题

使用函数MQTTClient_subscribe()订阅主题信息
函数原型

int MQTTClient_subscribe(MQTTClient handle,const char *topic,int qos
)

函数参数

handle：客户端句柄
topic：主题名称，客户端订阅主题
qos：Qos等级

返回值

成功：MQTTCLIENT_SUCCESS
失败：返回错误码

5.2 取消订阅

使用函数MQTTClient_unsubscribe()
函数原型

int MQTTClient_unsubscrube(MQTTClient handle,const char *topic
)

函数参数

handle: 客户端句柄
topic: 主题名称，取消订阅该主题

返回值

成功：MQTTCLIENT_SUCCESS
失败：返回错误码

6 断开服务连接

函数：MQTTClient_disconnect()
函数原型

int MQTTClient_disconnect(MQTTClient handle,int timeout
)

函数参数

handle：客户端句柄
timeout：超时时间

返回值

成功：MQTTCLIENT_SUCCESS
失败：返回错误代码