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
- MQTTAsync_create() : MQTTAsync.h
- MQTTAsync_createWithOptions() : MQTTAsync.h
- MQTTAsync_destroy() : MQTTAsync.h
- MQTTAsync_disconnect() : MQTTAsync.h
- MQTTAsync_free() : MQTTAsync.h
- MQTTAsync_freeMessage() : MQTTAsync.h
- MQTTAsync_getPendingTokens() : MQTTAsync.h
- MQTTAsync_getVersionInfo() : MQTTAsync.h
- MQTTAsync_global_init() : MQTTAsync.h
- MQTTAsync_isComplete() : MQTTAsync.h
- MQTTAsync_isConnected() : MQTTAsync.h
- MQTTAsync_malloc() : MQTTAsync.h
- MQTTAsync_reconnect() : MQTTAsync.h
- MQTTAsync_send() : MQTTAsync.h
- MQTTAsync_sendMessage() : MQTTAsync.h
- MQTTAsync_setAfterPersistenceRead() : MQTTAsync.h
- 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
- MQTTProperties_add() : MQTTProperties.h
- MQTTProperties_copy() : MQTTProperties.h
- MQTTProperties_free() : MQTTProperties.h
- MQTTProperties_getNumericValue() : MQTTProperties.h
- MQTTProperties_getNumericValueAt() : MQTTProperties.h
- MQTTProperties_getProperty() : MQTTProperties.h
- MQTTProperties_getPropertyAt() : MQTTProperties.h
- MQTTProperties_hasProperty() : MQTTProperties.h
- MQTTProperties_len() : MQTTProperties.h
- MQTTProperties_propertyCount() : MQTTProperties.h
- MQTTProperties_read() : MQTTProperties.h
- MQTTProperties_write() : MQTTProperties.h
- MQTTProperty_getType() : MQTTProperties.h
- MQTTPropertyName() : MQTTProperties.h
- MQTTReasonCode_toString() : MQTTReasonCodes.h