C

本页介绍 C API。适用于所有语言的连接字符串、标签地址和默认值的变更详见概览页]。

简短版本

PLC4C API 没有变化。plc4c/api/include 中 0.13.1 已有的每个函数在 1.0.0 中依然存在，签名也相同。针对 0.13.1 编译的应用程序可以直接针对 1.0.0 编译。

以下变更是增量性的，或者是运行时行为的改变。

API 的新增内容

plc4c_data_create_wstring_data(unsigned int size, char *s) 与现有的 plc4c_data_create_string_data 一同加入，作为对 Modbus 的通用 STRING 和 WSTRING 支持的一部分。

其负载是采用线上编码的字节串，而不是 wchar_t 序列——SPI 没有能生成这种序列的宽字符读取器。

消息嵌套深度有限制

生成的解析器会拒绝类型嵌套深度超过 1024 层的消息。若干协议类型包含自身，因此值树的深度由发送方决定，且每深一层在线上只多花一个字节；过去只要嵌套足够深，就会耗尽解析器的栈空间。

如果某个设备的消息确实嵌套更深，请设置 PLC4X_MAX_NESTING_DEPTH 环境变量。它在所有 PLC4X 绑定中含义相同；若取值不是 1 到 65535 之间的正整数，则保留默认值并给出警告。

项目自带测试套件中最深的消息嵌套了 36 层，因此这一限制只影响现实中没有任何设备会发送的情况。

标签地址保持不变

这正是 PLC4C 此刻与 PLC4J 和 PLC4Go 存在差异的地方，有必要明确说明。

1.0.0 在所有 Java 和 Go 驱动中引入了统一的数组表示法，其中选择部分写在类型之前，[4] 表示“索引为 4 的元素”：

holding-register:1[0..3]:INT     # PLC4J and PLC4Go in 1.0.0

已复制！

PLC4C 并未跟进。 它的 Modbus 解析器仍然按照旧的“先类型后数量”形式进行解析，在该形式中 [4] 表示“四个元素”：

holding-register:1:INT[4]        # PLC4C, both in 0.13.1 and in 1.0.0

已复制！

这样你现有的 PLC4C 地址就能保持不变地继续工作——但从 数组寻址 页面或某个可正常运行的 PLC4J 应用程序复制来的地址将无法解析。请把数组记法的文档理解为面向 PLC4J 和 PLC4Go，而非 PLC4C。

Modbus 的 STRING 和 WSTRING 仅部分支持

STRING和WSTRING已被加入 Modbus 数据类型，生成的解析器也能解码它们——但 PLC4C 的 Modbus 标签没有字符串长度的概念，因此驱动会把每个字符串都当作单个字符来读取。

PLC4J 和 PLC4Go 会像 S7 驱动那样，用圆括号写上声明的长度（holding-register:1[0..2]:STRING(20)表示三个长度为 20 的字符串）。PLC4C 的地址解析器会把:和[之间的文本当作数据类型名称来读取，所以STRING(20)根本无法解析为任何数据类型。

请把 Modbus 字符串视为目前尚不能从 PLC4C 使用。0.13.1 中原本可用的功能都没有被破坏——那个版本同样没有STRING支持。

构建

PLC4X 的构建已迁移到 Apache Maven 4。只有当你使用-Pwith-c从 PLC4X 源码树构建 PLC4C 时才需要关注这一点；生成源码的 CMake 构建没有变化。