MQTT--mosquitto库常见函数的使用

一、初始化和清理

（1）mosquitto_lib_init

int mosquitto_lib_init (NULL)

作用：初始化mosquitto，必须在任何其他mosqtto函数前使用它。

返回值：
MOSQ_ERR_SUCCESS：关于成功。
MOSQ_ERR_UNKNOWN：在 Windows 上，无法初始化套接字。

（2）mosquitto_lib_cleanup

int mosquitto_lib_cleanup (NULL)

作用：调用以释放与库关联的资源。

返回值：
MOSQ_ERR_SUCCESS 总是

二、客户端创建、销毁

（1）mosquitto_new

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

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

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

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

obj：将作为参数传递给任何指定回调的用户指针。为指向struct mosquitto结构体类型的指针。

返回值：
成功则指向struct mosquitto类型的指针。失败时为 NULL。可查询 errno 以确定失败的原因。

ENOMEM 内存不足。
无效输入参数的 EINVAL。

（2）mosquitto_destroy

void mosquitto_destroy(struct  mosquitto  *	mosq)

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

参数：指向需要free 的 struct mosquitto指针。

三、用户名和密码

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：如果发生内存不足的情况。

四、连接、重新连接、断开连接

（1）mosquitto_connect

作用：连接到 MQTT 代理。该功能适用​​于使用所有 MQTT 协议版本的客户端。

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

参数：
mosq：一个有效的mosquitto实例。
host：要连接的代理的主机名或 IP 地址。
port：要连接的网络端口。通常是 1883 。
keepalive：如果在这段时间内（秒数）没有交换其他消息，代理应该向客户端发送 PING 消息。

返回值：

MOSQ_ERR_SUCCESS：连接成功。
MOSQ_ERR_INVAL：如果输入参数无效，可以是以下任何一种：
mosq == NULL
host == 空
port < 0
keepalive < 5

MOSQ_ERR_ERRNO：如果系统调用返回错误。变量 errno 包含错误代码，即使在 Windows 上也是如此。在Linux情况下使用 strerror(errno) 或在 Windows 上使用 FormatMessage()。

（2）mosquitto_reconnect

int mosquitto_reconnect(struct 	mosquitto 	*mosq)

作用：重新连接到代理。此功能提供了一种在连接丢失后重新连接到代理的简单方法。它使用mosquitto_connect调用中提供的值。但不能在mosquitto_connect之前调用它。

参数：
mosq：一个有效的mosquitto实例。

返回值：
MOSQ_ERR_SUCCESS：关于成功。
MOSQ_ERR_INVAL：如果输入参数无效。
MOSQ_ERR_NOMEM：如果发生内存不足的情况。
MOSQ_ERR_ERRNO：如果系统调用返回错误。变量 errno 包含错误代码，即使在 Windows 上也是如此。在Linux下可使用 strerror(errno) 或在 Windows 上使用 FormatMessage()获取错误。

（3）mosquitto_disconnect

int mosquitto_disconnect(struct  mosquitto  *mosq)

作用：断开与代理的连接。该功能适用​​于使用所有 MQTT 协议版本的客户端。

参数：
mosq：一个有效的mosquitto实例

返回值：

MOSQ_ERR_SUCCESS：关于成功。
MOSQ_ERR_INVAL：如果输入参数无效。
MOSQ_ERR_NO_CONN：如果客户端未连接到代理

五、发布、订阅、取消订阅

（1）mosquitto_publish

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

作用：发布关于给定主题的消息。该功能适用​​于使用所有 MQTT 协议版本的客户端。如果需要设置 MQTT v5 PUBLISH 属性，请改用mosquitto_publish_v5。

参数：
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：如果 payloadlen 太大。
MOSQ_ERR_MALFORMED_UTF8：如果主题不是有效的 UTF-8
MOSQ_ERR_QOS_NOT_SUPPORTED：如果 QoS 大于代理所支持的。
MOSQ_ERR_OVERSIZE_PACKET：如果生成的数据包比代理支持的大。

（2）mosquitto_subscribe

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

作用：
订阅一个主题。该功能适用​​于使用所有 MQTT 协议版本的客户端。如果需要设置 MQTT v5 SUBSCRIBE 属性，请改用mosquitto_subscribe_v5。

参数：
mosq：一个有效的mosquitto实例。
mid：指向 int 的指针。如果不为 NULL，该函数会将其设置为此特定消息的消息 ID。然后可以将其与 subscribe 回调一起使用，以确定消息何时发送。
sub：订阅模式。
qos：服务质量，此订阅请求的服务质量。

返回值：
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：指向 int 的指针。如果不为 NULL，该函数会将其设置为此特定消息的消息 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：如果生成的数据包比代理支持的大。

六、网络循环（由 libmosquitto 管理）

必须定期调用内部网络循环。两种推荐的方法是使用mosquitto_loop_forever或mosquitto_loop_start。 mosquitto_loop_forever是一个阻塞调用，适用于你只想在回调中处理传入消息的情况。 mosquitto_loop_start是一个非阻塞调用，它创建一个单独的线程来为您运行循环。当您需要与 MQTT 客户端同时运行其他任务时使用此功能，例如从传感器读取数据。

（1）mosquitto_loop_forever

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

此函数在无限阻塞循环中为您调用 loop()。这对于您只想在程序中运行 MQTT 客户端循环的情况很有用。

**如果服务器连接丢失，它会处理重新连接。**如果您在回调中调用 mosquitto_disconnect()，它将返回。

参数：
mosq：一个有效的mosquitto实例。
timeout：在超时之前等待 select() 调用中的网络活动的最大毫秒数。设置为 0 以立即返回。设置负数以使用默认值 1000 毫秒。
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 包含错误代码，即使在 Windows 上也是如此。在Linux下使用 strerror(errno) 或在 Windows 上使用 FormatMessage()获取。

（2）mosquitto_loop_start

int mosquitto_loop_start( struct mosquitto *mosq)

作用：
这是线程客户端接口的一部分。调用一次以启动一个新线程来处理网络流量。这为重复调用mosquitto_loop提供了一种替代方法。

参数：
mosq：一个有效的mosquitto实例。

返回值：
MOSQ_ERR_SUCCESS：关于成功。
MOSQ_ERR_INVAL：如果输入参数无效。
MOSQ_ERR_NOT_SUPPORTED：如果线程支持不可用。

（3）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：线程支持不可用。

（4）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 消息流的一部分的命令。
这调用 select() 来监视客户端网络套接字。如果您想将 mosquitto 客户端操作与您自己的 select() 调用集成，请使用mosquitto_socket、mosquitto_loop_read、mosquitto_loop_write和mosquitto_loop_misc。

参数：
mosq：一个有效的mosquitto实例。
timeout：在超时之前等待 select() 调用中的网络活动的最大毫秒数。设置为 0 以立即返回。设置负数以使用默认值 1000 毫秒。
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 包含错误代码，即使在 Windows 上也是如此。在Linux下使用 strerror(errno) 或在 Windows 上使用 FormatMessage()获取。

七、回调

（1）mosquitto_connect_callback_set

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

作用：
设置连接回调。这在代理发送 CONNACK 消息以响应连接时调用。

参数：
mosq：一个有效的mosquitto实例。
on_connect：函数指针，以下形式的回调函数： void callback(struct mosquitto *mosq, void *obj, int rc)，在使用编写此回调函数时，一定要严格安装此参数和类型的要求。

回调参数
mosq：进行回调的 mosquitto 实例。
obj：mosquitto_new中提供的用户数据
rc：连接响应的返回码。这些值由使用的 MQTT 协议版本定义。

（2）mosquitto_disconnect_callback_set

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

作用：设置断开回调。当代理收到 DISCONNECT 命令并断开客户端的连接时调用。

参数：
mosq：一个有效的mosquitto实例。
on_disconnect：以下形式的回调函数：void callback(struct mosquitto *mosq, void *obj)

回调参数：
mosq：进行回调的 mosquitto 实例。
obj：mosquitto_new中提供的用户数据
rc：指示断开连接原因的整数值。值 0 表示客户端已调用mosquitto_disconnect。任何其他值表示断开是意外的。

（3）mosquitto_publish_callback_set

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

作用：
设置发布回调。当使用mosquitto_publish启动的消息已成功发送到代理时，将调用此方法。

参数：
mosq：一个有效的mosquitto实例。
on_publish：以下形式的回调函数： void callback(struct mosquitto *mosq, void *obj, int mid)

回调参数：
mosq：进行回调的 mosquitto 实例。
obj：mosquitto_new中提供的用户数据
mid：已发送消息的消息 ID。

（4）mosquitto_message_callback_set

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

作用：
设置消息回调。当从代理接收到消息时调用它。

参数：
mosq：一个有效的mosquitto实例。
on_message：以下形式的回调函数：void callback(struct mosquitto *mosq, void *obj, const struct mosquitto_message *message)

回调参数：
mosq：进行回调的 mosquitto 实例。
obj：mosquitto_new中提供的用户数据
message：消息数据。回调完成后，该变量和关联的内存将由库释放。客户应该复制它需要的任何数据。

（5）mosquitto_subscribe_callback_set

void mosquitto_subscribe_callback_set(struct  mosquitto 	*mosq,
void  (*on_subscribe)(struct mosquitto *, void *, int, int, const int *))

作用：
设置订阅回调。当代理响应订阅请求时调用。

参数：
mosq：一个有效的mosquitto实例。
on_subscribe：以下形式的回调函数： void callback(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 的大小）。
grant_qos：一个整数数组，指示每个订阅的授予 QoS。

（6）mosquitto_unsubscribe_callback_set

void mosquitto_unsubscribe_callback_set(struct 	mosquitto 	*mosq,
void (*on_unsubscribe)(struct mosquitto *, void *, int))

作用：
设置取消订阅回调。当代理响应取消订阅请求时调用它。

参数：
mosq：一个有效的mosquitto实例。
on_unsubscribe：以下形式的回调函数： void callback(struct mosquitto *mosq, void *obj, int mid)

回调参数：
mosq：进行回调的 mosquitto 实例。
obj：mosquitto_new中提供的用户数据
mid：取消订阅消息的消息 ID。

（7）mosquitto_log_callback_set

void mosquitto_log_callback_set(struct 	mosquitto 	*mosq,
void (*on_log)(struct mosquitto *, void *, int, const char *))

作用：
设置日志记录回调。如果您需要来自客户端库的事件日志信息，则应使用此选项。

清真寺 一个有效的mosquitto实例。
on_log 以下形式的回调函数： void callback(struct mosquitto *mosq, void *obj, int level, const char *str)

回调参数：
mosq：进行回调的 mosquitto 实例。
obj：mosquitto_new中提供的用户数据
level：来自值的日志消息级别： MOSQ_LOG_INFO、 MOSQ_LOG_NOTICE、 MOSQ_LOG_WARNING、 MOSQ_LOG_ERR、 MOSQ_LOG_DEBUG
str：消息字符串。

八、实用功能

mosquitto_strerror

const char *mosquitto_strerror(int 	mosq_errno)

作用：
调用以获取 mosquitto错误号的 const 字符串描述。

参数：
mosq_errno ：mosquitto错误编号。

返回值：
描述错误的常量字符串。

九、常见的返回值

MOSQ_ERR_INVAL=3
MOSQ_ERR_NOMEM=1
MOSQ_ERR_NO_CONN=4
MOSQ_ERR_MALFORMED_UTF8=18
MOSQ_ERR_OVERSIZE_PACKET=25
MOSQ_ERR_CONN_LOST=7 //如果与代理的连接丢失
MOSQ_ERR_PROTOCOL=2 //如果与代理通信时出现协议错误
MOSQ_ERR_ERRNO=14