openPlant C++ 语言接口使用说明

本文档用于指导开发人员快速掌握 openPlant 实时数据库 C/C++ API 的使用规范，系统介绍数据库基础概念、新版接口能力(适配数据库V4.0/V5.0)、标准调用流程、业务场景用法及可编译示例代码，同时兼容说明老接口(适配 V3.0 )，为项目开发、迁移、维护提供统一技术依据。

1、基础知识

openPlant 实时数据库采用三级树形架构，层级从上至下依次为：数据库层级（database）→ 业务节点（node）→ 监测测点（point）。所有测点属性分为动态属性与静态属性两类，同时区分实时数据与历史数据。

1.1 测点属性分类

属性类型	属性标识	属性说明	编辑权限
动态属性（实时更新）	TM	数据更新时间戳，随数据推送实时变化	系统/业务写入更新
	AS	测点运行状态，标识数据有效性	系统/业务写入更新
	AV	测点实时数值，核心业务数据	系统/业务写入更新
静态属性（固定/可配置）	PN、ID、ED、EU	PN(点名)、ID(测点唯一标识)、ED(描述)、EU(工程单位)	ID、PN、测点类型创建后永久固定；其余静态属性支持API修改

1.2 数据类型定义

实时数据：测点当前最新的 AV 数值，为系统实时推送的有效数据。新数据推送后，上一条实时数据自动归档为历史数据。
历史数据：所有完成归档、存储在数据库中的过往时序数据，支持区间查询、快照插值、批量补录等操作。

2、新版接口总览（适配 V4.0 / V5.0）

2.1 架构设计

openPlant V4.0/V5.0 CPP SDK 采用标准句柄式架构，统一遵循「创建连接-组装请求-发送请求-解析响应-释放资源」的生命周期，架构规范、资源可控、支持异步订阅，为新项目唯一推荐使用版本。

2.2 核心对象说明

对象名称	对象类型	核心作用
OpenPlant	连接句柄	数据库全局连接上下文，所有接口操作的基础依赖
op_request	请求对象	封装接口请求参数、操作类型、过滤条件、目标测点等信息
op_response	响应对象	承载服务端返回结果、错误码、错误信息等响应数据
op_table	数据表对象	统一承载请求入参、查询结果的二维数据表结构
op_row	行对象	数据表单行数据载体，用于批量组装写入数据
op_stream	传输流对象	底层网络传输通道，支持数据压缩配置

2.3 核心能力覆盖

数据库连接初始化、状态检测、连接关闭管理
测点实时值、快照值、历史时序数据读写操作
数据库节点、测点的新增、修改、删除运维操作
原生 SQL 语句执行与数据统计查询
实时数据异步订阅、回调消费、通道关闭全流程能力

2.4 标准调用流程

2.4.1 同步调用流程（常规查询、写入、SQL执行）

调用 op2_init 初始化数据库连接，获取全局连接句柄；
调用 op2_new_table 创建数据表，通过 op2_add_column 定义字段结构；
调用 op2_new_request 创建空白请求对象；
通过 op2_set_table 绑定数据表，配置请求参数、过滤条件、目标测点；
通过统一请求接口提交请求，接收服务端响应数据；
遍历数据表解析业务结果，处理返回数据；
主动释放请求、响应、数据表等资源，避免内存泄漏；
业务执行完毕，调用 op2_close 关闭数据库连接。

2.4.2 异步订阅流程（实时数据推送）

同步流程前5步保持一致，将主动请求替换为长连接订阅：调用 op2_open_async 注册数据回调函数，持续接收服务端实时推送数据；业务结束后调用 op2_close_async 关闭订阅通道。

3、新版接口详细说明（V4.0/V5.0）

3.1 连接与时间工具接口

函数名称	功能描述
op2_init	初始化并建立数据库连接，返回有效连接句柄
op2_close	关闭数据库连接，释放连接句柄资源
op2_get_system_time	获取数据库服务器标准时间戳，保证时序数据统一
op2_decode_time	将时间戳解析为年、月、日、时、分、秒分段时间
op2_encode_time	将分段年月日时分秒时间编码为标准时间戳
op2_sleep	异步订阅循环内毫秒级休眠等待，适配长连接监听场景

3.2 数据表与数据绑定接口

函数名称	功能描述
op2_new_table	创建空白数据表，用于承载请求参数或响应结果
op2_add_column	为数据表新增字段，定义字段名称、数据类型等属性
op2_append_row	向数据表末尾追加空行记录，用于批量填充数据
op2_new_row	独立创建单行数据对象，灵活组装单条数据
op2_append	将独立行对象追加至指定数据表
op2_bind_string	为数据表指定行列绑定字符串类型数值
op2_bind_int	为数据表指定行列绑定普通整型数值
op2_bind_int32	为数据表指定行列绑定32位整型数值
op2_bind_double	为数据表指定行列绑定双精度浮点数值

3.3 请求组装配置接口

函数名称	功能描述
op2_new_request	创建空白请求对象，作为所有操作的请求载体
op2_set_table	将数据表绑定至请求对象，关联请求入参数据
op2_set_option	配置请求核心参数，支持 Action、Reqid、SQL、interval 等
op2_add_filter	为请求添加自定义过滤条件，精准筛选目标数据
op2_set_indices	通过测点ID数组批量指定查询、订阅、写入的目标测点
op2_set_indices_string	通过测点点名字符串数组批量指定操作目标测点

3.4 请求发送与响应读取接口

函数名称	功能描述
op2_get_table	从请求或响应对象中提取数据表结构与数据
op2_get_stream	获取底层网络传输流对象，用于自定义传输配置
op2_set_compress	开启或关闭网络传输数据压缩，优化大批量数据传输性能
op2_write_request	底层写出请求头数据，业务层无需手动调用
op2_write_content	底层写出数据表请求内容，业务层无需手动调用
op2_flush_content	刷新发送缓冲区，强制推送缓存请求数据
op2_get_response	阻塞接收服务端返回的响应数据
op2_next_content	分段读取大批量响应结果，适配大数据查询场景
op2_get_errno	获取请求执行错误码，用于异常判断
op2_get_error	获取请求执行错误详细描述，用于问题排查

3.5 结果遍历与资源释放接口

函数名称	功能描述
op2_row_count	统计并返回结果数据表总行数
op2_column_count	统计并返回结果数据表总列数
op2_column_name	根据列索引获取对应字段名称
op2_set_rowid	设置数据读取游标，定位至指定行数据
op2_column_type	获取指定列的数据类型
op2_column_string	读取指定行列的字符串类型数值
op2_column_int	读取指定行列的整型数值
op2_column_double	读取指定行列的浮点类型数值
op2_free_request	释放请求对象内存资源，必调接口
op2_free_response	释放响应对象内存资源，必调接口

3.6 异步订阅专用接口

函数名称	功能描述
op2_open_async	开启异步长连接订阅通道，注册实时数据回调函数，持续接收服务端推送数据
op2_close_async	关闭异步订阅通道，终止实时数据推送，释放订阅资源

4、典型业务场景开发说明

4.1 数据查询场景

核心封装函数：opio_select、opio_select_archive。通过组合数据表创建、字段定义、测点绑定、条件过滤接口，组装查询请求，可实现测点静态配置、实时快照、历史归档数据的全场景查询，统一通过 opio_service 完成请求发送与结果解析。

4.2 数据写入场景

核心封装函数：opio_update_realtime（实时数据写入）、opio_update_archive（历史数据补录）、opio_insert（新增节点/测点）、opio_update（属性修改）、opio_delete（节点/测点删除）。依托行创建、数据绑定系列基础接口，实现各类数据与对象的写入操作。

4.3 结果解析场景

核心工具函数：opio_service、opio_show_table。统一封装响应接收、数据遍历、结果打印逻辑，通过行列统计、字段读取系列接口，标准化解析所有数据表返回结果，规避重复编码。

4.4 异步订阅场景

核心工具函数：opio_subscribe、onRealtime。基于异步订阅接口开启长连接，通过回调函数实时消费服务端推送的测点数据，适用于实时监控、数据大屏、高频采集等业务场景。

5、可编译运行示例代码（已修复BUG）

以下示例代码基于标准流程编写，可直接嵌入工程编译运行。

5.1 测点信息查询示例

cpp

int sample_select(OpenPlant op)
{
	// 创建测点数据表，定义查询字段
	op_table table = op2_new_table("Point");
	op2_add_column(table, "ID", vtNull, 0, 0, NULL, NULL);
	op2_add_column(table, "ND", vtNull, 0, 0, NULL, NULL);
	op2_add_column(table, "PN", vtNull, 0, 0, NULL, NULL);
	op2_add_column(table, "ED", vtNull, 0, 0, NULL, NULL);

	// 初始化请求对象并配置参数
	op_request request = op2_new_request();
	op2_set_table(request, table);
	op2_set_option(request, "Reqid", "1");
	op2_set_option(request, "Action", "Select");

	// 指定待查询测点
	const char *tags[] = { "W3.SYS.SESSION" };
	op2_set_indices_string(request, NULL, 1, tags);

	// 统一发送请求（修复变量未定义BUG）
	return opio_service(op, request, NULL, true);
}

5.2 测点属性更新示例

cpp

int sample_update(OpenPlant op)
{
	// 创建数据表并定义可修改字段
	op_table table = op2_new_table("Point");
	op2_add_column(table, "ND", vtInt32, 0, 0, NULL, NULL);
	op2_add_column(table, "PN", vtString, 0, 0, NULL, NULL);
	op2_add_column(table, "ED", vtString, 0, 0, NULL, NULL);

	// 组装待更新数据
	op2_append_row(table);
	op2_bind_int(table, 0, 14);
	op2_bind_string(table, 1, "AX");
	op2_bind_string(table, 2, "This is a test");

	// 初始化并配置更新请求
	op_request request = op2_new_request();
	op2_set_table(request, table);
	op2_set_option(request, "Reqid", "1");
	op2_set_option(request, "Action", "Update");

	// 统一发送请求（修复变量未定义BUG）
	return opio_service(op, request, NULL, true);
}

5.3 原生SQL执行示例

cpp

int sample_exec_sql(OpenPlant op)
{
	// 初始化SQL执行请求
	op_request request = op2_new_request();
	op2_set_option(request, "Reqid", "1");
	op2_set_option(request, "Action", "ExecSQL");
	op2_set_option(request, "SQL", "select count(*) from Database");

	// 统一发送请求（修复变量未定义BUG）
	return opio_service(op, request, NULL, true);
}

6、开发使用规范建议

本文档覆盖工程高频业务接口，可与源代码一一对应查阅，完整接口定义以官方头文件 include/opapi2.h、include/op_service.h 为准。
开发过程中优先复用 opio_service 通用请求流程，统一处理请求发送、异常捕获、资源释放，减少重复代码与内存泄漏风险。
严格区分版本使用规范，新项目统一使用 V4.0/V5.0 新版句柄接口，不推荐 V3.0 老旧接口。
所有请求、响应、数据表对象使用完毕后，必须主动调用对应释放接口，保障程序长期稳定运行。

7、老旧接口说明（适配数据库V3.0，仅存量迁移使用）

重要规范：V3.0 接口架构较老、无统一资源管理、不支持异步订阅，存在稳定性与扩展性短板。所有新项目禁止使用，仅用于存量老系统维护、版本迁移过渡。

7.1 V3.0 通用调用步骤

调用 op2_init 建立数据库连接，校验连接句柄有效性；
通过有效句柄调用各类读写、查询、运维接口；
校验接口返回错误码，解析结果集业务数据；
手动释放所有对象、列表、结果集内存资源；
业务结束调用 op2_close 关闭数据库连接。

7.2 核心接口分类说明

7.2.1 连接管理接口

函数名称	功能描述
op2_init	初始化数据库连接，获取操作句柄
op2_close	关闭数据库连接，释放句柄
op2_status	检测连接句柄状态，判断链路是否有效

7.2.2 节点/测点增删改查接口

cpp

// 对象创建与资源释放
op2_new_object        // 创建测点/节点对象
op2_free_object       // 释放对象资源

// 对象查询接口
op2_get_object_byid   // 通过唯一ID获取对象
op2_get_object_byname // 通过点名获取对象
op2_get_child         // 获取目标对象的全部子节点列表
op2_get_child_idname  // 获取子节点ID、点名精简列表
op2_free_list         // 释放列表内存资源
op2_get_database      // 获取数据库根节点列表

// 对象属性读取
op2_object_get_double
op2_object_get_int
op2_object_get_string

// 对象属性设置
op2_object_set_double
op2_object_set_int
op2_object_set_string

// 持久化提交（增/删/改唯一入口）
op2_modify_object

7.2.3 实时数据写入接口

函数名称	功能描述
op2_write_value	批量测点同一时间戳写入，同步更新数值与状态
op2_write_value_tm	批量测点独立时间戳，分别写入数值与状态
op2_write_value_only	仅写入测点实时数值，不更新测点状态

7.2.4 实时数据读取接口

函数名称	功能描述
op2_get_value_byname	通过测点点名读取TM、AS、AV实时动态数据
op2_get_value_byid	通过测点ID读取TM、AS、AV实时动态数据

7.2.5 历史数据补录接口

函数名称	功能描述
op2_write_histroy_byid	通过测点ID无压缩补录时间段完整历史数据
op2_write_histroy_byname	通过测点点名无压缩补录时间段完整历史数据
op2_write_snap	通过测点ID补录指定时刻快照数据，高效轻量化
op2_write_cache	批量压缩过滤，快速补录历史数据至本地缓存
op2_write_cache_one	单测点压缩过滤，快速补录历史数据

7.2.6 历史数据查询接口

函数名称	功能描述
op2_get_history_byid	通过ID查询指定时间段完整历史数据
op2_get_history_byname	通过点名查询指定时间段完整历史数据
op2_get_histroy_top_byid	通过ID限量查询历史数据，限制返回数据条数
op2_get_histroy_top_byname	通过点名限量查询历史数据，限制返回数据条数
op2_get_snap_byid	通过ID查询指定时刻快照，无数据时自动插值估算
op2_get_snap_byname	通过点名查询指定时刻快照，无数据时自动插值估算
op2_raw_to_span	将压缩缓存历史数据还原为标准等间距时序数据

7.2.7 辅助工具接口

时间工具

函数名称	功能描述
op2_get_system_time	获取数据库服务器标准时间戳
op2_decode_time	时间戳解析为年月日、时分秒分段时间
op2_encode_time	分段时间编码为标准时间戳

点组批量操作工具

函数名称	功能描述
op2_new_group	创建测点分组容器，用于批量管理测点
op2_add_group_point	向测点分组添加指定点名
op2_group_size	获取测点分组内的测点总数

历史结果集解析工具

函数名称	功能描述
op2_fetch_timed_value	解析原始历史结果集，获取单条数据时间、状态、数值
op2_fetch_stat_value	解析历史统计结果集，获取统计结构体数据
op2_num_rows	统计结果集数据总行数
op2_free_result	释放历史结果集内存资源

opBuffer 缓存配置工具

opBuffer 为API内置本地缓存机制，可在网络中断、服务器异常时缓存写入数据，链路恢复后自动续传，有效避免数据丢失，支持自定义缓存参数：

函数名称	功能描述
op2_buffer_set_point	配置缓存关联测点属性
op2_buffer_set_int	配置整型缓存参数
op2_buffer_set_string	配置字符串型缓存参数

配置

数据

网络

维护

openPlant C++ 语言接口使用说明 ​

1、基础知识 ​

1.1 测点属性分类 ​

1.2 数据类型定义 ​

2、新版接口总览（适配 V4.0 / V5.0） ​

2.1 架构设计 ​

2.2 核心对象说明 ​

2.3 核心能力覆盖 ​

2.4 标准调用流程 ​

2.4.1 同步调用流程（常规查询、写入、SQL执行） ​

2.4.2 异步订阅流程（实时数据推送） ​

3、新版接口详细说明（V4.0/V5.0） ​

3.1 连接与时间工具接口 ​

3.2 数据表与数据绑定接口 ​

3.3 请求组装配置接口 ​

3.4 请求发送与响应读取接口 ​

3.5 结果遍历与资源释放接口 ​

3.6 异步订阅专用接口 ​

4、典型业务场景开发说明 ​

4.1 数据查询场景 ​

4.2 数据写入场景 ​

4.3 结果解析场景 ​

4.4 异步订阅场景 ​

5、可编译运行示例代码（已修复BUG） ​

5.1 测点信息查询示例 ​

5.2 测点属性更新示例 ​

5.3 原生SQL执行示例 ​

6、开发使用规范建议 ​

7、老旧接口说明（适配 数据库V3.0，仅存量迁移使用） ​

7.1 V3.0 通用调用步骤 ​

7.2 核心接口分类说明 ​

7.2.1 连接管理接口 ​

7.2.2 节点/测点增删改查接口 ​

7.2.3 实时数据写入接口 ​

7.2.4 实时数据读取接口 ​

7.2.5 历史数据补录接口 ​

7.2.6 历史数据查询接口 ​

7.2.7 辅助工具接口 ​