认识mosquitto的一些API函数

普通函数

int mosquitto_lib_init( void )必须在任何其他mosquito函数之前调用。
此函数不是线程安全的。也就是说mosquitto要第一个使用，返回值总是
MOSQ_ERR_SUCCESS

struct mosquitto *mosquitto_new( const char * id, bool clean_session, void * obj )创建一个新的客户端实例，第一个参数id为客户端的clientid，第二个参数设置为true指示代理在断开连接时清除所有消息和订阅，设置为false指示代理保留它们。如果id参数为NULL，则必须将其设置为true，第三个参数将作为参数传递给指定的任何回调的用户指针。后面传进回调函数的指针

int mosquitto_lib_cleanup( void )释放调用的资源和相关的库，返回值总是为MOSQ_ERR_SUCCESS

void mosquitto_destroy( struct mosquitto * mosq )用于释放与mosquitto客户端实例关联的内存，第一个参数为mosquitto创建实例返回的mosq指针。

int mosquitto_username_pw_set( struct mosquitto * mosq, const char * username, const char * password )配置mosquito实例的用户名和密码。默认情况下，不会发送用户名或密码。对于v3.1和v3.1.1客户端，如果username为NULL，则忽略password参数。在调用mosquitto\u connect之前必须调用此函数。如果代理支持无用户密码的连接可以不使用此函数
。第一个参数为mosquitto_new的返回值，第二个为用户名，第三个为密码。返回值：
MOSQ_ERR_SUCCESS 成功。
MOSQ_ERR_INVAL 如果输入参数无效。
MOSQ_ERR_NOMEM 如果发生内存不足的情况。

int mosquitto_connect( struct mosquitto * mosq, const char * host, int port, int keepalive )连接MQTT代理，第一个参数为mosquitto_new创建的实例， 第二个为代理的网络地址（IP地址或者域名），第三个为对应代理的端口，第4个为心跳连接，也就是如果设定时间内没有其他消息交换，则代理应该向客户机发送PING消息。返回值
MOSQ_ERR_SUCCESS 成功。
MOSQ_ERR_INVAL 如果输入参数无效。
MOSQ_ERR_ERRNO 如果系统调用返回错误。变量errno包含错误代码，即使在Windows上也是如此。在可用的地方使用strerror_r（）或在Windows上使用FormatMessage（）。

int mosquitto_publish( struct mosquitto * mosq, int * mid,const char * topic,int payloadlen,const void * payload,int qos,bool retain )发布关于给定主题的消息。第一个参数为创建的mosquitto实例，第二个为指向int的指针。如果不为NULL，则函数会将其设置为该特定消息的消息ID。然后可以将其与发布回调一起使用，以确定何时发送消息。请注意，尽管MQTT协议不对QoS = 0的消息使用消息ID，但libmosquitto为其分配了消息ID，以便可以使用此参数对其进行跟踪。 第三个为要发布到的主题的以null结尾的字符串。第四个为有效负载的大小（字节）。有效值在0到268,435,455之间。指向要发送的数据的指针，也就是发送的内容，第五个为QoS也就是服务质量等级，第七个为是否要保留消息，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_MALFORMED_UTF8 如果主题无效，则为UTF-8
MOSQ_ERR_QOS_NOT_SUPPORTED 如果QoS大于代理支持的QoS。
MOSQ_ERR_OVERSIZE_PACKET 如果结果包大于代理支持的包。

int mosquitto_subscribe( struct mosquitto * mosq,int * mid,const char * sub,int qos )订阅一个主题，第一个参数为创建的mosquitto实例，第二个为指向int的指针。如果不为NULL，则函数会将其设置为该特定消息的消息ID。然后可以将其与订阅回调一起使用，以确定何时发送消息。
第三个为订阅的模式也就是主题，第4个为通信服务质量。

int mosquitto_loop_forever( struct mosquitto * mosq,int timeout,int max_packets )此函数在无限阻塞循环中为您调用loop（）。对于只想在程序中运行MQTT客户机循环的情况，它非常有用。它处理服务器连接丢失时的重新连接。如果在回调中调用mosquitto_u disconnect（），它将返回。第一个参数为新建的moaquitto实例，第二个为在超时之前等待select（）调用中的网络活动的最大毫秒数。设置为0以立即返回。设置为负值以使用默认值1000毫秒。第三个为当前并未使用，保留，应该设为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包含错误代码，即使在Windows上也是如此。在可用的地方使用strerror_r（）或在Windows上使用FormatMessage（）。

设置相应的回调函数

每个被回调的函数的参数都是一样的void (*on_connect)(struct mosquitto *, void *, int)第一个参数进行回调的mosquitto实例， mosquitto_new中提供的用户数据，连接响应的返回码，其中之一：
0-成功
1-连接被拒绝（协议版本不可接受）
2-连接被拒绝（标识符被拒绝）
3-连接被拒绝（经纪人不可用）
4-保留供将来使用

void mosquitto_connect_callback_set(struct mosquitto * mosq,void (*on_connect)(struct mosquitto *, void *, int))设置连接回调。当代理发送CONNACK消息以响应连接时，将调用此函数完成某项事情。第一个为mosquitto的实例，第二个参数回调的函数。

void mosquitto_publish_callback_set(struct mosquitto * mosq,void (*on_publish)(struct mosquitto *, void *, int))设置发布回调。当以mosquitto_publish发起的消息已成功发送到代理时，将调用此方法。具体参数与上面相同

void mosquitto_subscribe_callback_set(struct mosquitto * mosq,void (*on_subscribe)(struct mosquitto *, void *, int, int, const int *，))设置订阅回调。当代理响应订阅请求时，将调用此方法，第二个参数的函数的参数第一个和第二个和上面相同，第三个为订阅消息的消息ID，第四个为授予的订阅数（grant_qos的大小），第5个为整数数组，指示每个订阅的已授予QoS。

void mosquitto_message_v5_callback_set(struct mosquitto * mosq,void (*on_message)(struct mosquitto *, void *, const struct mosquitto_message *, const mosquitto_property *))设置消息回调。当从代理接收到消息时，将调用此方法，第一个参数进行回调的mosquitto实例，第二个为mosquitto_new中提供的用户数据，第三个为消息数据。回调完成后，库将释放此变量和关联的内存。客户应复制其所需的任何数据。具体的mosquitto_message结构体如下：

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

上面的则是比较常用的mosquitto函数，这篇博客主要是整理了函数的使用，下篇博客将进行编程。
参考链接：https://mosquitto.org/api/files/mosquitto-h.html