mosquitto库中常见的函数

最新推荐文章于 2024-07-25 14:49:22 发布

Xiezongyi

最新推荐文章于 2024-07-25 14:49:22 发布

阅读量707

点赞数 1

分类专栏： MQTT学习记录文章标签：服务器 linux

本文链接：https://blog.csdn.net/qq_46312211/article/details/124546711

版权

MQTT学习记录专栏收录该内容

1 篇文章 0 订阅

订阅专栏

本文详细介绍了MQTT客户端库mosquitto的一系列关键API，包括初始化、连接、断开、发布、订阅等操作，以及相关回调函数的设置。这些API在物联网(IoT)应用中用于与MQTT代理进行交互，实现设备间的通信。同时，文章还涵盖了连接确认、断开连接、消息接收和订阅响应的回调函数，帮助开发者更好地理解和使用mosquitto库。

摘要由CSDN通过智能技术生成

今天列举的API是我在做项目过程中会使用到的，在该博客我将全部记录下来：

文章目录

常用函数

1、mosquitto_lib_init

int mosquitto_lib_init(void)

函数功能：使用mosquitto库函数前，要先初始化，使用之后需要清除。
此函数不是线程安全的（线程安全：多个线程访问同一个对象时，调用这个对象的行为都可以获得正确的结果），也就是说mosquitto要第一个使用。

返回值：总是MOSQ_ERR_SUCCESS

2、mosquitto_lib_cleanup

int mosquitto_lib_cleanup(void)

作用：使用完mosquitto函数后，需要做清除工作

返回值：总是MOSQ_ERR_SUCCESS

3、mosquitto *mosquitto_new

struct mosquitto *mosquitto_new(const char *id, bool clean_session, void *obj)

作用：创建一个新的mosquitto客户端实例

参数：
①id：用作客户端id的字符串。如果为NULL，生成一个随机的客户端id，此时clean_session必须为true。

②clean_session: 若设置为true表示：代理（Broker）在断开时，客户端清除所有的消息和订阅；设置为false表示保留它们，客户端永远不会在断开时丢弃自己传出的消息。

③obj：用户指针，将作为参数传递给指定的任何回调（回调参数）

返回值：
成功：返回结构mosquitto的指针
失败：NULL

查询errno以确定失败的原因：
ENOMEM：内存不足
EINVAL: 输入参数无效

4、mosquitto_destroy

void mosquitto_destroy(struct mosquitto *mosq)

作用：用于释放与mosquitto客户端实例关联的内存

参数：有效的mosquitto实例，mosquitto_new()返回的mosq，客户端

5、mosquitto_username_pw_set

int mosquitto_username_pw_set(struct mosquitto * mosq, const char *username, const char *password )

功能：为mosquitto实例配置用户名和密码，必须在调用mosquitto_connect之前调用这个参数。

参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq

②username ：以字符串形式发送的用户名，或以NULL形式关闭认证

③password ：以字符串形式发送的密码。当用户名有效时，设置为NULL，以便只发送一个用户名。

返回值：
MOSQ_ERR_SUCCESS：成功
MOSQ_ERR_INVAL：输入参数无效
MOSQ_ERR_NOMEM：发生内存不足的情况

6、mosquitto_connect

int mosquitto_connect( struct mosquitto *mosq, const char *host, int port, int keepalive )

功能：连接到MQTT代理（Broker）/服务器
主题订阅要在连接服务器之后进行

参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq，客户端

②host：服务器ip地址

③port：服务器的端口号

④keepalive：保持连接的时间间隔，单位：秒
如果在这段时间内没有其他消息交换，则代理应该将PING消息发送到客户端的秒数

返回值：
MOSQ_ERR_SUCCESS ：成功
MOSQ_ERR_INVAL ：输入参数无效
MOSQ_ERR_ERRNO ：系统调用返回错误

7、mosquitto_disconnect

int mosquitto_disconnect( struct mosquitto *mosq )

功能：断开代理与服务器的连接

返回值：
MOSQ_ERR_SUCCESS ：成功。
MOSQ_ERR_INVAL ：输入参数无效。
MOSQ_ERR_NO_CONN ：客户端未连接到代理

8、mosquitto_publish

int mosquitto_publish( struct mosquitto *mosq, int *mid, const char *topic, int payloadlen, const void *payload, int qos, bool retain)

功能：发布主题

参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq

②mid：指向int的指针。如果不为NULL，则函数会将其设置为该特定消息的消息ID。然后可以将其与订阅回调一起使用，以确定何时发送消息
注意：尽管MQTT协议不对Qos = 0 的消息使用消息ID，但libmosquitto为其分配了消息ID，以便可以使用此参数对其进行跟踪。

③topic：要发布的主题，以null结尾的字符串

④payloadlen：主题消息的内容长度

⑤payload：主题消息的内容，指向要发送数据的指针；
如果payloadlen > 0，其必须是有效的存储位置

⑥qos：消息服务质量，整数值0、1、2

⑦retain:是否要保留消息，true为保留，false为不保留

返回值：
MOSQ_ERR_SUCCESS ：成功
MOSQ_ERR_INVAL ：输入参数无效
MOSQ_ERR_NOMEM ：发生内存不足的情况
MOSQ_ERR_NO_CONN ：客户端未连接到代理
MOSQ_ERR_PROTOCOL：与代理进行通信时存在协议错误
MOSQ_ERR_PAYLOAD_SIZE：payloadlen太大
MOSQ_ERR_QOS_NOT_SUPPORTED：QoS大于代理支持的QoS
MOSQ_ERR_MALFORMED_UTF8 ：主题无效，则为UTF-8
MOSQ_ERR_OVERSIZE_PACKET ：结果包大于代理支持的包

9、mosquitto_subscribe

int mosquitto_subscribe( struct mosquitto *mosq, int *mid, const char *sub, int qos)

功能：订阅主题

参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq

②mid：指向int的指针。如果不为NULL，则函数会将其设置为该特定消息的消息ID。然后可以将其与订阅回调一起使用，以确定何时发送消息

③sub：主题的消息ID

④qos：消息服务质量，整数值0、1、2

返回值：
MOSQ_ERR_SUCCESS ：成功
MOSQ_ERR_INVAL ：输入参数无效
MOSQ_ERR_NOMEM ：发生内存不足的情况
MOSQ_ERR_NO_CONN ：客户端未连接到代理
MOSQ_ERR_QOS_NOT_SUPPORTED：QoS大于代理支持的QoS
MOSQ_ERR_MALFORMED_UTF8 ：主题无效，则为UTF-8
MOSQ_ERR_OVERSIZE_PACKET ：结果包大于代理支持的包

10、mosquitto_loop_start

int mosquitto_loop_start( struct mosquitto * mosq )

函数功能：网络事件循环处理函数，通过创建新的线程不断调用mosquitto_loop() 函数处理网络事件，不阻塞

返回值：
MOSQ_ERR_SUCCESS 成功。
MOSQ_ERR_INVAL 如果输入参数无效。
MOSQ_ERR_NOT_SUPPORTED 如果没有线程支持。

11、mosquitto_loop_forever

int mosquitto_loop_forever(struct mosquitto *mosq, int timeout, int max_packets)

功能：此函数在无限阻塞循环中调用loop()，对于只想在程序中运行MQTT客户端循环的情况，这很有用。
如果服务器断开，该函数会重新连接；若在回调中调用mosquitto_disconnect()它将返回

参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq

②timeout：超时之前，在select()调用中等待网络活动的最大毫秒数；
设置为0为立刻返回，设置为负可使用默认值为1000ms。

③max_packets：该参数当前为使用，应设为1，以备来兼容

返回值：
MOSQ_ERR_SUCCESS ：成功
MOSQ_ERR_INVAL ：输入参数无效
MOSQ_ERR_NOMEM ：发生内存不足的情况
MOSQ_ERR_NO_CONN ：客户端未连接到代理
MOSQ_ERR_CONN_LOST：与代理的连接丢失
MOSQ_ERR_PROTOCOL：与代理进行通信时存在协议错误
MOSQ_ERR_ERRNO：系统调用发生错误。变量errno包含错误代码

12、mosquitto_loop_stop

int mosquitto_loop_stop( struct mosquitto *mosq, bool force )

功能：网络事件阻塞回收结束处理函数，是线程客户端接口的一部分。
调用一次可停止先前使用mosquitto_loop_start创建的网络线程；该调用将一直阻塞，直到网络线程结束。
可以事先调用mosquitto_disconnect或将force参数设置为true，来使网络线程结束

参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq

②force：
设为true表示：强制取消线程；若设为false，则必须已经调用mosquitto_disconnect

返回值：
MOSQ_ERR_SUCCESS：成功
MOSQ_ERR_INVAL：输入参数无效
MOSQ_ERR_NOT_SUPPORTED：没有线程支持

回调函数

1、mosquitto_connect_callback_set

void mosquitto_connect_callback_set( struct mosquitto *mosq, void (*on_connect )(struct mosquitto *mosq, void *obj, int rc) )

功能：连接确认回调函数，当代理发送CONNACK消息以响应连接时，将调用此方法完成某一功能

参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq

②回调函数，示例如下
void callback (struct mosquitto *mosq, void *obj, int rc)
回调的参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq

②void *obj：创建客户端时的回调参数（mosquitto_new中提供的用户数据）

③int rc： 0表示连接成功，其他表示失败
rc连接响应的返回码，其中有：

0-成功
1-连接被拒绝（版本协议不可接受）
2-连接被拒绝（通识符被拒绝）
3-连接被拒绝（经纪人不可用）
4-255（保留供将来使用）

2、mosquitto_disconnect_callback_set

void mosquitto_disconnect_callback_set( struct mosquitto *mosq, void (*on_disconnect )(struct mosquitto *mosq, void *obj, int rc) )

功能：断开连接回调函数，当代理收到DISCONNECT命令并断开与客户端的连接，将调用此方法

参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq，客户端

②回调函数，示例如下：
void callback (struct mosquitto *mosq, void *obj, int rc)
回调的参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq

②void *obj：创建客户端时的回调参数

③int rc： 0表示客户端已经调用mosquitto_disconnect
任何其他值都表示：连接时意外断开的

3、mosquitto_message_callback_set

void mosquitto_message_callback_set( struct mosquitto *mosq, void (*on_message)(struct mosquitto *mosq, void *obj, const struct mosquitto_message *message) )

功能：消息回调函数，收到订阅的消息后调用

参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq

②回调函数，格式如下：
void callback (struct mosquitto *mosq, void *obj, const struct mosquitto_message *message)
回调的参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq

②obj：mosquitto_new()中提供的用户数据

③message：消息数据。回调完成后，mosquitto库将释放此变量和内存的关联，客户应复制其所需要的任何数据

struct mosquitto_message{
int mid; //消息序号ID
char *topic; //主题
void *payload; //主题内容， MQTT中有效载荷
int payloadlen; //消息的长度，单位是字节
int qos；//服务质量
bool retain；//是否保留消息
};

4、mosquitto_subscribe_callback_set

void mosquitto_subscribe_callback_set( struct mosquitto * mosq, void (*on_subscribe)(struct mosquitto *mosq, void *obj, int mid, int qos_count, const int *granted_qos) )

功能：设置订阅回调。当代理响应订阅请求时，将调用此方法

参数：
①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq

②回调函数，格式如下：
void callback (struct mosquitto *mosq, void *obj, int mid, int qos_count, const int *granted_qos)
回调的参数：

①mosq：有效的mosquitto实例，mosquitto_new()返回的mosq

②void *obj：创建客户端时的回调参数（mosquitto_new中提供的用户数据）

③mid：订阅消息的消息ID

④qos_count：授予的订阅数（grant_qos的大小)

⑤granted_qos：整数数组，指示每个订阅的已授予QoS。