mosquitto库函数详解

Posted Shemesz

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了mosquitto库函数详解相关的知识,希望对你有一定的参考价值。


了解了 MQTT协议,就会知道mosquitto库,通过这个库即可实现MQTT协议的订阅/发布模型,了解mosquitto库更多API请点击这里:
https://mosquitto.org/api/files/mosquitto-h.html

(1)mosquitto_lib_init

  • 函数原型
int mosquitto_lib_init(void)
  • 功能:使用mosquitto库函数前,要先初始化,使用之后就要清除。清除函数;int mosquitto_lib_cleanup();

  • 返回值:MOSQ_ERR_SUCCESS 总是

(2)mosquitto_lib_cleanup

  • 函数原型
int mosquitto_lib_cleanup(void
  • 功能:使用完mosquitto函数之后,要做清除工作。

  • 返回值: MOSQ_ERR_SUCCESS 总是

(3)mosquitto_new

  • 函数原型
struct mosquitto *mosquitto_new( const char * id, bool clean_session, void * obj )
  • 功能:创建一个新的mosquitto客户端实例,新建客户端

    参数:
    ①id :用作客户端ID的字符串。如果为NULL,将生成一个随机客户端ID。如果id为NULL,clean_session必须为true。
    ②clean_session:设置为true以指示代理在断开连接时清除所有消息和订阅,设置为false以指示其保留它们,客户端将永远不会在断开连接时丢弃自己的传出消息。调用mosquitto_connect或mosquitto_reconnect将导致重新发送消息。使mosquitto_reinitialise将客户端重置为其原始状态。如果id参数为NULL,则必须将其设置为true。简言之:就是断开后是否保留订阅信息true/false
    ③obj: 用户指针,将作为参数传递给指定的任何回调,(回调参数)
    
  • 返回值:成功时返回结构mosquitto的指针,失败时返回NULL,询问errno以确定失败的原因:

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

(4)mosquitto_destroy

  • 函数原型
void mosquitto_destroy( struct mosquitto * mosq )
  • 功能:释放客户端

  • 参数:mosq: struct mosquitto指针

(5)mosquitto_connect_callback_set

  • 函数原型
void mosquitto_connect_callback_set(struct mosquitto * mosq, void (*on_connect)(struct mosquitto *mosq, void *obj, int rc) )
  • 功能连接确认回调函数,当代理发送CONNACK消息以响应连接时,将调用此方法。

  • 参数

在这里插入图片描述

  • obj:mosquitto_new中提供的用户数据

  • rc 连接响应的返回码,其中有:

     0-成功
     1-连接被拒绝(协议版本不可接受)
      2-连接被拒绝(标识符被拒绝)
      3-连接被拒绝(经纪人不可用)
      4-255-保留供将来使用
    

(6)mosquitto_disconnect_callback_set

  • 函数原型
void mosquitto_disconnect_callback_set( struct mosquitto *mosq,void (*on_disconnect)( struct mosquitto *mosq,void *obj, int rc) );
  • 功能:断开连接回调函数,当代理收到DISCONNECT命令并断开与客户端的连接,将调用此方法。

  • 参数
    在这里插入图片描述

  • rc:0表示客户端已经调用mosquitto_disconnect,任何其他值,表示断开连接时意外的。

(7)mosquitto_username_pw_set

  • 函数原型
 int mosquitto_username_pw_set(struct mosquitto *	mosq, const char *username,  const char *password	)
  • 功能:为mosquitto实例配置用户名和密码,必须在调用mosquitto_connect之前调用这个参数。

  • 参数

     ①mosq :一个有效的mosquitto实例。
     ②username : 以字符串形式发送的用户名,或以NULL形式关闭认证。
     ③password :以字符串形式发送的密码。 当用户名有效时,设置为NULL,以便只发送一个用户名。
    
  • 返回

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

(8)mosquitto_connect

  • 函数原型
int mosquitto_connect( struct mosquitto * mosq, const char * host, int port, int keepalive )
  • 功能: 连接到MQTT代理/服务器(主题订阅要在连接服务器之后进行)

  • 参数

       ①mosq : 有效的mosquitto实例,mosquitto_new()返回的mosq.
       ②host : 服务器ip地址
       ③port:服务器的端口号
       ④keepalive:保持连接的时间间隔, 单位秒。如果在这段时间内没有其他消息交换,则代理应该将PING消息发送到客户端的秒数。
    
  • 返回

    MOSQ_ERR_SUCCESS 成功。
    MOSQ_ERR_INVAL 如果输入参数无效。
    MOSQ_ERR_ERRNO 如果系统调用返回错误。变量errno包含错误代码
    

(9)mosquitto_disconnect

  • 函数原型
int mosquitto_disconnect( struct mosquitto * mosq )
  • 功能:断开与代理/服务器的连接。

  • 返回

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

(10)mosquitto_publish

  • 函数原型
int mosquitto_publish( struct mosquitto * mosq, int * mid, const char * topic, int payloadlen, const void * payload, int qos, bool retain )
  • 功能:主题发布的函数

  • 参数

    ①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大于代理支持的QoS。
    MOSQ_ERR_OVERSIZE_PACKET 如果结果包大于代理支持的包。
    

(11)mosquitto_subscribe

  • 函数原型
int mosquitto_subscribe( struct mosquitto * mosq, int * mid, const char * sub, int qos )
  • 功能:订阅主题函数

  • 参数

    ①mosq:有效的mosquitto实例,客户端
    ②mid: 指向int的指针。如果不为NULL,则函数会将其设置为该特定消息的消息ID。然后可以将其与订阅回调一起使用,以确定何时发送消息。;主题的消息ID
    ③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 如果结果包大于代理支持的包。
    

(12)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实例,客户端。
    ②on_message 回调函数,格式如下:void callback(struct mosquitto * mosq,void * obj,const struct mosquitto_message * message)
    
  • 回调的参数

     ①mosq:进行回调的mosquitto实例
     ②obj: mosquitto_new中提供的用户数
     ③message: 消息数据,回调完成后,库将释放此变量和关联的内存,客户应复制其所需要的任何数据。
    
  • struct mosquitto_message结构体

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

(13)mosquitto_loop_forever

  • 函数原型
int mosquitto_loop_forever( struct mosquitto * mosq, int timeout, int max_packets )
  • 功能:此函数在无限阻塞循环中为你调用loop(),对于只想在程序中运行MQTT客户端循环的情况,这很有用,如果服务器连接丢失,它将处理重新连接,如果在回调中调用mosqitto_disconnect()它将返回。

  • 参数

    ①mosq: 有效的mosquitto实例,客户端
    ②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包含错误代码
    

(14)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 如果没有线程支持。
    

(15)mosquitto_loop_start

  • 函数原型
int mosquitto_loop_start( struct mosquitto * mosq )
  • 功能:网络事件循环处理函数,通过创建新的线程不断调用mosquitto_loop() 函数处理网络事件,不阻塞

  • 返回

    MOSQ_ERR_SUCCESS 成功。 
    MOSQ_ERR_INVAL 如果输入参数无效。 
    MOSQ_ERR_NOT_SUPPORTED 如果没有线程支持。
    

以上是关于mosquitto库函数详解的主要内容,如果未能解决你的问题,请参考以下文章

python MQTT消息中间件mosquitto 消息获取(从MQTT服务器取消息)

基于mosquitto库实现MQTT订阅与发布

MQTT--mosquitto实现发布与订阅

MQTT服务器(Broker) - mosquitto配置文件详解

通过理解函数指针构建回调函数来实现mosquitto源码功能

通过理解函数指针构建回调函数来实现mosquitto源码功能