mosquitto常见库函数总结

int mosquitto_lib_init(NULL) 

功能：初始化mosquitto，一定是别的mosqtto使用函数前。

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

int mosquitto_lib_cleanup (NULL) 

功能:调用与库相关的资源释放。

返回值： MOSQ_ERR_SUCCESS 总是

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。

void mosquitto_destroy(struct  mosquitto  * mosq) 

void mosquitto_destroy(struct mosquitto * mosq) 功能：用于释放和释放 mosquitto 与客户端实例相关的内存。

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

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：若内存不足。

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()。

int mosquitto_disconnect(struct  mosquitto  *mosq)

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

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

返回值：

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

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：如果生成的数据包比代理支持的大。

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：如果生成的数据包比代理支持的大。

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：如果生成的数据包比代理支持的大。

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()获取。

int mosquitto_loop_start( struct mosquitto *mosq)

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

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

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

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

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()获取。

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 协议版本定义。

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,int rc)

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

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。

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：消息数据。回调完成后，该变量和关联的内存将由库释放。客户应该复制它需要的任何数据。

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

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。

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。

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：消息字符串。

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