简介：面向使用 C++ 处理测试测量数据的开发者，这份文档围绕 C++ 对 TDMS（含 TDM）文件的读写展开，帮助读者在数据采集、自动化测试等场景中绕开格式转换的繁琐，直接调用 NI 官方 DDC 库完成文件级操作。文中以 writeDDCFile 与 ReadDDCFile 两个完整函数为主干，串起 DDC_CreateFile、DDC_AddChannel、DDC_SetDataValues、DDC_SaveFile 的写入链路，以及 DDC_OpenFile、DDC_GetNumChannels、DDC_GetDataValuesDouble 的读取链路，并提示新增通道时名称参数必须唯一、否则会相互覆盖这类易踩的细节。作者还记录了 TDM 与 TDMS 的实测差异：同等通道数与数据长度下文件体积接近，TDMS 写入耗时却接近 TDM 的两倍，通道数升至万级时写入时间明显增加，写盘前需为第三方库的中间文件预留数倍空间。压缩包内为 1 个 doc 文件，约 20KB，体量轻便，已有 996 人学习下载，适合想快速上手 TDMS 读写接口的初中级开发者查阅。

1. 从一份采集程序说起：C++ 读写 TDMS 到底难在哪

做振动采集上位机的同行多半遇到过一个场景：128 个通道、每通道 102400 个采样点，存成 CSV 要一百多兆，Excel 打不开，文本解析一遍要十几秒，还丢精度。换成 TDMS 之后，同一批数据落到磁盘上还是一百兆出头，但带上索引之后，第二次读明显变快。这就是为什么做科学计算和数据采集的 C++ 程序，绕不开 TDMS 这个格式。这里整理的是用 C++ 加一套 C 风格接口库读写 TDM/TDMS 的完整实例，从创建文件、加通道组、灌数据，到打开、遍历、取值，两条链路都有可编译的骨架。适合谁读：正在给测试台架写数据落盘模块的 C++ 开发、要从上位机导出数据给分析端的人、以及被 CSV 拖慢过的人。看完至少能跑通，也大概知道哪几行最容易出事。

2. 接口全景：DDC 库把 TDM/TDMS 拆成了哪几层对象

这套库是纯 C 接口，头文件一进来就是一堆DDC_前缀函数，第一眼会觉得函数多得让人头疼。实际上它的对象模型只有三层半，理清楚之后，读写两条链路都只有七八步。

2.1 文件—通道组—通道的三层句柄模型

TDMS 的逻辑结构是严格的树形：一个文件下面挂若干通道组（group），每个组下面挂若干通道（channel），每条通道下面才是真正的采样点数组，外加一串属性键值对（property）。在 C 接口里，这三层各对应一个不透明句柄类型：

所谓句柄，本质上就是个void*，里面包着库自己维护的结构体，调用方不要去看也不要自己释放，只能通过DDC_CloseFile或者库提供的销毁函数交回去。所有 API 的返回值都是int状态码，0 表示成功，非 0 要立刻查错误信息，把错误吞掉的后果后面会讲。

另一个必须先记住的是数据类型枚举。写入时DDC_AddChannel的第二个参数决定了这条通道的数据类型，后续取值函数必须与之匹配：

常见做法是：采集端一律写DDC_Double，分析端读之前先调DDC_GetChannelType判断真实类型再分发到对应函数，别想当然地拿DDC_GetDataValuesDouble去读一条DDC_I16的通道——有的版本会返回错误码，有的版本会给你一堆零，这种玄学问题排查起来能耗掉半天。

2.2 写入链路的七步调用顺序

写入的最小闭环踩在七个点上，顺序不能乱：创建文件、加组、加通道、设数据、可选写属性、保存、关闭。骨架长这样：

// 最小写入骨架：文件 -> 组 -> 通道 -> 数据 -> 保存 -> 关闭 int WriteMinimal(const char* path, const double* data, size_t len) { DDCFileHandle file = nullptr; // 1. 创建文件：第二个参数决定是 "TDM" 还是 "TDMS" int rc = DDC_CreateFile(path, "TDMS", "采集数据", "test", "标题", "说明", &file); if (rc != 0) return rc; DDCChannelGroupHandle group = nullptr; // 2. 加通道组，第三个参数是描述，可以留空 rc = DDC_AddChannelGroup(file, "group01", "振动信号", &group); if (rc != 0) { DDC_CloseFile(file); return rc; } DDCChannelHandle ch = nullptr; // 3. 加通道：类型、名字、描述、单位；名字在同组内必须唯一 rc = DDC_AddChannel(group, DDC_Double, "ch0", "", "m/s2", &ch); if (rc != 0) { DDC_CloseFile(file); return rc; } // 4. 一次把整段数据塞进去，第三参数是点数 rc = DDC_SetDataValues(ch, data, static_cast<unsigned __int64>(len)); if (rc != 0) { DDC_CloseFile(file); return rc; } // 5. 保存才会真正把内存里的数据落到磁盘 rc = DDC_SaveFile(file); // 6. 关闭句柄，无论保存成功与否 DDC_CloseFile(file); return rc; }

参数里最容易被忽略的是DDC_CreateFile的第三个到第六个参数。它们分别是文件描述、文件名、标题、标题描述，写进文件头里，用来存实验条件、采样率、设备编号这类元信息。很多人图省事全传空串，结果半年后拿到一个data.tdms，完全不知道它是什么工况下采的，只能从文件名去猜。我现在的习惯是把采样率、量程、传感器编号都塞进属性里：

// 属性是 meta 信息的正解，别往文件名里塞 DDC_SetChannelProperty(ch, "SampleRate", DDC_Double, &sampleRate, 1); DDC_SetChannelProperty(ch, "SensorSN", DDC_String, "SN-0001", 1);

DDC_SetChannelProperty第三参数指定属性类型，第四参数传地址，第五参数是值的个数（数组属性才用得上，不是逗号分隔的值）。属性会随文件一起存，读的时候用DDC_GetChannelProperty取回来，这是把数据交给别人时唯一靠谱的自解释手段。

2.3 读取链路与类型取值

读取链路看起来对称，但比写入多两步——必须先拿到组句柄数组和通道句柄数组，才能往下遍历。完整的调用次序是：

// 读取骨架：打开 -> 拿组 -> 拿通道 -> 拿长度 -> 取值 DDCFileHandle file = nullptr; DDC_OpenFile(path, "TDMS", &file); // 1. 打开，格式要对上 unsigned int groupCount = 0; DDC_GetNumChannelGroups(file, &groupCount); // 2. 先问数量 std::vector<DDCChannelGroupHandle> groups(groupCount); DDC_GetChannelGroups(file, groups.data(), groupCount); // 3. 再取句柄数组 for (unsigned int i = 0; i < groupCount; ++i) { unsigned int chCount = 0; DDC_GetNumChannels(groups[i], &chCount); std::vector<DDCChannelHandle> chans(chCount); DDC_GetChannels(groups[i], chans.data(), chCount); // 组内同理 for (unsigned int j = 0; j < chCount; ++j) { unsigned __int64 len = 0; DDC_GetNumDataValues(chans[j], &len); // 4. 单通道点数 std::vector<double> buf(len); DDC_GetDataValuesDouble(chans[j], 0, len, buf.data()); // 5. 起止索引 } } DDC_CloseFile(file);

第 3 步的DDC_GetChannelGroups是整条链路的关键，它负责把上一步问到的数量填成真正的句柄。原始示例代码里正好漏了这一步，直接拿未初始化的数组往下走，后面会专门讲这个坑。

DDC_GetDataValuesDouble的第二个参数是起始索引，第三个是点数，这样就能只取一段数据。做大文件浏览时不要一次读全量，按窗口取，几百兆的文件翻页不会卡。至于“多次访问后读取变快”这个现象，原因是库内部维护了索引缓存，第一次打开要扫一遍块索引，后面命中缓存。这也带来一个副作用：如果多个线程同时读同一个句柄，缓存状态可能互相干扰，正确做法是每个线程DDC_OpenFile一份自己的句柄。

3. 写入实现拆解：WriteDDCFile 里每一步在干什么

原始的写入函数长这样，去掉注释之后不到二十行，但每一行都有说法：

int CTDMSTestDlg::WriteDDCFile(const char* filePath, int channelNum, int dataLen, const char* fileType /* = "TDM" */) { DWORD begin = ::GetTickCount(); DDCFileHandle testFile; DDC_CreateFile(filePath, fileType, "", "", "", "", &testFile); // 创建指定格式的文件 DDCChannelGroupHandle group01; DDC_AddChannelGroup(testFile, "group01", "", &group01); // 增加一个通道组 DDCChannelHandle* channels = new DDCChannelHandle[channelNum]; double* channelData = CreateRandomData(dataLen); for (int i = 0; i < channelNum; i++) { char channelIdx[20]; itoa(i, channelIdx, 10); // 通道名 = 序号 DDC_AddChannel(group01, DDC_Double, channelIdx, "", "", &channels[i]); // 注意每次增加通道时，第三个参数值要不一样，否则会覆盖 DDC_SetDataValues(channels[i], channelData, dataLen); // 为通道设置数据 } DDC_SaveFile(testFile); DWORD end = ::GetTickCount(); DDC_CloseFile(testFile); delete[] channels; delete[] channelData; return end - begin; }

3.1 创建文件与通道组：参数到底落在哪

DDC_CreateFile的七个参数依次是：文件路径、格式字符串、文件描述、文件名、标题描述、标题、输出句柄。格式字符串只有"TDM"和"TDMS"两个合法值，写错了会直接返回错误码；路径用相对路径时是相对当前工作目录，不是相对 exe 所在目录，这一点在服务里跑的时候经常翻车——打包部署后工作目录变成了C:\Windows\System32，文件就“消失”了。稳妥做法是先把相对路径转成绝对路径再传进去。

DDC_AddChannelGroup只有三个有效参数：文件的句柄、组名、描述。组名在同一文件内唯一，重复添加同名组时库的行为是返回错误还是追加，不同版本不一致，别赌，自己在业务层加个唯一性检查。描述建议写清楚这组数据代表什么工况，比如"工位3-空载-3000rpm"，对后期检索的价值远大于省下的那几十字节。

3.2 通道名重复会覆盖，这是最容易翻车的一行

示例里用itoa把序号转成字符串当通道名，还专门留了一行注释「每次增加通道时，第三个参数的值要不一样，否则会覆盖」。这句话是整段代码里最值钱的一行血泪经验。DDC_AddChannel的第三个参数是通道名，当你在同一个组里第二次用同名调用它时，库并不会给你新建一条通道，而是把已有那条的句柄还给你，接着DDC_SetDataValues就把原数据盖掉了。表现出来就是：明明写了 128 个通道，读回来只有 1 个，且数据是全零或者某一条的重复。

围绕这一行还有三个衍生问题。第一，char channelIdx[20]配itoa只够撑到二十位十进制，通道数上千之后名字会变长，得换成snprintf(channelIdx, sizeof(channelIdx), "ch_%05d", i)，定长命名还方便后期按名字排序。第二，itoa不是标准 C++ 函数，跨编译器（比如换到某个 Linux 工具链）直接编不过，用std::to_string或snprintf更省事。第三，通道名里不要放空格和点号，某些解析工具会把它们当成层级分隔符处理。

如果要做“追加写入”，注意DDC_AddChannel对已存在通道的处理和新建不同：拿到句柄后调DDC_AppendDataValues才是追加语义，DDC_SetDataValues永远是覆盖。这两个函数名长得像，用错方向就是一次数据丢失。

3.3 计时的坑：GetTickCount 包不住保存

示例统计耗时的方式是GetTickCount()取开始和结束，然后end - begin。三个问题：其一，GetTickCount返回 32 位毫秒，连续运行四十多天会回绕归零，做长时间稳定性测试时算出来的耗时会变成负数；其二，示例里end取在DDC_SaveFile之后、DDC_CloseFile之前，关闭文件本身也有磁盘抖动开销，尤其在网络盘上；其三，毫秒精度测小文件根本不够看，128 通道 10 万点的写入耗时可能几百毫秒，误差能到 10%。

我一般换成std::chrono::steady_clock，并且把DDC_CloseFile也纳入统计区间：

auto t0 = std::chrono::steady_clock::now(); // ... 创建、加通道、设数据、保存 ... DDC_CloseFile(file); auto ms = std::chrono::duration_cast<std::chrono::milliseconds>( std::chrono::steady_clock::now() - t0).count();

3.4 TDM 和 TDMS 选哪个：实测比文档靠谱

两种格式的表层差异是：TDM 由 XML 头和二进制数据组成，索引和描述都是可读文本；TDMS 从头到尾都是二进制，没有 XML 段。官方材料里一般更推崇 TDMS，理由是性能好、适合流式写。但拿同一份数据实测下来，结论并不完全一致：

通道数固定、每通道点数固定时，两者文件体积几乎没差别，所以“TDMS 更省空间”这个说法在中小规模数据上并不成立。写入耗时上 TDMS 反而更慢，这和它边写边维护块索引、要做更多的元数据落盘有关；数据量越大，差距越明显。读取侧两者都有索引，第二次读都比第一次快，差距在毫秒级。

真正决定选型的是使用场景而不是绝对快慢：如果程序是“一次性写完整段数据、事后交给分析端读”，TDM 更划算，XML 头还能让人拿文本编辑器直接看一眼通道结构；如果是长时间连续采、边采边写、对断电后的可恢复性有要求，TDMS 的分块追加语义更合适，因为它的元数据也是二进制且按块组织，中途异常时前面的块通常还能读出来。

还有个规模问题要记住：通道数增加到一万这个量级时，写入耗时会有一次明显跳变，不是线性的；而单通道长度的增加和耗时基本是线性的。所以设计采集方案时，宁可少通道、长缓冲，也不要搞几千个短通道。

4. 读取实现拆解：ReadDDCFile 的骨架和它藏着的三个坑

原始的读取函数是这段：

int CTDMSTestDlg::ReadDDCFile(const char* filePath, const char* fileType /* = "TDM" */) { DWORD begin = ::GetTickCount(); DDCFileHandle ddcFile; DDC_OpenFile(filePath, fileType, &ddcFile); // 打开文件 unsigned int groupNum = 0; DDC_GetNumChannelGroups(ddcFile, &groupNum); // 获取通道组的数目 DDCChannelGroupHandle* groups = new DDCChannelGroupHandle[groupNum]; for (int i = 0; i < groupNum; i++) { unsigned int channelNum = 0; DDC_GetNumChannels(groups[i], &channelNum); // 获取通道的数目 DDCChannelHandle* channels = new DDCChannelHandle[channelNum]; for (int j = 0; j < channelNum; j++) { unsigned __int64 dataLen = 0; DDC_GetNumDataValues(channels[j], &dataLen); // 获取数据长度 double* data = new double[dataLen]; DDC_GetDataValuesDouble(channels[j], 0, dataLen, data); for (int k = 0; k < dataLen; k++) { data[k]; // 这里本该是业务处理 } } delete[] groups; // 在内层循环里释放外层数组 groups = NULL; } DWORD end = ::GetTickCount(); DDC_CloseFile(ddcFile); delete[] groups; return end - begin; }

这段代码的骨架方向是对的，但它不能直接跑。

4.1 正确版本：补齐句柄数组那一步

问题出在groups[i]从来没被赋过值。DDC_GetNumChannelGroups只回答“有几个组”，不负责给你组句柄；拿到数量之后必须再调一次DDC_GetChannelGroups把句柄填进去，组内的DDC_GetChannels同理。补全之后的版本：

int ReadAll(const char* path, const char* fileType) { DDCFileHandle file = nullptr; int rc = DDC_OpenFile(path, fileType, &file); if (rc != 0) { return rc; } // 打开失败就没有句柄可用 unsigned int groupNum = 0; if (DDC_GetNumChannelGroups(file, &groupNum) != 0 || groupNum == 0) { DDC_CloseFile(file); return -1; } std::vector<DDCChannelGroupHandle> groups(groupNum); DDC_GetChannelGroups(file, groups.data(), groupNum); // 关键补齐 for (unsigned int i = 0; i < groupNum; ++i) { unsigned int channelNum = 0; if (DDC_GetNumChannels(groups[i], &channelNum) != 0) continue; std::vector<DDCChannelHandle> chans(channelNum); DDC_GetChannels(groups[i], chans.data(), channelNum); for (unsigned int j = 0; j < channelNum; ++j) { unsigned __int64 dataLen = 0; if (DDC_GetNumDataValues(chans[j], &dataLen) != 0 || dataLen == 0) continue; std::vector<double> buf(static_cast<size_t>(dataLen)); rc = DDC_GetDataValuesDouble(chans[j], 0, dataLen, buf.data()); if (rc != 0) continue; // 类型不匹配等错误在这里暴露 // ... 业务处理 buf ... } } DDC_CloseFile(file); return 0; }

改法本身不复杂，但要点在于每一层都先校验返回码再用句柄。这套 C 接口没有异常，出错只能靠状态码，rc != 0那一行看着啰嗦，省掉一次，线上就是一次段错误。

4.2 三处硬伤：未取句柄、循环里删除、数据不释放

把原始版本的错误挨个对一遍。第一处是groups[i]未初始化就被当参数传进DDC_GetNumChannels，这个数组是用new申请但没初值的裸内存，里面是随机垃圾，传进去轻则返回错误码、重则库内部解引用野指针直接崩，也就是那种“打开文件就闪退、日志一条没有”的黑匣子现场。

第二处是delete[] groups被写在了for (i)循环体内的末尾，紧接着又groups = NULL，然后下一轮迭代再delete[] groups（此时是空指针，还好），但循环结束后函数末尾还有一次delete[] groups——同一个指针被释放两次，堆直接损坏。正确位置只有一个：循环全部结束、DDC_CloseFile之后。用std::vector就没这问题。

第三处是new double[dataLen]之后从头到尾没有delete[]，channels数组同样泄漏。读一个 128 通道 10 万点的文件，泄漏就是 128 × 100000 × 8 字节，约 100MB 一次。批量跑一百个文件，进程内存就上去了。同样用std::vector<double>管理，一出作用域自动回收。

4.3 大文件的内存与分块策略

dataLen的类型是unsigned __int64，说明这套接口本身支持超过 4G 点数的通道。真按这个长度一次性new double[dataLen]，12G 的数据文件就需要 12G 连续内存，32 位进程完全没戏，64 位进程也会因为内存碎片和物理内存上限直接失败。

分块读取是必选项：

// 按 64K 点一块读，内存占用恒定 const unsigned __int64 kChunk = 65536; std::vector<double> buf(kChunk); for (unsigned __int64 offset = 0; offset < dataLen; offset += kChunk) { unsigned __int64 n = std::min(kChunk, dataLen - offset); DDC_GetDataValuesDouble(ch, offset, n, buf.data()); // 起止索引就是干这个的 // ... 处理 buf[0..n) ... }

DDC_GetDataValuesDouble的第二个参数起始索引和第三个参数点数，就是为分块设计的。块大小选 64K 点（512KB）是个折中：太小的话函数调用和锁开销占比上升，太大的话单次拷贝耗时长、UI 会卡。做进度条的话每块处理完更新一次，128 通道 10 万点的文件基本感觉不到顿挫。

5. 避坑清单：磁盘留三倍、通道破万、句柄与时间统计

这一章全是踩出来的。每条按现象、原因、解决三段走，能对上号的直接抄。

5.1 现象：写到一半报磁盘空间不足，一看目录里多了个巨大临时文件

原因：这套库保存时并不是直接在目标文件上原地写，而是先落中间文件，最后再合并成最终文件。中间文件的体积远大于成品，实测 12G 左右的最终数据文件，需要至少 32G 的可用空间才能顺利写完。空间不足时DDC_SaveFile返回非零，但很多人没检查返回值，以为写成功了，实际只留下半截文件。

解决：落盘前先查一次可用空间，按「预计数据量 × 3」做门槛判断，不够就提前报错给上层，别等写到 90% 才失败。中小数据量不用太焦虑，128 通道、每通道 102400 点、成品约 100M 的场景，中间文件也在可接受范围内。另外把中间目录配置到和成品同一个物理盘上，跨盘合并会额外拉长保存时间。

5.2 现象：通道数从几百加到一万，写入时间不是翻倍而是跳了好几倍

原因：通道数到一万量级时，元数据条目本身的规模上来了，库在保存时对通道索引的整理和后处理开销显著上升，不再是线性关系。而单通道点数增加时，耗时基本线性——数据段是顺序落盘的。这决定了“宽表”比“长表”更吃亏。

解决：重新设计通道划分。同一个传感器的三轴数据不要拆成三条通道，可以合并成一条通道加属性说明，或者按采集单元分组、每组控制在几百通道以内。真的是上万测点的场景，考虑按时间段切成多个文件，每个文件内部再分组，把单个文件的通道数压下去。

5.3 现象：打开文件后第一行就崩，或者读回来的通道数是天文数字

原因：就是上一章说的句柄未取、野指针解引用。也可能是DDC_OpenFile的格式参数和实际文件不符——文件是 TDMS，参数传了"TDM"，有的版本返回错误码，有的版本返回 0 但句柄无效。

解决：所有DDC_调用后紧跟返回码判断，打开文件后立刻用DDC_GetNumChannelGroups验证句柄可用；格式参数不要写死默认值，从文件扩展名推导，或者干脆先用"TDMS"试、失败再用"TDM"重试一次。

5.4 现象：跑了几天以后耗时统计是负数，或者内存一直涨

原因：时间统计用GetTickCount，32 位毫秒在连续运行 49.7 天后回绕；内存一直涨则是句柄和缓冲没有释放，循环里的new配不上delete，或者DDC_OpenFile成功后中途 return 忘了DDC_CloseFile。

解决：时间统一换std::chrono::steady_clock；句柄用 RAII 包一层，析构里调DDC_CloseFile；缓冲一律std::vector。再加一条：每个DDC_OpenFile对应且只对应一个DDC_CloseFile，不要指望进程退出时系统帮你收，库内部可能还有落盘动作没完成。

5.5 一张排查表

6. 二次开发：把 demo 改成能进采集流水线的模块

这份示例代码最好的用法不是直接塞进工程，而是当成协议参考。真要落地，我一般做三件事：包一层 RAII、抽出通道描述结构、写一个自校验的读写往返测试。

RAII 那层很薄，就是把句柄的关闭动作绑到析构上，避免任何一条 return 路径漏掉：

// 极简 RAII：句柄生命周期跟着对象走 class TdmsFile { public: explicit TdmsFile(const std::string& path, const char* type = "TDMS") { rc_ = DDC_OpenFile(path.c_str(), type, &h_); } ~TdmsFile() { if (rc_ == 0 && h_) DDC_CloseFile(h_); } TdmsFile(const TdmsFile&) = delete; // 句柄不可拷贝 TdmsFile& operator=(const TdmsFile&) = delete; bool ok() const { return rc_ == 0; } DDCFileHandle raw() const { return h_; } private: DDCFileHandle h_ = nullptr; int rc_ = -1; };

通道描述建议抽成结构体，把名字、单位、数据类型、属性打包，采集层只负责填结构体，落盘层统一遍历。这样以后从 TDM 换成 TDMS、或者把落盘换成别的格式，只改一层。属性写入也一并收进去，元信息就不会漏。

改造完必须验一遍，不然改出来的东西看着像对的。我的做法是写一个往返测试：造一段已知数据（比如sin加线性斜坡，避免全零掩盖问题），写盘、重新打开、逐点比对，误差超过1e-12就判定失败；同时比对通道数、组名、属性值。再补一轮边界样本：零长度通道、单点通道、超长通道（百万点以上）、通道名含下划线和中划线、属性值为空串。这几组跑过，基本能挡住九成的回归问题。

还有一个技巧值得单独说：调试读写代码时，别急着看自己的业务结果，先写一个“结构打印”函数，把文件的组名、通道名、类型、长度、属性全打出来。TDMS 是二进制格式，出了问题没有后悔药，看不见结构就只能靠猜。这个函数我每个项目都会留一份，后期对接分析端时直接拿它当协议文档用。

从那以后我每次接采集落盘的活，第一件事都是先写这个结构打印和往返校验，再写业务逻辑——顺序反过来，后面排查的成本要高出好几倍。希望帮到你。

本文还有配套的精品资源，点击获取