MQTT学习记录（4）

常用API详解

mosquitto_lib_init

函数原型

int mosquitto_lib_init(void)

功能：使用mosquitto库函数前，要先初始化，使用之后就要清除。清除函数；int mosquitto_lib_cleanup();

返回值：MOSQ_ERR_SUCCESS 总是

mosquitto_lib_cleanup

函数原型

int mosquitto_lib_cleanup（void）

功能：使用完mosquitto函数之后，要做清除工作。

返回值： MOSQ_ERR_SUCCESS 总是

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 输入参数无效。

mosquitto_destroy

函数原型

void mosquitto_destroy( struct mosquitto * mosq )

功能：释放客户端

参数：

• mosq： struct mosquitto指针

mosquitto_connect_callback_set

函数原型

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

功能：
连接确认回调函数，当代理发送CONNACK消息以响应连接时，将调用此方法。

参数：

• mosq：客户端struct mosquitto指针

• void (*on_connect)(struct mosquitto *mosq, void *obj, int rc) ：回调函数
  回调函数参数：

  • mosq：客户端struct mosquitto指针
  • obj：mosquitto_new中提供的用户数据
  • rc：连接响应的返回码，其中有：
    0-成功
    1-连接被拒绝（协议版本不可接受）
    2-连接被拒绝（标识符被拒绝）
    3-连接被拒绝（经纪人不可用）
    4-255-保留供将来使用

mosquitto_disconnect_callback_set

函数原型

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

功能：断开连接回调函数，当代理收到DISCONNECT命令并断开与客户端的连接，将调用此方法。
参数：

• mosq：客户端struct mosquitto指针

• void (*on_connect)(struct mosquitto *mosq, void *obj, int rc) ：回调函数
  回调函数参数：

  • mosq：客户端struct mosquitto指针
  • obj：mosquitto_new中提供的用户数据
  • rc：连接响应的返回码，0表示客户端已经调用mosquitto_disconnect，任何其他值，表示断开连接时意外的。

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; //是否保留消息
};

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实例。
• on_subscribe 回调函数，格式如下：void (*on_subscribe)(struct mosquitto *mosq, void *obj, int mid, int qos_count, const int *granted_qos)
  回调的参数：
• mosq：进行回调的mosquitto实例
• obj： mosquitto_new中提供的用户数
• mid：订阅消息的消息ID
• qos_count：授予的订阅数（grant_qos的大小）
• granted_qos：整数数组，指示每个订阅的已授予QoS。

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。

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包含错误代码

mosquitto_disconnect

函数原型

int mosquitto_disconnect( struct mosquitto * mosq )

功能：断开与代理/服务器的连接。

返回：

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

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

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

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包含错误代码

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

mosquitto_loop_start

函数原型

int mosquitto_loop_start( struct mosquitto * mosq )

功能：网络事件循环处理函数，通过创建新的线程不断调用mosquitto_loop() 函数处理网络事件，不阻塞
参数：

• mosq :有效的mosquitto实例

返回：

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

其他API

下一节：MQTT学习记录（5）