mosquitto库常用的相关函数解析-CSDN博客

②clean_session：设置为 true 可指示代理在断开连接时清除所有消息和订阅，设置为 false 以指示代理保留它们。注意：客户端在断开连接时永远不会丢弃自己的传出消息。呼叫mosquitto_connect或mosquitto_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的指针

③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_forever和mosquitto_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 包含错误代码。