【MQTT】Mosquitto库函数常见API函数

1.初始化和清理

（1）mosquitto_lib_init()

mosquitto_lib_init();

功能：初始化Mosquitto库，必须在使用Mosquitto库其他函数之前调用

（2）mosquitto_lib_cleanup()

mosquitto_lib_cleanup();

功能：清理Mosquitto库相关资源，必须在程序结束时调用

2.客户端的创建和销毁

（1）mosquitto_new()

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

功能：创建一个Mosquitto客户端实例
参数：
id：客户端ID字符串
clean_session：一个布尔值，表示是否启用清理会话
userdata：指向用户自定义数据的指针
返回值：指向新创建的Mosquitto客户端实例的指针

（2）mosquitto_destroy()

void mosquitto_destroy(struct mosquitto *mosq);

功能：销毁Mosquitto客户端实例，并释放相关资源
参数：指向Mosquitto客户端实例的指针

3.客户端用户名和密码

(1)mosquitto_username_pw_set

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

功能：为 mosquitto 实例配置用户名和密码。默认情况下，不会发送用户名或密码。对于 v3.1 和 v3.1.1 客户端，如果 username 为 NULL，则忽略密码参数。这必须在调用mosquitto_connect之前调用。

参数：
mosq：一个有效的mosquitto实例
username：要作为字符串发送的用户名，或 NULL 以禁用身份验证。
password：作为字符串发送的密码。当用户名有效时设置为 NULL，以便仅发送用户名。

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

4.与MQTT代理服务器的连接、重新连接与断开连接

（1）mosquitto_connect()

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

功能：连接到MQTT代理服务器
参数：
mosq：指向Mosquitto客户端实例的指针
host：代理服务器的主机名和IP地址
port：代码服务器的端口号
keepalive：保持连接的时间间隔（以秒为单位）
返回值：连接结果，成功返回0，失败返回错误码

（2）mosquitto_disconnect()

int mosquitto_disconnect(struct mosquitto *mosq);

功能：断开与MQTT代理服务器的连接
参数：指向Mosquitto客户端实例的指针
返回值：
MOSQ_ERR_SUCCESS：关于成功。
MOSQ_ERR_INVAL：如果输入参数无效。
MOSQ_ERR_NO_CONN：如果客户端未连接到代理

（3）mosquitto_reconnect()

int mosquitto_reconnect(struct mosquitto *mosq);

功能：重新连接到代理。此功能提供了一种在连接丢失后重新连接到代理的简单方法。它使用mosquitto_connect调用中提供的值。但不能在mosquitto_connect之前调用它。
参数：指向Mosquitto客户端实例的指针
返回值：
MOSQ_ERR_SUCCESS：关于成功。
MOSQ_ERR_INVAL：如果输入参数无效。
MOSQ_ERR_NOMEM：如果发生内存不足的情况。
MOSQ_ERR_ERRNO：如果系统调用返回错误。变量 errno 包含错误代码，即使在 Windows 上也是如此。在Linux下可使用 strerror(errno) 或在 Windows 上使用 FormatMessage()获取错误。

5.发布、订阅与取消订阅

(1)mosquitto_publish()

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

功能：向MQTT代理服务器发布消息
参数：
mosq：指向Mosquitto客户端实例的指针
mid：用于存储消息ID的整数指针
topic：消息的主题
payloadlen：消息负载的字节数
payload：指向消息负载数据的指针
qos：消息的服务质量（0、1、2）
retain：指定是否保留消息
返回值：
MOSQ_ERR_SUCCESS：成功
MOSQ_ERR_INVAL：如果输入参数无效。
MOSQ_ERR_NOMEM：如果发生内存不足的情况。
MOSQ_ERR_NO_CONN：如果客户端未连接到代理。
MOSQ_ERR_PROTOCOL：如果与代理通信时出现协议错误。
MOSQ_ERR_PAYLOAD_SIZE：如果 payloadlen 太大。
MOSQ_ERR_MALFORMED_UTF8：如果主题不是有效的 UTF-8
MOSQ_ERR_QOS_NOT_SUPPORTED：如果 QoS 大于代理所支持的。
MOSQ_ERR_OVERSIZE_PACKET：如果生成的数据包比代理支持的大。

(2)mosquitto_subscribe()

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

功能：向MQTT代理服务器订阅主题
参数：
mosq：指向Mosquitto客户端实例的指针
mid：用于存储消息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：如果生成的数据包比代理支持的大。

(3)mosquitto_unsubscribe()

int mosquitto_unsubscribe(struct mosquitto  *mosq, int *mid, const char *sub);

功能：退订主题
参数：
mosq：指向Mosquitto客户端实例的指针
mid：用于存储消息ID的整数指针
sub：要取消订阅的主题
返回值：
MOSQ_ERR_SUCCESS：成功
MOSQ_ERR_INVAL：如果输入参数无效
MOSQ_ERR_NOMEM：如果发生内存不足的情况
MOSQ_ERR_NO_CONN：如果客户端未连接到代理
MOSQ_ERR_MALFORMED_UTF8：如果主题不是有效的 UTF-8
MOSQ_ERR_OVERSIZE_PACKET：如果生成的数据包比代理支持的大

6.网络循环

(1)mosquitto_loop()

int mosquitto_loop（struct mosquitto *mosq, int timeoutm,  int max_packets）;

功能：循环处理Mosquitto客户端实例的网络流量
参数:
mosq：指向Mosquitto客户端实例的指针
timeout：超时时间（以毫秒为单位）
max_packets：处理的最大数据包数量
返回值：

7.回调函数

(1)mosquitto_connect_callback_set()

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

功能：设置连接回调，这在代理发送 CONNACK 消息以响应连接时调用。
回调函数：

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

参数：
mosq：有效的mosquitto实例，mosquitto_new()返回的mosq
obj：创建客户端时的回调函数（mosquitto_new中提供的用户数据）
rc：0表示连接成功，其他表示rc连接相应的返回码，其中有：
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命令并断开与客户端的连接，将调用此方法
回调函数：

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

参数：
mosq：有效的mosquitto实例，mosquitto_new()返回的mosq
obj：创建客户端时的回调函数
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))

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

void (*on_message)(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) )

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

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

参数：
mosq：有效的mosquitto实例，mosquitto_new()返回的mosq
obj：创建客户端时的回调函数(mosquitto_new中提供的用户数据)
mid：订阅消息的消息ID
qos_count：授予的订阅数（grant_qos大小）
granted：数据数组，指示每个订阅的已授予QoS