Linux下学习用C语言实现MQTT(二）（常用函数介绍）_mqtt与文件系统

介绍一下常用的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;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

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;
1
2
3
4
5
6
7
8
9
10
11

4.MQTTClient_create

DLLExport int MQTTClient_create(    
        MQTTClient *    handle,
        const char *    serverURI,
        const char *    clientId,
        int     persistence_type,
        void *      persistence_context 
    ) 
1
2
3
4
5
6
7

作用：该函数创建了一个用于连接到特定服务器，使用特定持久存储的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结构。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

5.MQTTClient_setCallbacks

DLLExport int MQTTClient_setCallbacks   (   
        MQTTClient      handle,
        void *      context,
        MQTTClient_connectionLost *     cl,
        MQTTClient_messageArrived *     ma,
        MQTTClient_deliveryComplete *   dc 
    )   
1
2
3
4
5
6
7

作用：该函数为特定的客户端创建回调函数。如果您的客户端应用程序不使用特定的回调函数，请将相关参数设置为
NULL。 调用MQTTClient_setCallbacks（）使客户端进入多线程模式。 任何必要的消息确认和状态通信都在后台处
理，而不需要客户端应用程序的任何干预。

注意：在调用该函数时，MQTT客户端必须断开连接。（即先要调用该函数在连接客户端）。
| 参数 | 含义 |
| ---|-------------|
| handle | 指向MQTT客户端句柄的指针。句柄被成功从函数中返回的客户端引用所填充 |
| context| 指向任何应用程序特定上下文的指针。 上下文指针被传递给每个回调函数，以提供对回调中的上下文信息的
访问。|
|cl|指向MQTTClient_connectionLost()回调函数的指针。 如果您的应用程序不处理断开连接，您可以将其设置为
NULL。|
|ma|指向MQTTClient_messageArrived()回调函数的指针。 当您调用MQTTClient_setCallbacks()时，必须指定此回调
函数。|
|dc|指向MQTTClient_deliveryComplete()回调函数的指针。 如果您的应用程序同步发布，或者您不想检查是否成功发
送，则可以将其设置为NULL。|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

6.MQTTClient_connect

DLLExport int MQTTClient_connect    (   
        MQTTClient      handle,
        MQTTClient_connectOptions *     options 
    ) 
1
2
3
4

作用：此函数尝试使用指定的选项将先前创建的客户端连接到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	订阅的请求服务质量
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

7.MQTTClient_publishMessage

DLLExport int MQTTClient_publishMessage     (   
        MQTTClient      handle,
        const char *    topicName,
        MQTTClient_message *    msg,
        MQTTClient_deliveryToken *      dt 
    ) 
1
2
3
4
5
6

作用：此功能尝试将客户订阅到单个主题，该主题可能包含通配符。 此函数还指定服务质量。

参数	含义
handle	指向MQTT客户端句柄的指针。句柄被成功从函数中返回的客户端引用所填充
topicName	与信息相关的主题。
msg	指向有效的 MQTTClient_message 结构的指针, 其中包含要发布消息的有效负载和属性
dt	指向MQTTClient_deliveryToken的指针。当函数成功返回时，dt会被赋值为代表消息的token。如果程序中没有使用
传递token，将其设置为NULL。
1
2
3
4
5
6
7
8

8.MQTTClient_waitForCompletion

DLLExport int MQTTClient_waitForCompletion  (   
        MQTTClient      handle,
        MQTTClient_deliveryToken    dt,
        unsigned long   timeout 
    )  
1
2
3
4
5

作用：客户端应用程序调用此函数来将主线程的执行与消息的完成发布同步。 被调用时，
MQTTClient_waitForCompletion()阻塞执行，直到消息成功传递或已超过指定的时间。

参数	含义
handle	指向MQTT客户端句柄的指针。句柄被成功从函数中返回的客户端引用所填充
dt	代表消息的MQTTClient_deliveryToken用来检测是否成功传递。传递token由发布函数MQTTClient_publish () 和

 MQTTClient_publishMessage ()所产生。
timeout	等待的最大毫秒数。
返回值：
消息成功传递则返回MQTTCLIENT_SUCCESS(0) ，如果时间已过期或检测token时出问题，则返回错误码。
1
2
3
4
5
6
7
8
9
10
11

9.MQTTClient_receive

int MQTTClient_receive(
MQTTClient handle,
 char** topicName,
 int* topicLen, 
 MQTTClient_message** message,
 unsigned long timeout)
1
2
3
4
5
6

仅当客户端应用程序未设置回调方法为
支持异步接收消息。使用此函数允许单线程
要编写的客户端订阅程序。当调用这个函数时
阻塞，直到下一条消息到达或指定超时过期
重要提示:当处理完成时，应用程序必须释放()分配给主题和消息的内存(请参阅
MQTTClient_freeMessage ())。
handle是执行函数MQTTClient_create函数返回的有效句柄
topicName指向主题的指针的地址。这个函数
为主题分配内存并将其返回给应用程序
通过设置topicName指向主题。
 topicLen主题的长度。如果从这个返回代码
函数是::MQTTCLIENT_TOPICNAME_TRUNCATED，主题包含嵌入式
应使用以下命令检索空字符和完整主题
topicLen
指向接收到的消息的指针的地址。该函数为消息分配内存，并通过设置message指向接收到的消息，将其返回给应用程序。如果超时超时，指针将被设置为NULL。超时等待消息的时间(以毫秒为单位)。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

参考博客：https://www.cnblogs.com/homejim/p/8196763.html