mosquitto-1.4.5 基本接口函数解析

MQTT简述

MQTT（Message Queuing Telemetry Transport，消息队列遥测传输）是IBM开发的一个即时通讯协议，有可能成为物联网的重要组成部分。该协议支持所有平台，几乎可以把所有联网物品和外部连接起来，被用来当做传感器和致动器（比如通过Twitter让房屋联网）的通信协议。

MQTT协议是为大量计算能力有限，且工作在低带宽、不可靠的网络的远程传感器和控制设备通讯而设计的协议，它具有以下主要的几项特性：

1、使用发布/订阅消息模式，提供一对多的消息发布，解除应用程序耦合；

2、对负载内容屏蔽的消息传输；

3、使用 TCP/IP 提供网络连接；

4、有三种消息发布服务质量：

    “至多一次”，消息发布完全依赖底层 TCP/IP 网络。会发生消息丢失或重复。这一级别可用于如下情况，环境传感器数据，丢失一次读记录无所谓，因为不久后还会有第二次发送。

    “至少一次”，确保消息到达，但消息重复可能会发生。

    “只有一次”，确保消息到达一次。这一级别可用于如下情况，在计费系统中，消息重复或丢失会导致不正确的结果。

5、小型传输，开销很小（固定长度的头部是 2 字节），协议交换最小化，以降低网络流量；

6、使用 Last Will 和 Testament 特性通知有关各方客户端异常中断的机制；

      mosquitto是一款实现了消息推送协议 MQTT v3.1 的开源消息代理软件，提供轻量级的，支持可发布/可订阅的的消息推送模式，使设备对设备之间的短消息通信变得简单，比如现在应用广泛的低功耗传感器，手机、嵌入式计算机、微型控制器等移动设备。一个典型的应用案例就是 Andy Stanford-ClarkMosquitto（MQTT协议创始人之一）在家中实现的远程监控和自动化。

     下面我将对mosquitto中基本的函数进行简单讲解。

常用接口  （mosquitto-1.4.5/lib/mosquito.h）

消息结构体

struct mosquitto_message{

int mid;

char *topic; //主题

void *payload; //消息内容

int payloadlen; //消息的长度

int qos; //服务质量

bool retain;

};

1．客户端创建之前调用此函数

此函数不是线程安全的.

返回值:

MOSQ_ERR_SUCCESS - always

libmosq_EXPORT int mosquitto_lib_init(void);

2.释放资源.

返回值:

MOSQ_ERR_SUCCESS - always

libmosq_EXPORT int mosquitto_lib_cleanup(void);

3.创建一个新的客户端结构体

参数:

id -    客户端的id，如果设置为NULL,将会随机生成一个id，并且clean_session必须设置为true。           

clean_session –   设置为ture，该客户端disconnect之后，broker会清理改客户端的所有发送，订阅信息，f设置为false，broker会保留

obj -           A user pointer that will be passed as an argument to any

                  callbacks that are specified.

 返回值s:

 * Pointer to a struct mosquitto on success.

 * NULL on failure. Interrogate errno to determine the cause for the failure:

 *      - ENOMEM on out of memory.

 *      - EINVAL on invalid input parameters.

struct mosquitto *mosquitto_new(const char *id, bool clean_session, void *obj);

4.释放客户端结构体资源.

void mosquitto_destroy(struct mosquitto *mosq);

5.连接到MQTT代理

参数:

 * mosq -      客户端结构体.

 * host -      broker端ip地址.

 * port -      broker端口. 通常为1883.

 * keepalive - the number of seconds after which the broker should send a PING

 *              message to the client if no other messages have been exchanged

 *              in that time.

 *

 * Returns:

 * MOSQ_ERR_SUCCESS - on success.

 * MOSQ_ERR_INVAL -   if the input parameters were invalid.

 * MOSQ_ERR_ERRNO -   if a system call returned an error. The variable errno

 *                     contains the error code, even on Windows.

 *                     Use strerror_r() where available or FormatMessage() on

 *                     Windows.

int mosquitto_connect(struct mosquitto *mosq, const char *host, int port, int keepalive);

6.断开连接.

 返回值:

MOSQ_ERR_SUCCESS - on success.

  MOSQ_ERR_INVAL -   if the input parameters were invalid.

  MOSQ_ERR_NO_CONN -  if the client isn't connected to a broker.

int mosquitto_disconnect(struct mosquitto *mosq)

7.订阅主题

参数:

* mid -  a pointer to an int. If not NULL, the function will set this to

 *        the message id of this particular message. This can be then used

 *        with the subscribe callback to determine when the message has been

 *        sent.

 * sub -  主题.

 * qos -  服务质量

 *

 * 返回值:

 * MOSQ_ERR_SUCCESS - on success.

 * MOSQ_ERR_INVAL -   if the input parameters were invalid.

 * MOSQ_ERR_NOMEM -   if an out of memory condition occurred.

 * MOSQ_ERR_NO_CONN - if the client isn't connected to a broker.

 */

int mosquitto_subscribe(struct mosquitto *mosq, int *mid, const char *sub, int qos);

8.退订主题

int mosquitto_unsubscribe(struct mosquitto *mosq, int *mid, const char *sub);

9.发送主题

参数：

mid - pointer to an int. If not NULL, the function will set this

              to the message id of this particular message. This can be then

              used with the publish callback to determine when the message

              has been sent

topic-主题

payloadlen-发送消息的长度

payload-发送的消息

qos-服务质量

retain-是否保留消息

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

9.客户端线程函数

调用此函数开启一个线程用于处理相关网络服务

int mosquitto_loop_start(struct mosquitto *mosq)

10．停止线程

* This is part of the threaded client interface. Call this once to stop the

 * network thread previously created with <mosquitto_loop_start>. This call

 * will block until the network thread finishes. For the network thread to end,

 * you must have previously called <mosquitto_disconnect> or have set the force

 * parameter to true.

 *

 * Parameters:

 *  mosq - a valid mosquitto instance.

 * force - set to true to force thread cancellation. If false,

 *         <mosquitto_disconnect> must have already been called.

 *

 * Returns:

 * MOSQ_ERR_SUCCESS -       on success.

 * MOSQ_ERR_INVAL -         if the input parameters were invalid.

 * MOSQ_ERR_NOT_SUPPORTED - if thread support is not available.

int mosquitto_loop_stop(struct mosquitto *mosq, bool force)

11.回调函数

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

void mosquitto_subscribe_callback_set(struct mosquitto *mosq, void (*on_subscribe)(struct mosquitto *, void *, int, int, const int *));

void mosquitto_unsubscribe_callback_set(struct mosquitto *mosq, void (*on_unsubscribe)(struct mosquitto *, void *, int))

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

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

void mosquitto_publish_callback_set(struct mosquitto *mosq, void (*on_publish)(struct mosquitto *, void *, int))

流程

mosquitto_lib_init();

mosq = mosquitto_new(NULL, session, NULL);

if(!mosq){

printf("Failed to mosquitto_new\n");

mosquitto_lib_cleanup();

return 1;

}

if(mosquitto_connect(mosq, HOST, PORT, KEEP_ALIVE)){

printf("Failed to mosquitto_connect\n");

return 1;

}

int loop = mosquitto_loop_start(mosq);

if(loop != MOSQ_ERR_SUCCESS){

printf("Failed to mosquitto_loop_start\n");

return 1;

}

mosquitto_subscribe(mosq, NULL, "sub", 0); //订阅主题，消息的接收在回调函数中

mosquitto_message_callback_set(mosq, my_message_callback);

mosquitto_publish(mosq, NULL, "pub", strlen(buf)+1, buf, 0, 0);

mosquitto_disconnect(mosq);

mosquitto_loop_stop(mosq, 0);

mosquitto_destroy(mosq);

mosquitto_lib_cleanup();