今天列举的API是我在做项目过程中会使用到的,在该博客我将全部记录下来:
常用函数
1、mosquitto_lib_init
int mosquitto_lib_init(void)
函数功能: 使用mosquitto库函数前, 要先初始化, 使用之后需要清除。
此函数不是线程安全的(线程安全:多个线程访问同一个对象时,调用这个对象的行为都可以获得正确的结果),也就是说mosquitto要第一个使用。
返回值:总是MOSQ_ERR_SUCCESS
2、mosquitto_lib_cleanup
int mosquitto_lib_cleanup(void)
作用:使用完mosquitto函数后,需要做清除工作
返回值:总是MOSQ_ERR_SUCCESS
3、mosquitto *mosquitto_new
struct mosquitto *mosquitto_new(const char *id, bool clean_session, void *obj)
作用:创建一个新的mosquitto客户端实例
参数:
①id:用作客户端id的字符串。如果为NULL, 生成一个随机的客户端id, 此时clean_session必须为true。
②clean_session: 若设置为true表示:代理(Broker)在断开时,客户端清除所有的消息和订阅;设置为false表示保留它们,客户端永远不会在断开时丢弃自己传出的消息。
③obj:用户指针,将作为参数传递给指定的任何回调(回调参数)
返回值:
成功:返回结构mosquitto的指针
失败:NULL
查询errno以确定失败的原因:
ENOMEM: 内存不足
EINVAL: 输入参数无效
4、mosquitto_destroy
void mosquitto_destroy(struct mosquitto *mosq)
作用: 用于释放与mosquitto客户端实例关联的内存
参数: 有效的mosquitto实例,mosquitto_new()返回的mosq,客户端
5、mosquitto_username_pw_set
int mosquitto_username_pw_set(struct mosquitto * mosq, const char *username, const char *password )
功能:为mosquitto实例配置用户名和密码,必须在调用mosquitto_connect之前调用这个参数。
参数:
①mosq:有效的mosquitto实例,mosquitto_new()返回的mosq
②username : 以字符串形式发送的用户名,或以NULL形式关闭认证
③password :以字符串形式发送的密码。 当用户名有效时,设置为NULL,以便只发送一个用户名。
返回值:
MOSQ_ERR_SUCCESS:成功
MOSQ_ERR_INVAL:输入参数无效
MOSQ_ERR_NOMEM:发生内存不足的情况
6、mosquitto_connect
int mosquitto_connect( struct mosquitto *mosq, const char *host, int port, int keepalive )
功能:连接到MQTT代理(Broker)/服务器
主题订阅要在连接服务器之后进行
参数:
①mosq:有效的mosquitto实例,mosquitto_new()返回的mosq,客户端
②host:服务器ip地址
③port:服务器的端口号
④keepalive: 保持连接的时间间隔,单位:秒
如果在这段时间内没有其他消息交换,则代理应该将PING消息发送到客户端的秒数
返回值:
MOSQ_ERR_SUCCESS :成功
MOSQ_ERR_INVAL :输入参数无效
MOSQ_ERR_ERRNO :系统调用返回错误
7、mosquitto_disconnect
int mosquitto_disconnect( struct mosquitto *mosq )
功能:断开代理与服务器的连接
返回值:
MOSQ_ERR_SUCCESS :成功。
MOSQ_ERR_INVAL :输入参数无效。
MOSQ_ERR_NO_CONN :客户端未连接到代理
8、mosquitto_publish
int mosquitto_publish( struct mosquitto *mosq, int *mid, const char *topic, int payloadlen, const void *payload, int qos, bool retain)
功能:发布主题
参数:
①mosq:有效的mosquitto实例,mosquitto_new()返回的mosq
②mid: 指向int的指针。如果不为NULL,则函数会将其设置为该特定消息的消息ID。然后可以将其与订阅回调一起使用,以确定何时发送消息
注意:尽管MQTT协议不对Qos = 0 的消息使用消息ID,但libmosquitto为其分配了消息ID,以便可以使用此参数对其进行跟踪。
③topic: 要发布的主题,以null结尾的字符串
④payloadlen:主题消息的内容长度
⑤payload:主题消息的内容,指向要发送数据的指针;
如果payloadlen > 0,其必须是有效的存储位置
⑥qos:消息服务质量,整数值0、1、2
⑦retain:是否要保留消息,true为保留,false为不保留
返回值:
MOSQ_ERR_SUCCESS :成功
MOSQ_ERR_INVAL :输入参数无效
MOSQ_ERR_NOMEM :发生内存不足的情况
MOSQ_ERR_NO_CONN :客户端未连接到代理
MOSQ_ERR_PROTOCOL:与代理进行通信时存在协议错误
MOSQ_ERR_PAYLOAD_SIZE:payloadlen太大
MOSQ_ERR_QOS_NOT_SUPPORTED:QoS大于代理支持的QoS
MOSQ_ERR_MALFORMED_UTF8 :主题无效,则为UTF-8
MOSQ_ERR_OVERSIZE_PACKET :结果包大于代理支持的包
9、mosquitto_subscribe
int mosquitto_subscribe( struct mosquitto *mosq, int *mid, const char *sub, int qos)
功能:订阅主题
参数:
①mosq:有效的mosquitto实例,mosquitto_new()返回的mosq
②mid: 指向int的指针。如果不为NULL,则函数会将其设置为该特定消息的消息ID。然后可以将其与订阅回调一起使用,以确定何时发送消息
③sub:主题的消息ID
④qos:消息服务质量,整数值0、1、2
返回值:
MOSQ_ERR_SUCCESS :成功
MOSQ_ERR_INVAL :输入参数无效
MOSQ_ERR_NOMEM :发生内存不足的情况
MOSQ_ERR_NO_CONN :客户端未连接到代理
MOSQ_ERR_QOS_NOT_SUPPORTED:QoS大于代理支持的QoS
MOSQ_ERR_MALFORMED_UTF8 :主题无效,则为UTF-8
MOSQ_ERR_OVERSIZE_PACKET :结果包大于代理支持的包
10、mosquitto_loop_start
int mosquitto_loop_start( struct mosquitto * mosq )
函数功能:网络事件循环处理函数,通过创建新的线程不断调用mosquitto_loop() 函数处理网络事件,不阻塞
返回值:
MOSQ_ERR_SUCCESS 成功。
MOSQ_ERR_INVAL 如果输入参数无效。
MOSQ_ERR_NOT_SUPPORTED 如果没有线程支持。
11、mosquitto_loop_forever
int mosquitto_loop_forever(struct mosquitto *mosq, int timeout, int max_packets)
功能:此函数在无限阻塞循环中调用loop(),对于只想在程序中运行MQTT客户端循环的情况,这很有用。
如果服务器断开,该函数会重新连接;若在回调中调用mosquitto_disconnect()它将返回
参数:
①mosq:有效的mosquitto实例,mosquitto_new()返回的mosq
②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包含错误代码
12、mosquitto_loop_stop
int mosquitto_loop_stop( struct mosquitto *mosq, bool force )
功能:网络事件阻塞回收结束处理函数,是线程客户端接口的一部分。
调用一次可停止先前使用mosquitto_loop_start创建的网络线程;该调用将一直阻塞,直到网络线程结束。
可以事先调用mosquitto_disconnect或将force参数设置为true,来使网络线程结束
参数:
①mosq:有效的mosquitto实例,mosquitto_new()返回的mosq
②force:
设为true表示:强制取消线程;若设为false,则必须已经调用mosquitto_disconnect
返回值:
MOSQ_ERR_SUCCESS:成功
MOSQ_ERR_INVAL:输入参数无效
MOSQ_ERR_NOT_SUPPORTED:没有线程支持
回调函数
1、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实例,mosquitto_new()返回的mosq
②回调函数,示例如下
void callback (struct mosquitto *mosq, void *obj, int rc)
回调的参数:
①mosq:有效的mosquitto实例,mosquitto_new()返回的mosq
②void *obj: 创建客户端时的回调参数(mosquitto_new中提供的用户数据)
③int rc: 0表示连接成功, 其他表示失败
rc连接响应的返回码, 其中有:
- 0-成功
- 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命令并断开与客户端的连接,将调用此方法
参数:
①mosq: 有效的mosquitto实例,mosquitto_new()返回的mosq,客户端
②回调函数,示例如下:
void callback (struct mosquitto *mosq, void *obj, int rc)
回调的参数:
①mosq:有效的mosquitto实例,mosquitto_new()返回的mosq
②void *obj: 创建客户端时的回调参数
③int 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) )
功能:消息回调函数,收到订阅的消息后调用
参数:
①mosq:有效的mosquitto实例,mosquitto_new()返回的mosq
②回调函数,格式如下:
void callback (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) )
功能: 设置订阅回调。当代理响应订阅请求时,将调用此方法
参数:
①mosq:有效的mosquitto实例,mosquitto_new()返回的mosq
②回调函数,格式如下:
void callback (struct mosquitto *mosq, void *obj, int mid, int qos_count, const int *granted_qos)
回调的参数:
①mosq:有效的mosquitto实例,mosquitto_new()返回的mosq
②void *obj: 创建客户端时的回调参数(mosquitto_new中提供的用户数据)
③mid:订阅消息的消息ID
④qos_count:授予的订阅数(grant_qos的大小)
⑤granted_qos:整数数组,指示每个订阅的已授予QoS。