mosquitto常用函数简介

忘记哪里复制的。

1. MQTT 初始化
函数原型:

int mosquitto_lib_init(void)
功能：
使用mosquitto库函数前，要先初始化，使用之后就要清除。清除函数；int mosquitto_lib_cleanup()
返回值：MOSQ_ERR_SUCCESS

2. MQTT 清除
函数原型:

int mosquitto_lib_cleanup(void)
功能:
使用MQTT之后,清除工作
返回值MOSQ_ERR_SUCCESS

3. 新建客户端
函数原型:

struct mosquitto *mosquitto_new( const char * id, bool clean_session, void * obj )
参数
    id:如果为NULL，将生成一个随机客户端ID。如果id为NULL，clean_session必须为true。
    clean_session:设置为true以指示代理在断开连接时清除所有消息和订阅，设置为false以指示其保留它们，客户端将永远不会在断开连接时丢弃自己的传出消息就是断开后是否保留订阅信息true/false
	obj:用户指针，将作为参数传递给指定的任何回调
返回
成功时返回结构mosquitto的指针，失败时返回NULL，询问errno以确定失败的原因：ENOMEM内存不足。EINVAL输入参数无效。      

4. 释放客户端
函数原型:

void mosquitto_destroy( struct mosquitto * mosq)
功能
释放客户端
参数：mosq： struct mosquitto指针

5. 确认连接回调函数
函数原型:

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

功能：连接确认回调函数，当代理发送CONNACK消息以响应连接时，将调用此方法。
参数:
struct mosquitto * mosq:客户端通配符
void (*on_connect):回调函数
struct mosquitto *mosq:客户端数据
void *obj:创建客户端的回调参数(mosquitto_new中提供的用户数据)
int rc: 
0-成功
1-连接被拒绝（协议版本不可接受）
2-连接被拒绝（标识符被拒绝）
3-连接被拒绝（经纪人不可用）
4-255-保留供将来使用

6. 断开连接回调函数
函数原型:

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

功能：断开连接回调函数，当代理收到DISCONNECT命令并断开与客户端的连接，将调用此方法。
参数:
struct mosquitto *mosq:客户端
void (*on_disconnect):回调函数
 struct mosquitto *mosq:客户端数据
void *obj:创建客户端时的回调函数
int rc:表示断开原因(0表示客户端已经调用mosquitto_disconnect，任何其他值，表示断开连接时意外的)

7. 连接MQTT代理/服务器
函数原型:

int mosquitto_connect( struct mosquitto * mosq, const char * host, int port, int keepalive )
 功能: 连接到MQTT代理/服务器（主题订阅要在连接服务器之后进行）
 参数:
struct mosquitto * mosq:客户端
const char * host:服务器ip
int port:服务器端口号
int keepalive:保持连接的时间间隔， 单位秒 
返回：
MOSQ_ERR_SUCCESS 成功。
MOSQ_ERR_INVAL 如果输入参数无效。
MOSQ_ERR_ERRNO 如果系统调用返回错误。变量errno包含错误代码

8. 断开MQTT代理/服务器
函数原型:

int mosquitto_disconnect( struct mosquitto * mosq )
功能：断开与代理/服务器的连接。
返回：
MOSQ_ERR_SUCCESS 成功。
MOSQ_ERR_INVAL 如果输入参数无效。
MOSQ_ERR_NO_CONN 如果客户端未连接到代理。 

9. 发布主题
函数原型:

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

功能：主题发布的函数
参数:
struct mosquitto * mosq:客户端
int * mid:指向int的指针。如果不为NULL，则函数会将其设置为该特定消息的消息ID
const char * topic:要发布的主题,以'\0'结尾的字符串
int payloadlen:主题消息的内容长度
const void * payload:主题消息的内容，指向要发送的数据的指针，如果payloadlen >0，则它必须时有效的存储位置
int qos:整数值0、1、2指示要用于消息的服务质量
bool 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大于代理支持的QoS。
MOSQ_ERR_OVERSIZE_PACKET 如果结果包大于代理支持的包。

10. 订阅主题
函数原型:

int mosquitto_subscribe( struct mosquitto * mosq, int * mid, const char * sub, int qos )
参数:
struct mosquitto * mosq:客户端
int * mid:主题的消息ID。如果不为NULL，则函数会将其设置为该特定消息的消息ID
char * sub:主题名称，订阅模式
int qos:此订阅请求的服务质量
返回值：
MOSQ_ERR_SUCCESS 成功。
MOSQ_ERR_INVAL 如果输入参数无效。
MOSQ_ERR_NOMEM 如果发生内存不足的情况。
MOSQ_ERR_NO_CONN 如果客户端未连接到代理。
MOSQ_ERR_MALFORMED_UTF8 如果主题无效，则为UTF-8
MOSQ_ERR_OVERSIZE_PACKET 如果结果包大于代理支持的包

11. 消息回调函数
函数原型:

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

功能：消息回调函数，收到订阅的消息后调用。
参数:
struct mosquitto * mosq:客户端
(*on_message):void callback（struct mosquitto * mosq，void * obj，const struct mosquitto_message * message）
回调的参数
struct mosquitto * mosq:客户端
void * obj: mosquitto_new中提供的用户数据

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

12. MQTT循环调用/断开重新连接
函数原型:

int mosquitto_loop_forever( struct mosquitto * mosq, int timeout, int max_packets )
功能：此函数在无限阻塞循环中为你调用loop（），对于只想在程序中运行MQTT客户端循环的情况，这很有用，如果服务器连接丢失，它将处理重新连接，如果在回调中调用mosqitto_disconnect（）它将返回。
参数:
struct mosquitto * mosq: 客户端
int timeout:超时之前，在select（）调用中等待网络活动的最大毫秒数，设置为0以立即返回，设置为负可使用默认值为1000ms。
int 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包含错误代码

13. :网络事件阻塞回收结束处理
函数原型:

int mosquitto_loop_stop( struct mosquitto * mosq, bool force )

功能:网络事件阻塞回收结束处理函数，这是线程客户端接口的一部分。调用一次可停止先前使用mosquitto_loop_start创建的网络线程。该调用将一直阻塞，直到网络线程结束。为了使网络线程结束，您必须事先调用mosquitto_disconnect或将force参数设置为true。
参数:
struct mosquitto * mosq: 客户端
bool force:设置为true强制取消线程。如果为false，则必须已经调用mosquitto_disconnect。
返回：
MOSQ_ERR_SUCCESS 成功。
MOSQ_ERR_INVAL 如果输入参数无效。
MOSQ_ERR_NOT_SUPPORTED 如果没有线程支持

14. 网络事件循环处理
函数原型:

int mosquitto_loop_start( struct mosquitto * mosq )
功能：网络事件循环处理函数，通过创建新的线程不断调用mosquitto_loop() 函数处理网络事件，不阻塞
参数:
struct mosquitto * mosq:客户端
返回：
MOSQ_ERR_SUCCESS 成功。
MOSQ_ERR_INVAL 如果输入参数无效。
MOSQ_ERR_NOT_SUPPORTED 如果没有线程支持。

15. 配置用户名/密码
函数原型:

int mosquitto_username_pw_set(struct mosquitto *mosq, const char *username,  const char *passworp)
 参数
 struct mosquitto *mosq ：客户端
 const char *username ： 以字符串形式发送的用户名，或以NULL形式关闭认证。
 const char *passworp：以字符串形式发送的密码。 当用户名有效时，设置为NULL，以便只发送一个用户名。
 返回值
	成功时返回MOSQ_ERR_SUCCESS。
	如果输入参数无效，返回MOSQ_ERR_INVAL。
	如果发生内存不足的情况，返回MOSQ_ERR_NOMEM。

16.循环接受订阅发代理的内容
函数原型:

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

参数
    struct mosquitto *mosq :客户端
    int timeout:超时之前，在select（）调用中等待网络活动的最大毫秒数，设置为0以立即返回，设置为负可使用默认值为1000ms。
	int 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包含错误代码