mosquitto库常用的相关函数解析

目录

mosquitto_lib_init()

mosquitto_lib_cleanup()

mosquitto_new()

struct mosquitto

mosquitto_destroy()

mosquitto_connect()

mosquitto_connect_callback_set()

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

mosquitto_connect_async()

mosquitto_disconnect()

mosquitto_disconnect_callback_set()

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

mosquitto_publish()

mosquitto_publish_callback_set()

void (*on_publish)(struct mosquitto *mosq, void *obj, int mid)

mosquitto_subscribe()

mosquitto_subscribe_callback_set()

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

mosquitto_message_callback_set()

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

const struct mosquitto_message

mosquitto_loop()

mosquitto_loop_forever()

mosquitto_loop_start()

mosquitto_loop_stop()


包含的头文件是:mosquitto.h 

注:此头文件用于包含libmosquitto(Mosquitto客户端库)的函数和定义。该库提供线程安全操作,但mosquitto_lib_init除外,它不是线程安全的

mosquitto_lib_init()

int mosquitto_lib_init(void)

功能描述:在使用数据库之前必须要先初始化,所以该函数必须在任何其它mosquitto函数之前调用,且使用后要用mosquitto_lib_cleanup(),进行清除

返回值:成功则返回MOSQ_ERR_SUCCESS,若返回MOSQ_ERR_UNKNOWN,则表示在Windows上,无法初始化套接字

mosquitto_lib_cleanup()

int mosquitto_lib_cleanup(void)

功能描述:对使用完的mosquitto库函数,进行相关清除操作

mosquitto_new()

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

功能描述:创建一个新的mosquitto客户端实例,使用完后一定要使用mosquitto_destroy()释放相关内存

参数解析:

①id:用作客户端 ID 的字符串。如果为 NULL,则将生成一个随机客户端 ID。如果 id 为 NULL,则clean_session必须为真

②clean_session:设置为 true 可指示代理在断开连接时清除所有消息和订阅,设置为 false 以指示代理保留它们。注意:客户端在断开连接时永远不会丢弃自己的传出消息。呼叫mosquitto_connectmosquitto_reconnect将导致邮件被重新发送。使用mosquitto_reinitialise将客户端重置为其原始状态。如果 id 参数为 NULL,则必须设置为 true

③obj:一个用户指针,它将作为参数传递给指定的任何回调。

返回值:成功则返回结构体mosquitto的指针,失败则返回NULL。询问 errno 以确定失败的原因:

ENOMEM内存不足

EINVAL无效的输入参数

struct mosquitto

该结构体用来保存客户端连接的所有信息

struct mosquitto {
#ifndef WIN32
    int sock; /*服务器程序与该客户端连接通信所用的socket描述符*/
#  ifndef WITH_BROKER
    int sockpairR, sockpairW;
#  endif
#else
    SOCKET sock;
#  ifndef WITH_BROKER
    SOCKET sockpairR, sockpairW;
#  endif
#endif
    enum _mosquitto_protocol protocol;
    char *address;/*该客户端的IP地址*/
    char *id;/*该客户端登陆mosquitto程序时所提供的ID值,该值与其他的客户端不能重复*/
    char *username;/*登录用户名*/
    char *password;/*密码*/
    uint16_t keepalive;/*该客户端需在此时间内向mosquitto服务器程序发送一条ping/ping消息*/
    uint16_t last_mid;
    enum mosquitto_client_state state;
    time_t last_msg_in;/*last_msg_in和last_msg_out用于记录上次收发消息的时间*/
    time_t last_msg_out;
    time_t ping_t;
    struct _mosquitto_packet in_packet;
    struct _mosquitto_packet *current_out_packet;
    struct _mosquitto_packet *out_packet;
    struct mosquitto_message *will;
        ...
    bool want_write;
    bool want_connect;
#if defined(WITH_THREADING) && !defined(WITH_BROKER)
    pthread_mutex_t callback_mutex;
    pthread_mutex_t log_callback_mutex;
    pthread_mutex_t msgtime_mutex;
    pthread_mutex_t out_packet_mutex;
    pthread_mutex_t current_out_packet_mutex;
    pthread_mutex_t state_mutex;
    pthread_mutex_t in_message_mutex;
    pthread_mutex_t out_message_mutex;
    pthread_t thread_id;
#endif
    bool clean_session;
#ifdef WITH_BROKER
    bool is_dropping;
    bool is_bridge;
    struct _mqtt3_bridge *bridge;
    struct mosquitto_client_msg *msgs;/*用于暂时存储发往该context的消息。*/
    struct mosquitto_client_msg *last_msg;
    int msg_count;
    int msg_count12;
    struct _mosquitto_acl_user *acl_list;
    struct _mqtt3_listener *listener;
    time_t disconnect_t;
    struct _mosquitto_packet *out_packet_last;
    struct _mosquitto_subhier **subs;
    int sub_count;
    int pollfd_index;
...
};

moqsuitto源代码的相关数据结构解析

mosquitto_destroy()

void mosquitto_destroy(struct mosquitto *mosq)

功能描述:用于释放与 mosquitto 客户端实例关联的内存

参数解析:mosq:结构体mosquitto的指针

mosquitto_connect()

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

功能描述:连接到MQTT代理(服务器),注意:订阅主题要在连接服务器之后进行,该函数常用于同步阻塞调用,如果使用mosquitto_loop(),则必须用此函数连接客户端

参数解析:

①mosq:结构体mosquitto的指针

②host:服务器的主机名或 ip 地址

③port:服务器的端口,通常是1883

④keepalive:保持连接的时间间隔,单位是秒,如果在此时间内未交换其他消息,则代理应向客户端发送 PING 消息的秒数。

返回值:成功则返回MOSQ_ERR_SUCCESS,否则返回以下情况:

MOSQ_ERR_INVAL 输入的参数无效,如:

  • mosq == 空
  • 主机 == 空
  • 端口 < 0
  • 保持< 5

MOSQ_ERR_ERRNO 系统调用返回错误,变量errno包含错误代码

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的指针

②on_connect:一个回调函数

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

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

参数解析:

①mosq:结构体mosquitto的指针

②obj:创建客户端的回调参数,是mosquitto_new中提供的用户数据

③rc:连接相应的返回代码,连接成功rc值为0,其余值均为失败,ru:

1--连接被拒绝(协议版本不可接受)

2--连接被拒绝(标识符被拒绝)

3--连接被拒绝(经纪人不可用)

4--255(保留供将来使用)

mosquitto_connect_async()

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

功能描述:连接到MQTT代理(服务器),注意:订阅主题要在连接服务器之后进行,该函数常用于异步非阻塞调用,若使用该函数,则客户端必须使用线程接口mosquitto_loop_start

参数解析:

①mosq:结构体mosquitto的指针

②host:服务器的主机名或 ip 地址

③port:服务器的端口,通常是1883

④keepalive:保持连接的时间间隔,单位是秒,如果在此时间内未交换其他消息,则代理应向客户端发送 PING 消息的秒数。

返回值:成功则返回MOSQ_ERR_SUCCESS,否则返回以下情况:

MOSQ_ERR_INVAL 输入的参数无效,如:

  • mosq == 空
  • 主机 == 空
  • 端口 < 0
  • 保持< 5

MOSQ_ERR_ERRNO 系统调用返回错误,变量errno包含错误代码

mosquitto_disconnect()

int mosquitto_disconnect(struct mosquitto *mosq)

功能描述:客户端断开与代理(服务器)的连接

参数解析:mosq:结构体mosquitto的指针

返回值:成功则返回MOSQ_ERR_SUCCESS,否则返回以下情况:

MOSQ_ERR_INVAL 输入参数无效

MOSQ_ERR_NO_CONN 客户端未连接到代理

mosquitto_disconnect_callback_set()

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

功能描述:设置断开连接回调。当代理收到断开连接命令并断开客户端连接时,将调用此选项

参数解析:

①mosq:结构体mosquitto的指针

②on_disconnect:一个回调函数

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

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

参数解析:

①mosq:结构体mosquitto的指针

②obj:创建客户端的回调参数,是mosquitto_new中提供的用户数据

③rc:指示断开连接原因的整数值。值为 0 表示客户端已调用mosquitto_disconnect。任何其他值都表示断开连接是意外的。

mosquitto_publish()

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

功能描述:发布有关给定主题的消息

参数解析:

①mosq:结构体mosquitto的指针

②mid:指向int的指针。如果不是 NULL,则该函数会将此设置为此特定消息的消息 ID。然后,这可以与发布回调一起使用,以确定消息的发送时间。请注意,尽管 MQTT 协议不对 QoS=0 的消息使用消息 ID,但 libmosquitto 会为它们分配消息 ID,以便可以使用此参数跟踪它们。

③topic:要发布的注意(以NULL结尾的字符串)

④payloadlen:有效负载的大小(字节)。有效值介于 0 和 268,435,455 之间。

⑤payload:指向要发送的数据的指针。如果 payloadlen > 0,则必须是有效的内存位置。

⑥qos:整数值 0、1 或 2,指示要用于消息的服务质量。

⑦retain:设置为 true 可保留邮件。

返回值:成功则返回MOSQ_ERR_SUCCESS,否则返回以下情况:

MOSQ_ERR_INVAL输入参数无效。
MOSQ_ERR_NOMEM发生内存不足情况。
MOSQ_ERR_NO_CONN客户端未连接到代理。
MOSQ_ERR_PROTOCOL与代理通信时存在协议错误。
MOSQ_ERR_PAYLOAD_SIZE有效载荷太大。
MOSQ_ERR_MALFORMED_UTF8主题无效,则为UTF-8
MOSQ_ERR_QOS_NOT_SUPPORTED QoS 大于代理支持的 QoS。
MOSQ_ERR_OVERSIZE_PACKET生成的数据包大于代理支持的数据包。

mosquitto_publish_callback_set()

 void mosquitto_publish_callback_set(struct mosquitto *mosq, void (*on_publish)(struct mosquitto *mosq, void *obj, int mid))

功能描述:设置发布回调。当使用 mosquitto_publish 启动的消息已成功发送到代理时,将调用此选项

参数解析:

①mosq:结构体mosquitto的指针

②on_publish:一个回调函数

void (*on_publish)(struct mosquitto *mosq, void *obj, int mid)

void (*on_publish)(struct mosquitto *mosq, void *obj, int mid)

参数解析:

①mosq:结构体mosquitto的指针

②obj:创建客户端的回调参数,是mosquitto_new中提供的用户数据

③mid:已发送邮件的消息 id

mosquitto_subscribe()

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

功能描述:客户端订阅主题

参数解析:

①mosq:结构体mosquitto的指针

②mid:指向int的指针。如果不是 NULL,则该函数会将此设置为此特定消息的消息 ID。然后,这可以与发布回调一起使用,以确定消息的发送时间。请注意,尽管 MQTT 协议不对 QoS=0 的消息使用消息 ID,但 libmosquitto 会为它们分配消息 ID,以便可以使用此参数跟踪它们。

③sub:订阅的主题名称,订阅模式

④qos:整数值 0、1 或 2,指示要用于消息的服务质量。

返回值:成功则返回MOSQ_ERR_SUCCESS,否则返回以下情况:

MOSQ_ERR_INVAL输入参数无效。
MOSQ_ERR_NOMEM发生内存不足情况。
MOSQ_ERR_NO_CONN客户端未连接到代理。
MOSQ_ERR_MALFORMED_UTF8主题无效,则为UTF-8
MOSQ_ERR_OVERSIZE_PACKET生成的数据包大于代理支持的数据包。

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的指针

②on_subscribe:一个回调函数

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

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

①mosq:结构体mosquitto的指针

②obj:创建客户端的回调参数,是mosquitto_new中提供的用户数据

③mid:订阅消息的消息 id

④qos_count:授予的订阅数(granted_qos的大小)

⑤granted_qos:一个整数数组,指示为每个订阅授予的 QoS

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的指针

②on_message:一个回调函数

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

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

参数解析:

①mosq:结构体mosquitto的指针

②obj:创建客户端的回调参数,是mosquitto_new中提供的用户数据

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

const struct mosquitto_message

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

mosquitto_loop()

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

功能描述:客户端的主网络环路。必须经常调用此项,以保持客户端和代理之间的通信正常工作。这是通过mosquitto_loop_forevermosquitto_loop_start来执行的,这是处理网络环路的推荐方法。它不能在回调中调用。

如果存在传入的数据,则将对其进行处理。传出命令,例如mosquitto_publish,通常会在调用其函数后立即发送,但这并不总是可能的。mosquitto_loop还将尝试发送任何剩余的传出消息,其中还包括作为具有 QoS>0 的消息流一部分的命令。

参数解析:

①mosq:结构体mosquitto的指针

②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 包含错误代码。

mosquitto_loop_forever()

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

功能描述:

此函数在无限阻塞循环中调用 loop()。对于只想在程序中运行 MQTT 客户机循环的情况,它非常有用。它处理服务器连接丢失时的重新连接。如果在回调中调用 mosquitto_disconnect(),它将返回

参数解析:

①mosq:结构体mosquitto的指针

②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 包含错误代码。

mosquitto_loop_start()

int mosquitto_loop_start(struct mosquitto *mosq)

功能描述:网络事件循环处理函数,客户端通过创建新的线程不断调用mosquitto_loop()函数来处理网络事件,该函数非阻塞

参数解析:

①mosq:结构体mosquitto的指针

返回值:成功则返回MOSQ_ERR_SUCCESS,否则返回以下情况:

MOSQ_ERR_INVAL 输入的参数无效

MOSQ_ERR_NOT_SUPPORTED 没有线程的支持

mosquitto_loop_stop()

 int mosquitto_loop_stop(struct mosquitto *mosq, bool force)

功能描述:这是线程化客户端接口的一部分。调用此命令一次以停止以前使用mosquitto_loop_start创建的网络线程。此调用将阻塞,直到网络线程完成。要结束网络线程,必须先前调用 mosquitto_disconnect 或已将 force 参数设置为 true

参数解析:

①mosq:结构体mosquitto的指针

②force:设置为 true 可强制取消线程。如果为 false,则mosquitto_disconnect一定已被调用。

返回值:成功则返回MOSQ_ERR_SUCCESS,否则返回以下情况:

MOSQ_ERR_INVAL 输入的参数无效

MOSQ_ERR_NOT_SUPPORTED 没有线程的支持

本博客只列出常见的函数,其余的相关API请查看官方文件:

https://mosquitto.org/api/files/mosquitto-h.html

  • 5
    点赞
  • 28
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值