Paho-MQTT C 库 API 接口

接口类型	头文件	备注
Paho MQTT C Client Library	MQTTClient.h	非线程安全
Paho Asynchronous MQTT C Client Library	MQTTAsync.h	线程安全

数据结构

typedef void* MQTTClient;
typedef void* MQTTAsync;

MQTTClient 库接口

MQTTClient_connect() : MQTTClient.h

int MQTTClient_connect(MQTTClient handle,
                       MQTTClient_connectOptions *options
)

此函数尝试使用指定的选项将以前创建的客户端（调用 MQTTClient_create() 函数）连接到 MQTT 服务器。如果要启用异步消息和状态通知，调用该函数之前必须先调用 MQTTClient_setCallbacks() 函数。

MQTTClient_connect5() : MQTTClient.h

MQTTResponse MQTTClient_connect5(MQTTClient handle,
                                 MQTTClient_connectOptions *options,
                                 MQTTProperties *connectProperties,
                                 MQTTProperties *willProperties 
)

此函数尝试使用 MQTT 版本 5.0 和指定的选项将以前创建的客户端（调用 MQTTClient_create() 函数）连接到 MQTT 服务器。如果要启用异步消息和状态通知，调用该函数之前必须先调用 MQTTClient_setCallbacks() 函数。

MQTTClient_create() : MQTTClient.h

int MQTTClient_create(MQTTClient *handle,
                      const char *serverURI,
                      const char *clientId,
                      int         persistence_type,
                      void *      persistence_context 
)

此函数创建一个 MQTT 客户端，以便连接到指定的服务器并使用指定的持久性存储（参考 MQTTClient_persistence 函数）。另外，与创建函数对应的是销毁函数 MQTTClient_destroy()。

MQTTClient_createWithOptions() : MQTTClient.h

int MQTTClient_createWithOptions(MQTTClient *handle,
                                 const char *serverURI,
                                 const char *clientId,
                                 int         persistence_type,
                                 void *      persistence_context,
                                 MQTTClient_createOptions *options 
)

此函数为 MQTTClient_create() 函数的带选项版本，用于创建一个 MQTT 客户端，以便连接到指定的服务器并使用指定的持久性存储（参考 MQTTClient_persistence 函数）。另外，与创建函数对应的是销毁函数 MQTTClient_destroy()。

MQTTClient_destroy() : MQTTClient.h

void MQTTClient_destroy(MQTTClient *handle)

此函数用于释放分配给 MQTT 客户端的内存（调用 MQTTClient_create() 函数）。当不再需要客户端时，应该调用它。

MQTTClient_disconnect() : MQTTClient.h

int MQTTClient_disconnect(MQTTClient handle, int timeout)

此函数尝试断开客户端与 MQTT 服务器的连接。为了让客户端有时间完成对调用此函数时正在传递的消息的处理，需要指定一个超时期限。当超时期限过期时，即使仍有未完成的消息确认，客户端也会断开连接。下一次客户端连接到同一服务器时，任何未完成的 QoS 1 或 2 消息将根据前一个连接和新连接的清理设置重试（参考 MQTTClient_connectOptions.cleansession 和 MQTTClient_connect()）。

MQTTClient_disconnect5() : MQTTClient.h

int MQTTClient_disconnect5(MQTTClient           handle,
                           int                  timeout,
                           enum MQTTReasonCodes reason,
                           MQTTProperties *     props 
)

此函数为 MQTTClient_disconnect() 函数的 MQTT 5.0 版本，用于尝试断开客户端与 MQTT 服务器的连接。

MQTTClient_free() : MQTTClient.h

void MQTTClient_free(void *ptr)

此函数释放 MQTT C Client 库分配的内存，特别是主题名称。当 client 库和应用程序使用不同版本的 C 编译器编译时，在 Windows 上需要这样做。因此，在释放任何 MQTT C Client 分配的内存时，始终使用此函数是一个很好的策略。

MQTTClient_freeMessage() : MQTTClient.h

void MQTTClient_freeMessage(MQTTClient_message ** msg)

此函数释放分配给 MQTT 消息的内存，包括分配给消息有效负载的附加内存。当完全处理消息时，客户端应用程序调用此函数。重要提示：此函数不释放分配给消息主题字符串的内存。客户端应用程序负责使用 MQTTClient_free() 库函数释放此内存。

MQTTClient_getPendingDeliveryTokens() : MQTTClient.h

int MQTTClient_getPendingDeliveryTokens(MQTTClient handle,
                                        MQTTClient_deliveryToken **tokens
)

此函数设置一个指针，该指针指向当前正在传递（等待完成）的消息的传递令牌数组。

重要提示：在这个函数中，用于保存令牌数组的内存是 malloc() 分配的。当不再需要此内存时，客户端应用程序要负责释放此内存。

MQTTClient_getVersionInfo() : MQTTClient.h

MQTTClient_nameValue* MQTTClient_getVersionInfo(void)

此函数返回 MQTT C Client 库的版本信息，但不会返回任何跟踪信息。

MQTTClient_global_init() : MQTTClient.h

void MQTTClient_global_init(MQTTClient_init_options *inits)

MQTT 库的全局初始化，在程序开始时调用一次以设置全局行为。例如 do_openssl_init —— 如果 mqtt 库应该初始化 OpenSSL，或者在使用库之前依赖调用者进行初始化。

MQTTClient_isConnected() : MQTTClient.h

int MQTTClient_isConnected(MQTTClient handle)

此函数允许客户端应用程序测试某个 client 与 MQTT 服务器连接情况，已连接返回 true，否则返回 false。

MQTTClient_publish() : MQTTClient.h

int MQTTClient_publish(MQTTClient                handle,
                       const char *              topicName,
                       int                       payloadlen,
                       const void *              payload,
                       int                       qos,
                       int                       retained,
                       MQTTClient_deliveryToken *dt
)

此函数试图将消息发布到给定主题（另请参见 MQTTClient_publishMessage 函数)。当此函数成功返回时，将发出 MQTTClient_deliveryToken。如果客户端应用程序需要测试 QoS1 和 QoS2 消息的成功传递，可以异步或同步地完成（参考异步与同步客户端应用程序、 MQTTClient_waitForCompletion 和 MQTTClient_deliveryComplete 函数）。

MQTTClient_publishMessage() : MQTTClient.h

int MQTTClient_publishMessage(MQTTClient                handle,
                              const char *              topicName,
                              MQTTClient_message *      msg,
                              MQTTClient_deliveryToken *dt
)

此函数试图将消息发布到给定主题（另请参见 MQTTClient_publish 函数）。当此函数成功返回时，将发出一个 MQTTClient_deliveryToken 令牌。如果客户端应用程序需要测试 QoS1 和 QoS2 消息的成功传递，可以异步或同步地完成（参考异步与同步客户端应用程序、 MQTTClient_waitForCompletion 和 MQTTClient_deliveryComplete 函数）。

MQTTClient_publish5() : MQTTClient.h

MQTTResponse MQTTClient_publish5(MQTTClient  handle,
                                 const char *topicName,
                                 int         payloadlen,
                                 const void *payload,
                                 int         qos,
                                 int         retained,
                                 MQTTProperties *properties,
                                 MQTTClient_deliveryToken *dt
)

此函数使用 MQTT 版本 5.0，试图将消息发布到给定主题（另请参见 MQTTClient_publishMessage5 函数）。当此函数成功返回时，将发出 MQTTClient_deliveryToken。如果客户端应用程序需要测试 QoS1 和 QoS2 消息的成功传递，可以异步或同步地完成（参考异步与同步客户端应用程序、 MQTTClient_waitForCompletion 和 MQTTClient_deliveryComplete 函数）。

MQTTClient_publishMessage5() : MQTTClient.h

MQTTResponse MQTTClient_publishMessage5(MQTTClient                handle,
                                        const char *              topicName,
                                        MQTTClient_message *      msg,
                                        MQTTClient_deliveryToken *dt
)

此函数使用 MQTT 版本 5.0，试图将消息发布到给定主题（另请参见 MQTTClient_publish5 函数）。当此函数成功返回时，将发出一个 MQTTClient_deliveryToken 令牌。如果客户端应用程序需要测试 QoS1 和 QoS2 消息的成功传递，可以异步或同步地完成（参考异步与同步客户端应用程序、 MQTTClient_waitForCompletion 和 MQTTClient_deliveryComplete 函数）。

MQTTClient_receive() : MQTTClient.h

int MQTTClient_receive(MQTTClient            handle,
                       char **               topicName,
                       int *                 topicLen,
                       MQTTClient_message ** message,
                       unsigned long         timeout
)

此函数执行传入消息的同步接收。只有当客户端应用程序没有设置回调方法以支持消息的异步接收时，才应该使用它（请参见异步与同步客户端应用程序以及 MQTTClient_setCallbacks 函数）。使用此函数可以编写单线程客户端订阅者应用程序。当调用时，此函数将阻塞，直到下一条消息到达或指定的超时过期为止（另请参见 MQTTClient_yield 函数）。

重要提示：应用程序在处理完成后必须释放分配给主题和消息的内存（请参见 MQTTClient_freeMessage 函数）。

MQTTClient_setCallbacks() : MQTTClient.h

int MQTTClient_setCallbacks(MQTTClient                    handle,
                            void *                        context,
                            MQTTClient_connectionLost *   cl,
                            MQTTClient_messageArrived *   ma,
                            MQTTClient_deliveryComplete * dc
)

此函数设置特定客户端的回调函数。如果客户端应用程序不使用特定的回调，请将相关参数设置为 NULL。调用 MQTTClient_setCallbacks() 将客户端置于多线程模式。任何必要的消息确认和状态通信都在后台处理，不需要客户端应用程序的任何干预。更多信息请参见异步与同步客户端应用程序。

注意：在调用此函数时，MQTT 客户端必须断开连接。

MQTTClient_setCommandTimeout() : MQTTClient.h

int MQTTClient_setCommandTimeout(MQTTClient    handle,
                                 unsigned long milliSeconds
)

设置在等待来自服务器的 un/suback 响应时，un/ordering 命令的超时值。milliSeconds 不允许小于 5000 的值。

MQTTClient_setDisconnected() : MQTTClient.h

int MQTTClient_setDisconnected(MQTTClient handle,
                               void *     context,
                               MQTTClient_disconnected *co 
)

设置客户端的 MQTTClient_disconnected() 回调函数。如果从服务器接收到断开连接的数据包，将调用这个函数。该函数只对 MQTT V5 及以上版本有效。

MQTTClient_setPublished() : MQTTClient.h

int MQTTClient_setPublished(MQTTClient             handle,
                            void *                 context,
                            MQTTClient_published * co
)

MQTTClient_setTraceCallback() : MQTTClient.h

void MQTTClient_setTraceCallback(MQTTClient_traceCallback *callback)

此函数在需要时设置跟踪回调。如果设置为 NULL，则不返回任何跟踪信息。默认的跟踪级别是 MQTTASYNC_TRACE_MINIMUM。

MQTTClient_setTraceLevel() : MQTTClient.h

void MQTTClient_setTraceLevel(enum MQTTCLIENT_TRACE_LEVELS level)

此函数设置将在跟踪回调中返回的跟踪信息的级别。

MQTTClient_strerror() : MQTTClient.h

void MQTTClient_setTraceCallback(MQTTClient_traceCallback *callback)

返回指向错误的字符串表示形式或 NULL 的指针。

使用后不要释放。如果错误代码未知，则返回 NULL。

MQTTClient_subscribe() : MQTTClient.h

int MQTTClient_subscribe(MQTTClient  handle,
                         const char *topic,
                         int         qos
)

此函数试图将客户端订阅到单个主题，该主题可能包含通配符（请参见订阅通配符）。此调用还指定为订阅请求的 QoS 服务质量（另请参见 MQTTClient_subscribeMany 函数）。

MQTTClient_subscribe5() : MQTTClient.h

MQTTResponse MQTTClient_subscribe5(MQTTClient             handle,
                                   const char *           topic,
                                   int                    qos,
                                   MQTTSubscribe_options *opts,
                                   MQTTProperties *       props 
)

此函数试图将 MQTT 5.0 版本客户端订阅到单个主题，该主题可能包含通配符（请参见订阅通配符）。此调用还指定为订阅请求的 QoS 服务质量（另请参见 MQTTClient_subscribeMany 函数）。

MQTTClient_subscribeMany() : MQTTClient.h

int MQTTClient_subscribeMany(MQTTClient    handle,
                             int           count,
                             char *const * topic,
                             int *         qos
)

此函数试图将客户端订阅到多个主题，这些主题可能包含通配符（请参见订阅通配符）。此调用还指定为订阅请求的 QoS 服务质量（另请参见 MQTTClient_subscribe 函数）。

MQTTClient_subscribeMany5() : MQTTClient.h

MQTTResponse MQTTClient_subscribeMany5(MQTTClient             handle,
                                       int                    count,
                                       char *const *          topic,
                                       int *                  qos,
                                       MQTTSubscribe_options *opts,
                                       MQTTProperties *       props
)

此函数试图将 MQTT 5.0 版本客户端订阅到多个主题，这些主题可能包含通配符（请参见订阅通配符）。此调用还指定为订阅请求的 QoS 服务质量（另请参见 MQTTClient_subscribe 函数）。

MQTTClient_unsubscribe() : MQTTClient.h

int MQTTClient_unsubscribe(MQTTClient  handle,
                           const char *topic
)

此函数试图删除由指定客户端创建的现有订阅。

MQTTClient_unsubscribe5() : MQTTClient.h

MQTTResponse MQTTClient_unsubscribe5(MQTTClient      handle,
                                     const char *    topic,
                                     MQTTProperties *props
)

此函数试图删除指定客户端使用 MQTT 5.0 进行的现有订阅。

MQTTClient_unsubscribeMany() : MQTTClient.h

int MQTTClient_unsubscribeMany(MQTTClient   handle,
                               int          count,
                               char *const *topic
)

此函数试图删除对指定客户端创建的主题列表的现有订阅。

MQTTClient_unsubscribeMany5() : MQTTClient.h

MQTTResponse MQTTClient_unsubscribeMany5(MQTTClient      handle,
                                         int             count,
                                         char *const *   topic,
                                         MQTTProperties *props
)

此函数试图删除对指定客户端使用 MQTT 5.0 版本创建的主题列表的现有订阅。

MQTTClient_waitForCompletion() : MQTTClient.h

int MQTTClient_waitForCompletion(MQTTClient               handle,
                                 MQTTClient_deliveryToken dt,
                                 unsigned long            timeout
)

此函数由客户端应用程序调用，以使主线程的执行与完成的消息发布同步。调用时，MQTTClient_waitForCompletion() 会阻止执行，直到消息成功传递或指定的超时过期为止。请参见异步客户端应用程序与同步客户端应用程序。

MQTTClient_yield() : MQTTClient.h

void MQTTClient_yield(void)

在实现单线程客户端时，定期调用此函数以允许处理消息重试并发送 MQTT 保持活动（keepalive）的 ping 包。如果应用程序定期调用 MQTTClient_receive()，则不需要调用此函数。

MQTTPropertyName() : MQTTProperties.h

const char* MQTTPropertyName(enum MQTTPropertyCodes value)

返回 MQTT V5 属性代码的可打印字符串说明。

MQTTReasonCode_toString() : MQTTReasonCodes.h

const char* MQTTReasonCode_toString(enum MQTTReasonCodes value)

返回 MQTT V5 原因代码的可打印字符串说明。

MQTTResponse_free() : MQTTClient.h

void MQTTResponse_free(MQTTResponse response)

释放与 MQTT 响应关联的存储空间。

MQTTAsync 库接口

MQTTAsync_connect() : MQTTAsync.h

int MQTTAsync_connect	(	MQTTAsync 	handle,
const MQTTAsync_connectOptions * 	options 
)	

MQTTAsync_create() : MQTTAsync.h

int MQTTAsync_create	(	MQTTAsync * 	handle,
const char * 	serverURI,
const char * 	clientId,
int 	persistence_type,
void * 	persistence_context 
)	

MQTTAsync_createWithOptions() : MQTTAsync.h

int MQTTAsync_createWithOptions	(	MQTTAsync * 	handle,
const char * 	serverURI,
const char * 	clientId,
int 	persistence_type,
void * 	persistence_context,
MQTTAsync_createOptions * 	options 
)	

MQTTAsync_destroy() : MQTTAsync.h

void MQTTAsync_destroy	(	MQTTAsync * 	handle	)	

MQTTAsync_disconnect() : MQTTAsync.h

int MQTTAsync_disconnect	(	MQTTAsync 	handle,
const MQTTAsync_disconnectOptions * 	options 
)	

MQTTAsync_free() : MQTTAsync.h

void MQTTAsync_free	(	void * 	ptr	)	

MQTTAsync_freeMessage() : MQTTAsync.h

void MQTTAsync_freeMessage	(	MQTTAsync_message ** 	msg	)	

MQTTAsync_getPendingTokens() : MQTTAsync.h

int MQTTAsync_getPendingTokens	(	MQTTAsync 	handle,
MQTTAsync_token ** 	tokens 
)	

MQTTAsync_getVersionInfo() : MQTTAsync.h

MQTTAsync_nameValue* MQTTAsync_getVersionInfo	(	void 		)

MQTTAsync_global_init() : MQTTAsync.h

void MQTTAsync_global_init	(	MQTTAsync_init_options * 	inits	)

MQTTAsync_isComplete() : MQTTAsync.h

int MQTTAsync_isComplete	(	MQTTAsync 	handle,
MQTTAsync_token 	token 
)	

MQTTAsync_isConnected() : MQTTAsync.h

int MQTTAsync_isConnected	(	MQTTAsync 	handle	)

MQTTAsync_malloc() : MQTTAsync.h

void* MQTTAsync_malloc	(	size_t 	size	)

MQTTAsync_reconnect() : MQTTAsync.h

int MQTTAsync_reconnect	(	MQTTAsync 	handle	)	

MQTTAsync_send() : MQTTAsync.h

int MQTTAsync_send	(	MQTTAsync 	handle,
const char * 	destinationName,
int 	payloadlen,
const void * 	payload,
int 	qos,
int 	retained,
MQTTAsync_responseOptions * 	response 
)

MQTTAsync_sendMessage() : MQTTAsync.h

int MQTTAsync_sendMessage	(	MQTTAsync 	handle,
const char * 	destinationName,
const MQTTAsync_message * 	msg,
MQTTAsync_responseOptions * 	response 
)

MQTTAsync_setAfterPersistenceRead() : MQTTAsync.h

int MQTTAsync_setAfterPersistenceRead	(	MQTTAsync 	handle,
void * 	context,
MQTTPersistence_afterRead * 	co 
)

MQTTAsync_setBeforePersistenceWrite() : MQTTAsync.h

MQTTAsync_setCallbacks() : MQTTAsync.h

MQTTAsync_setConnected() : MQTTAsync.h

MQTTAsync_setConnectionLostCallback() : MQTTAsync.h

MQTTAsync_setDeliveryCompleteCallback() : MQTTAsync.h

MQTTAsync_setDisconnected() : MQTTAsync.h

MQTTAsync_setMessageArrivedCallback() : MQTTAsync.h

MQTTAsync_setTraceCallback() : MQTTAsync.h

MQTTAsync_setTraceLevel() : MQTTAsync.h

MQTTAsync_setUpdateConnectOptions() : MQTTAsync.h

MQTTAsync_strerror() : MQTTAsync.h

MQTTAsync_subscribe() : MQTTAsync.h

MQTTAsync_subscribeMany() : MQTTAsync.h

MQTTAsync_unsubscribe() : MQTTAsync.h

MQTTAsync_unsubscribeMany() : MQTTAsync.h

MQTTAsync_waitForCompletion() : MQTTAsync.h

MQTTPropertyName() : MQTTProperties.h

MQTTReasonCode_toString() : MQTTReasonCodes.h

Paho-MQTT C 库 API 接口

数据结构​

MQTTClient 库接口​

MQTTAsync 库接口​

数据结构

MQTTClient 库接口

MQTTAsync 库接口