tencent cloud

消息队列 MQTT 版

动态与公告
新功能发布记录
产品简介
TDMQ 产品系列介绍与选型
什么是消息队列 MQTT 版
应用场景
技术架构
产品系列
MQTT 协议兼容说明
开源对比
高可用
产品约束与使用配额
基本概念
开服地域
购买指南
计费概述
续费说明
查看消费明细
欠费说明
退费说明
快速入门
入门流程指引
准备工作
公网接入
VPC 网络接入
用户指南
使用流程指引
配置账号权限
新建集群
管理 Topic
连接集群
查询消息
管理客户端
管理集群
查看监控和配置告警
数据集成
集成数据到云函数 SCF
集成数据到 CKafka
集成数据到 RocketMQ
开发指南
MQTT 5 高级特性
数据面 HTTP 接口说明
配置自定义域名
配置 SQL 过滤
配置点对点订阅
MQTT over QUIC
管理客户端订阅
消息增强规则
实践教程
MQTT 客户端开发注意事项
可观测能力
Topic 与通配符订阅
API 参考
History
Introduction
API Category
Making API Requests
Cluster APIs
Topic APIs
Authorization Policy APIs
User APIs
Client APIs
Message Enhancement Rule APIs
Message APIs
Data Types
Error Codes
SDK 参考
接入点格式
Java SDK
C SDK
Javascript/Node.JS/小程序
Go SDK
iOS SDK
JavaScript SDK
Dart SDK
Python SDK
.NET
安全与合规
权限管理
常见问题
相关协议
隐私协议
数据处理和安全协议
消息队列 MQTT 版服务等级协议
联系我们
文档消息队列 MQTT 版SDK 参考C SDK

C SDK

聚焦模式
字号
最后更新时间： 2026-01-30 15:23:30

功能概述

Eclipse Paho C 与 Eclipse Paho Embedded C 均为 Eclipse Paho 项目下的 C 语言客户端库（MQTT C Client），均为使用 ANSI C 编写的功能齐全的 MQTT 客户端。
Eclipse Paho Embedded C 可以在桌面操作系统上使用，但主要针对 Mbed，Arduino和 FreeRTOS 等嵌入式环境。
该客户端有同步/异步两种 API ，分别以 MQTTClient 和 MQTTAsync 开头：
同步 API 旨在更简单，更有用，某些调用将阻塞直到操作完成为止，使用编程上更加容易。
异步 API 中只有一个调用块 API-waitForCompletion ，通过回调进行结果通知，更适用于非主线程的环境。

云资源准备

请您先参见 创建资源 操作步骤完成云资源准备。

环境准备

注意：
Paho MQTT C SDK 需要 CMake 版本3.5+。

安装 paho.mqtt.c SDK 示例

 cd paho.mqtt.c && cmake .
 make && make install
 echo '/usr/local/lib64' > /etc/ld.so.conf.d/paho.conf
 echo '/usr/local/lib' >> /etc/ld.so.conf.d/paho.conf
 ldconfig

示例代码

将下面内容复制到 /root/mqtt-example.c
#include "stdio.h"
#include "stdlib.h"
#include "string.h"

#include "MQTTClient.h"

#define ADDRESS     "tcp://mqtt-********.mqtt.tencenttdmq.com:1883"
#define CLIENTID    "sample_client"
#define TOPIC       "testtopic/1"
#define PAYLOAD     "Hello World!"
#define QOS         1
#define TIMEOUT     10000L
#define USERNAME    "your-username"
#define PASSWORD    "your-password"

int main(int argc, char* argv[])
{
    MQTTClient client;
    MQTTClient_connectOptions conn_opts = MQTTClient_connectOptions_initializer;
    MQTTClient_message pubmsg = MQTTClient_message_initializer;
    MQTTClient_deliveryToken token;
    int rc;

    MQTTClient_create(&client, ADDRESS, CLIENTID,
        MQTTCLIENT_PERSISTENCE_NONE, NULL);
  
    // MQTT 连接参数
    conn_opts.keepAliveInterval = 20;
    conn_opts.cleansession = 1;
    conn_opts.MQTTVersion = MQTTVERSION_3_1_1;
    conn_opts.username = USERNAME;
    conn_opts.password = PASSWORD;

    if ((rc = MQTTClient_connect(client, &conn_opts)) != MQTTCLIENT_SUCCESS)
    {
        printf("Failed to connect, return code %d\\n", rc);
        exit(-1);
    }
  
    // 发布消息
    pubmsg.payload = PAYLOAD;
    pubmsg.payloadlen = strlen(PAYLOAD);
    pubmsg.qos = QOS;
    pubmsg.retained = 0;
    MQTTClient_publishMessage(client, TOPIC, &pubmsg, &token);
    printf("Waiting for up to %d seconds for publication of %s\\n"
            "on topic %s for client with ClientID: %s\\n",
            (int)(TIMEOUT/1000), PAYLOAD, TOPIC, CLIENTID);
    rc = MQTTClient_waitForCompletion(client, token, TIMEOUT);
    printf("Message with delivery token %d delivered\\n", token);
  
    // 断开连接
    MQTTClient_disconnect(client, 10000);
    MQTTClient_destroy(&client);
    return rc;
}

参数说明

参数
说明
ADDRESS
broker 连接地址，在控制台目标集群基本信息 > 接入信息模块中复制。位置如下图所示。格式：mqtt-xxx-gz.mqtt.qcloud.tencenttdmq.com:1883。

CLIENTID
客户端 ID，在控制台集群详情页客户端管理页面获取。

USERNAME
用户名，在控制台认证管理页面获取；
PASSWORD
密码，在控制台认证管理页面获取；

编译示例

cd /root
gcc mqtt-example.c -lpaho-mqtt3c -o mqtt-example

Paho C MQTT 5.0 支持​

目前 Paho C 已经完整支持 MQTT 5.0。



一机一证示例

场景介绍

对于高价值设备等安全要求较高的场景, 建议使用“一机一证”的方式对客户端认证。“一机一证”是双向认证mTLS 的加强: 在双向认证的基础上，云端对设备客户端证书的状态进行管理，包括激活、取消激活、吊销等操作。


生成证书

生成 CA 证书

ECDSA
RSA
openssl ecparam -genkey -name prime256v1 -out CA.key
openssl req -new -x509 -key CA.key -sha256 -subj "/C=CN/ST=ZheJiang/L=HangZhou/O=TencentCloud/CN=MQTT-CA" -days 3650 -out CA.crt
openssl genrsa -out CA.key 4096
openssl req -new -x509 -key CA.key -sha256 -subj "/C=CN/ST=ZheJiang/L=HangZhou/O=TencentCloud/CN=MQTT-CA" -days 3650 -out CA.crt


签发服务端证书

创建配置文件 server.conf
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no

[req_distinguished_name]
C = CN
ST = ZheJiang
L = HangZhou
O = Example
CN = mqtt.example.com

[v3_req]
basicConstraints = critical, CA:FALSE
# Common Key Usage Combinations
#   TLS Server: keyUsage=digitalSignature,keyEncipherment + extendedKeyUsage=serverAuth
#   TLS Client: keyUsage=digitalSignature + extendedKeyUsage=clientAuth
#   Code Signing: keyUsage=digitalSignature + extendedKeyUsage=codeSigning
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = mqtt.example.com
DNS.2 = www.example.com
DNS.3 = api.example.com
DNS.4 = *.example.com
IP.1 = 192.168.1.100
IP.2 = 10.0.0.50

ECDSA
RSA
openssl ecparam -genkey -name prime256v1 -out server.key
openssl req -new -key server.key -out server.csr -config server.conf
openssl x509 -req -in server.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out server.crt -days 365 -sha256 -extensions v3_req -extfile server.conf
openssl genrsa -out server.key 4096
openssl req -new -key server.key -out server.csr -config server.conf
openssl x509 -req -in server.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out server.crt -days 365 -sha256 -extensions v3_req -extfile server.conf

验证服务端证书

openssl x509 -in server.crt -text -noout
openssl verify -CAfile CA.crt server.crt
openssl x509 -in server.crt -text -noout | grep -A 10 "Subject Alternative Name"
创建完整服务端证书链文件
cat server.crt > server.chain.crt
cat CA.crt >> server.chain.crt

签发客户端证书

创建配置文件 client.conf
[v3_req]
basicConstraints = critical, CA:FALSE
keyUsage = critical, digitalSignature
extendedKeyUsage = clientAuth

ECDSA
RSA
openssl ecparam -genkey -name prime256v1 -out client.key
openssl req -new -key client.key -out client.csr -subj "/C=CN/ST=ZheJiang/L=HangZhou/O=IoV/CN=SN0001"
openssl x509 -req -in client.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out client.crt -days 365 -sha256 -extfile client.conf -extensions v3_req
openssl genrsa -out client.key 4096
openssl req -new -key client.key -out client.csr -subj "/C=CN/ST=ZheJiang/L=HangZhou/O=IoV/CN=SN0001"
openssl x509 -req -in client.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out client.crt -days 365 -sha256 -extfile client.conf -extensions v3_req


配置 MQTT 实例为一机一证模式

配置服务端证书

1. 导航到实例配置页面



2. 选择自定义证书和“一机一证”认证方式



3. 上传服务端证书到 SSL 证书服务



单击上传证书，如下图：



上传证书与密钥：

修改备注：



选择证书：


配置 CA 证书




注册 CA 证书, 需签发一份验证证书, Common Name 为给定的随机值



openssl genrsa -out verify.key 4096
openssl req -new -key verify.key -out verify.csr -subj "/C=CN/ST=ZheJiang/L=HangZhou/O=IoV/CN=3a708879-8035-4d58-afca-e15d4586e2d2"
openssl x509 -req -in verify.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out verify.crt -days 3 -sha256

提交后, 注册 CA 证书完成


配置 CNAME

服务端证书Subject Alternative Name扩展中包含以下几个域名:
DNS.1 = mqtt.example.com
DNS.2 = www.example.com
DNS.3 = api.example.com
DNS.4 = *.example.com
域名系统增加 CNAME 记录, 将 mqtt.example.com 指向实例接入点: mqtt-xxxx-nj-public.mqtt.tencenttdmq.com.
测试环境下, 也可以修改本地 hosts 文件, 将 mqtt.example.com 指向接入点的 IP 地址.

验证域名、证书及一机一证配置

openssl s_client -connect mqtt.example.com:8883 -CAfile CA.crt -cert client.crt -key client.key  -verify_hostname mqtt.example.com
应该输出类似下面结果
Connecting to 109.244.152.235
CONNECTED(00000005)
depth=1 C=CN, ST=ZheJiang, L=HangZhou, O=TencentCloud, CN=MQTT-CA
verify return:1
depth=0 C=CN, ST=ZheJiang, L=HangZhou, O=Example, CN=mqtt.example.com
verify return:1
---
Certificate chain
 0 s:C=CN, ST=ZheJiang, L=HangZhou, O=Example, CN=mqtt.example.com
   i:C=CN, ST=ZheJiang, L=HangZhou, O=TencentCloud, CN=MQTT-CA
   a:PKEY: RSA, 4096 (bit); sigalg: sha256WithRSAEncryption
   v:NotBefore: Jul 24 02:48:06 2025 GMT; NotAfter: Jul 24 02:48:06 2026 GMT
 1 s:C=CN, ST=ZheJiang, L=HangZhou, O=TencentCloud, CN=MQTT-CA
   i:C=CN, ST=ZheJiang, L=HangZhou, O=TencentCloud, CN=MQTT-CA
   a:PKEY: RSA, 4096 (bit); sigalg: sha256WithRSAEncryption
   v:NotBefore: Jul 24 02:47:18 2025 GMT; NotAfter: Jul 22 02:47:18 2035 GMT
---
Server certificate
...
Acceptable client certificate CA names
...
---
SSL handshake has read 3950 bytes and written 5058 bytes
Verification: OK
Verified peername: mqtt.example.com
---
New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384
Protocol: TLSv1.3
Server public key is 4096 bit
This TLS version forbids renegotiation.
Compression: NONE
Expansion: NONE
No ALPN negotiated
Early data was not sent
Verify return code: 0 (ok)

开发环境

安装依赖

以 Ubuntu 24.04.2 LTS 为例:
apt install build-essential openssl libssl-dev cmake wget dnsutils -y

安装 paho.mqtt.c

wget https://github.com/eclipse-paho/paho.mqtt.c/archive/refs/tags/v1.3.14.tar.gz
tar -xzvf v1.3.14.tar.gz 
cd paho.mqtt.c-1.3.14/
mkdir _build && cd _build
cmake -DPAHO_WITH_SSL=true .. && make && make install

一机一证示例文件

详情可单击byoc-demo。

编译

tar -xzvf byoc-demo.tar.gz
cd byoc-demo && mkdir _build && cmake .. && make

运行

./paho_cs_pub -t home -i c_client_byoc -V 5 --cafile /root/byoc-test/CA.crt --cert /root/byoc-test/client.crt --key /root/byoc-test/client.key -c ssl://mqtt.example.com:8883 --trace protocol

控制台验证

客户端管理页面, 可以查看到使用"一机一证"的客户端

客户端证书管理页面, 客户端证书已自动注册


上一篇: Java SDK下一篇: Javascript/Node.JS/小程序

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈