1885 lines
61 KiB
Markdown
1885 lines
61 KiB
Markdown
# libiec61850 客户端开发手册
|
|
|
|
> 基于 libiec61850 v1.5.3 完整 API 参考。本文档旨在做到脱离代码即可完成客户端开发。
|
|
|
|
---
|
|
|
|
## 目录
|
|
|
|
1. [概述与连接生命周期](#1-概述与连接生命周期)
|
|
2. [IedConnection 连接管理](#2-iedconnection-连接管理)
|
|
3. [数据读写操作](#3-数据读写操作)
|
|
4. [数据集 (DataSet) 操作](#4-数据集-dataset-操作)
|
|
5. [报告 (Report) 控制](#5-报告-report-控制)
|
|
6. [控制操作 (Control)](#6-控制操作-control)
|
|
7. [服务器目录浏览与发现](#7-服务器目录浏览与发现)
|
|
8. [文件服务](#8-文件服务)
|
|
9. [日志服务 (Journal)](#9-日志服务-journal)
|
|
10. [GOOSE 订阅](#10-goose-订阅)
|
|
11. [GOOSE 发布 (独立)](#11-goose-发布-独立)
|
|
12. [Sampled Values 客户端](#12-sampled-values-客户端)
|
|
13. [SV 控制块 (SVCB)](#13-sv-控制块-svcb)
|
|
14. [MmsValue 完整操作手册](#14-mmsvalue-完整操作手册)
|
|
15. [MmsVariableSpecification](#15-mmsvariablespecification)
|
|
16. [TLS 安全连接](#16-tls-安全连接)
|
|
17. [单线程模式 (非线程模式)](#17-单线程模式-非线程模式)
|
|
18. [MmsConnection 底层接口](#18-mmsconnection-底层接口)
|
|
19. [完整代码示例](#19-完整代码示例)
|
|
|
|
---
|
|
|
|
## 1. 概述与连接生命周期
|
|
|
|
```
|
|
IedConnection_create() // 创建连接实例
|
|
↓
|
|
[可选] 设置本地地址/超时
|
|
↓
|
|
IedConnection_connect() // 连接到服务器 (阻塞)
|
|
↓
|
|
读写操作 / 报告订阅 / 控制操作
|
|
↓
|
|
IedConnection_close() // 关闭连接 (推荐)
|
|
or IedConnection_abort() // 中断连接
|
|
or IedConnection_release() // 正常释放 (MMS Conclude)
|
|
↓
|
|
IedConnection_destroy() // 销毁并释放所有资源
|
|
```
|
|
|
|
### 1.1 连接状态枚举
|
|
|
|
```c
|
|
typedef enum {
|
|
IED_STATE_CLOSED = 0, // 关闭/空闲
|
|
IED_STATE_CONNECTING, // 正在连接
|
|
IED_STATE_CONNECTED, // 已连接
|
|
IED_STATE_CLOSING // 正在关闭
|
|
} IedConnectionState;
|
|
```
|
|
|
|
### 1.2 错误码枚举 (IedClientError)
|
|
|
|
| 错误码 | 值 | 含义 |
|
|
|--------|-----|------|
|
|
| `IED_ERROR_OK` | 0 | 成功 |
|
|
| `IED_ERROR_NOT_CONNECTED` | 1 | 未连接 |
|
|
| `IED_ERROR_ALREADY_CONNECTED` | 2 | 已连接 |
|
|
| `IED_ERROR_CONNECTION_LOST` | 3 | 连接丢失 |
|
|
| `IED_ERROR_SERVICE_NOT_SUPPORTED` | 4 | 服务/参数不支持 |
|
|
| `IED_ERROR_CONNECTION_REJECTED` | 5 | 连接被拒绝 |
|
|
| `IED_ERROR_OUTSTANDING_CALL_LIMIT_REACHED` | 6 | 未完成调用达到上限 |
|
|
| `IED_ERROR_USER_PROVIDED_INVALID_ARGUMENT` | 10 | 无效参数 |
|
|
| `IED_ERROR_ENABLE_REPORT_FAILED_DATASET_MISMATCH` | 11 | 报告启用: 数据集不匹配 |
|
|
| `IED_ERROR_OBJECT_REFERENCE_INVALID` | 12 | 对象引用语法错误 |
|
|
| `IED_ERROR_UNEXPECTED_VALUE_RECEIVED` | 13 | 收到意外类型 |
|
|
| `IED_ERROR_TIMEOUT` | 20 | 超时 |
|
|
| `IED_ERROR_ACCESS_DENIED` | 21 | 访问拒绝 |
|
|
| `IED_ERROR_OBJECT_DOES_NOT_EXIST` | 22 | 对象不存在 |
|
|
| `IED_ERROR_OBJECT_EXISTS` | 23 | 对象已存在 |
|
|
| `IED_ERROR_OBJECT_ACCESS_UNSUPPORTED` | 24 | 不支持的访问方法 |
|
|
| `IED_ERROR_TYPE_INCONSISTENT` | 25 | 类型不一致 |
|
|
| `IED_ERROR_TEMPORARILY_UNAVAILABLE` | 26 | 暂时不可用 |
|
|
| `IED_ERROR_OBJECT_UNDEFINED` | 27 | 对象未定义 |
|
|
| `IED_ERROR_INVALID_ADDRESS` | 28 | 无效地址 |
|
|
| `IED_ERROR_HARDWARE_FAULT` | 29 | 硬件故障 |
|
|
| `IED_ERROR_TYPE_UNSUPPORTED` | 30 | 类型不支持 |
|
|
| `IED_ERROR_OBJECT_ATTRIBUTE_INCONSISTENT` | 31 | 属性不一致 |
|
|
| `IED_ERROR_OBJECT_VALUE_INVALID` | 32 | 值无效 |
|
|
| `IED_ERROR_OBJECT_INVALIDATED` | 33 | 对象已失效 |
|
|
| `IED_ERROR_MALFORMED_MESSAGE` | 34 | 格式错误的消息 |
|
|
| `IED_ERROR_SERVICE_NOT_IMPLEMENTED` | 98 | 服务未实现 |
|
|
| `IED_ERROR_UNKNOWN` | 99 | 未知错误 |
|
|
|
|
---
|
|
|
|
## 2. IedConnection 连接管理
|
|
|
|
### 2.1 创建连接实例
|
|
|
|
```c
|
|
// 基本创建 (多线程模式, 非TLS)
|
|
IedConnection IedConnection_create(void);
|
|
|
|
// 扩展创建
|
|
IedConnection IedConnection_createEx(
|
|
TLSConfiguration tlsConfig, // TLS 配置, NULL 表示非TLS
|
|
bool useThreads); // true=多线程, false=单线程
|
|
// useThreads=false 时需要使用异步API + IedConnection_tick()
|
|
|
|
// 创建 TLS 连接 (已废弃, 推荐使用 createEx)
|
|
IedConnection IedConnection_createWithTlsSupport(TLSConfiguration tlsConfig);
|
|
|
|
// 销毁连接 (自动关闭已连接)
|
|
void IedConnection_destroy(IedConnection self);
|
|
```
|
|
|
|
### 2.2 连接配置
|
|
|
|
```c
|
|
// 设置本地地址/端口
|
|
void IedConnection_setLocalAddress(IedConnection self,
|
|
const char* localIpAddress, int localPort);
|
|
// localPort < 1 时由OS自动选择端口
|
|
// 必须在 connect 前调用
|
|
|
|
// 设置连接超时 (ms)
|
|
void IedConnection_setConnectTimeout(IedConnection self, uint32_t timeoutInMs);
|
|
// 必须在 connect 前调用
|
|
|
|
// 设置请求超时 (ms) - 可随时调用
|
|
void IedConnection_setRequestTimeout(IedConnection self, uint32_t timeoutInMs);
|
|
|
|
// 获取请求超时
|
|
uint32_t IedConnection_getRequestTimeout(IedConnection self);
|
|
|
|
// 设置客户端生成的所有时间戳的时间品质
|
|
void IedConnection_setTimeQuality(IedConnection self,
|
|
bool leapSecondKnown,
|
|
bool clockFailure,
|
|
bool clockNotSynchronized,
|
|
int subsecondPrecision);
|
|
```
|
|
|
|
### 2.3 连接与断开
|
|
|
|
```c
|
|
// === 同步连接 (阻塞直到连接建立或超时) ===
|
|
void IedConnection_connect(IedConnection self,
|
|
IedClientError* error, // 输出: 错误码
|
|
const char* hostname, // 主机名或IP地址
|
|
int tcpPort); // TCP端口
|
|
|
|
// === 异步连接 (立即返回) ===
|
|
void IedConnection_connectAsync(IedConnection self,
|
|
IedClientError* error,
|
|
const char* hostname,
|
|
int tcpPort);
|
|
// 需要通过状态变化处理器或轮询 IedConnection_getState() 来跟踪状态
|
|
|
|
// === 获取连接状态 ===
|
|
IedConnectionState IedConnection_getState(IedConnection self);
|
|
|
|
// === 获取最后一次应用错误 ===
|
|
LastApplError IedConnection_getLastApplError(IedConnection self);
|
|
// LastApplError 结构:
|
|
// int ctlNum;
|
|
// ControlLastApplError error;
|
|
// ControlAddCause addCause;
|
|
|
|
// === 连接断开方法 ===
|
|
|
|
// 关闭连接 (简单关闭TCP, 无握手) - 推荐
|
|
void IedConnection_close(IedConnection self);
|
|
|
|
// Abort (发送 ACSE abort 消息后关闭)
|
|
void IedConnection_abort(IedConnection self, IedClientError* error);
|
|
|
|
// 异步 Abort
|
|
void IedConnection_abortAsync(IedConnection self, IedClientError* error);
|
|
|
|
// Release (发送 MMS conclude 消息 - 正常释放)
|
|
void IedConnection_release(IedConnection self, IedClientError* error);
|
|
// 注意: 服务器可能拒绝, 此时连接仍保持
|
|
|
|
// 异步 Release
|
|
void IedConnection_releaseAsync(IedConnection self, IedClientError* error);
|
|
```
|
|
|
|
### 2.4 连接状态回调
|
|
|
|
```c
|
|
// 状态变化处理器 (推荐)
|
|
typedef void (*IedConnection_StateChangedHandler)(
|
|
void* parameter,
|
|
IedConnection connection,
|
|
IedConnectionState newState);
|
|
|
|
void IedConnection_installStateChangedHandler(IedConnection self,
|
|
IedConnection_StateChangedHandler handler, void* parameter);
|
|
|
|
// 旧版连接关闭处理器 (已废弃)
|
|
typedef void (*IedConnectionClosedHandler)(
|
|
void* parameter, IedConnection connection);
|
|
|
|
void IedConnection_installConnectionClosedHandler(IedConnection self,
|
|
IedConnectionClosedHandler handler, void* parameter);
|
|
```
|
|
|
|
### 2.5 底层连接访问
|
|
|
|
```c
|
|
// 获取底层 MmsConnection (用于直接调用 MMS 级服务)
|
|
MmsConnection IedConnection_getMmsConnection(IedConnection self);
|
|
|
|
// 单线程模式: 周期性调用以处理连接事件
|
|
bool IedConnection_tick(IedConnection self);
|
|
// 返回: true = 连接等待中可挂起, false = 忙需尽快再调用
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 数据读写操作
|
|
|
|
### 3.1 同步读取
|
|
|
|
```c
|
|
// 读取单个对象
|
|
MmsValue* IedConnection_readObject(IedConnection self,
|
|
IedClientError* error,
|
|
const char* objectReference, // 对象引用路径, 如 "simpleIOGenericIO/GGIO1.AnIn1.mag.f"
|
|
FunctionalConstraint fc); // 功能约束, 如 IEC61850_FC_MX
|
|
// 返回: MmsValue* 或 NULL (失败)
|
|
// 注意: 即使 mmsError=OK, 返回值也可能为 NULL (服务器返回空结果列表)
|
|
|
|
// 读取数组元素 (支持索引语法)
|
|
// "testComplexArray/MHAI1.HA.phsAHar(2).cVal.mag.f" // 数组第2个元素的子属性
|
|
```
|
|
|
|
### 3.2 异步读取
|
|
|
|
```c
|
|
// 回调类型
|
|
typedef void (*IedConnection_ReadObjectHandler)(
|
|
uint32_t invokeId, // 请求调用ID
|
|
void* parameter, // 用户参数
|
|
IedClientError err, // 错误码
|
|
MmsValue* value); // 读取的值 (需由用户 MmsValue_delete 释放!)
|
|
|
|
// 异步读取
|
|
void IedConnection_readObjectAsync(IedConnection self,
|
|
IedClientError* error,
|
|
const char* objectReference,
|
|
FunctionalConstraint fc,
|
|
IedConnection_ReadObjectHandler handler,
|
|
void* parameter);
|
|
```
|
|
|
|
### 3.3 同步写入
|
|
|
|
```c
|
|
// 写入单个对象
|
|
void IedConnection_writeObject(IedConnection self,
|
|
IedClientError* error,
|
|
const char* objectReference,
|
|
FunctionalConstraint fc,
|
|
MmsValue* value);
|
|
|
|
// 示例: 写 Visible String
|
|
MmsValue* val = MmsValue_newVisibleString("libiec61850.com");
|
|
IedConnection_writeObject(con, &error,
|
|
"simpleIOGenericIO/GGIO1.NamPlt.vendor", IEC61850_FC_DC, val);
|
|
MmsValue_delete(val);
|
|
```
|
|
|
|
### 3.4 异步写入
|
|
|
|
```c
|
|
// 通用回调
|
|
typedef void (*IedConnection_GenericServiceHandler)(
|
|
uint32_t invokeId, void* parameter, IedClientError err);
|
|
|
|
void IedConnection_writeObjectAsync(IedConnection self,
|
|
IedClientError* error,
|
|
const char* objectReference,
|
|
FunctionalConstraint fc,
|
|
MmsValue* value,
|
|
IedConnection_GenericServiceHandler handler,
|
|
void* parameter);
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 数据集 (DataSet) 操作
|
|
|
|
### 4.1 ClientDataSet 类型
|
|
|
|
```c
|
|
typedef struct sClientDataSet* ClientDataSet;
|
|
|
|
// 读取数据集值
|
|
ClientDataSet IedConnection_readDataSetValues(IedConnection self,
|
|
IedClientError* error,
|
|
const char* dataSetReference, // 如 "simpleIOGenericIO/LLN0.Events"
|
|
ClientDataSet dataSet); // 可复用已有实例或传 NULL
|
|
// 返回: ClientDataSet 实例或 NULL
|
|
|
|
// 异步版本
|
|
void IedConnection_readDataSetValuesAsync(IedConnection self,
|
|
IedClientError* error,
|
|
const char* dataSetReference,
|
|
ClientDataSet dataSet,
|
|
IedConnection_ReadDataSetHandler handler, void* parameter);
|
|
|
|
// 获取数据集大小
|
|
int ClientDataSet_getDataSetSize(ClientDataSet self);
|
|
|
|
// 获取数据集值 (返回 MMS_ARRAY 类型的 MmsValue*)
|
|
MmsValue* ClientDataSet_getValues(ClientDataSet self);
|
|
|
|
// 获取数据集目录 (返回 LinkedList<char*> 元素名称列表)
|
|
LinkedList IedConnection_getDataSetDirectory(IedConnection self,
|
|
IedClientError* error,
|
|
const char* dataSetReference,
|
|
ClientDataSet dataSet);
|
|
|
|
// 写入数据集值
|
|
void IedConnection_writeDataSetValuesAsync(IedConnection self,
|
|
IedClientError* error,
|
|
const char* dataSetReference,
|
|
LinkedList /* <MmsValue*> */ values,
|
|
IedConnection_WriteDataSetHandler handler, void* parameter);
|
|
|
|
// 销毁数据集
|
|
void ClientDataSet_destroy(ClientDataSet self);
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 报告 (Report) 控制
|
|
|
|
### 5.1 报告回调
|
|
|
|
```c
|
|
// 报告回调函数类型
|
|
typedef void (*ReportCallbackFunction)(
|
|
void* parameter, // 用户参数
|
|
ClientReport report); // 报告对象
|
|
|
|
// 安装报告处理器
|
|
void IedConnection_installReportHandler(IedConnection self,
|
|
const char* rcbReference, // RCB引用, 如 "simpleIOGenericIO/LLN0.RP.EventsRCB01"
|
|
const char* rptId, // 报告ID (从 ClientReportControlBlock_getRptId 获取)
|
|
ReportCallbackFunction handler,
|
|
void* parameter);
|
|
```
|
|
|
|
### 5.2 ClientReport 读取
|
|
|
|
```c
|
|
// 获取报告中的数据集值
|
|
MmsValue* ClientReport_getDataSetValues(ClientReport report);
|
|
|
|
// 获取 RCB 引用
|
|
const char* ClientReport_getRcbReference(ClientReport report);
|
|
|
|
// 获取报告ID
|
|
const char* ClientReport_getRptId(ClientReport report);
|
|
|
|
// 检查报告是否包含时间戳
|
|
bool ClientReport_hasTimestamp(ClientReport report);
|
|
|
|
// 获取报告时间戳 (Unix 毫秒时间戳)
|
|
uint64_t ClientReport_getTimestamp(ClientReport report);
|
|
|
|
// 获取某个数据成员的包含原因
|
|
ReasonForInclusion ClientReport_getReasonForInclusion(ClientReport report, int index);
|
|
|
|
// 包含原因枚举值:
|
|
// IEC61850_REASON_NOT_INCLUDED - 未包含
|
|
// IEC61850_REASON_DATA_CHANGE - 数据变化
|
|
// IEC61850_REASON_QUALITY_CHANGE - 品质变化
|
|
// IEC61850_REASON_DATA_UPDATE - 数据更新
|
|
// IEC61850_REASON_INTEGRITY - 完整性
|
|
// IEC61850_REASON_GI - 总召唤
|
|
// IEC61850_REASON_APPLICATION_TRIGGER - 应用触发
|
|
```
|
|
|
|
### 5.3 ClientReportControlBlock 操作
|
|
|
|
```c
|
|
// RCB 元素标志 (用于 setRCBValues)
|
|
#define RCB_ELEMENT_RPT_ENA 1
|
|
#define RCB_ELEMENT_RESV 2
|
|
#define RCB_ELEMENT_DATSET 4
|
|
#define RCB_ELEMENT_TRG_OPS 8
|
|
#define RCB_ELEMENT_OPT_FLDS 16
|
|
#define RCB_ELEMENT_BUF_TIME 32
|
|
#define RCB_ELEMENT_INTG_PD 64
|
|
#define RCB_ELEMENT_GI 128
|
|
#define RCB_ELEMENT_PURGE_BUF 256
|
|
#define RCB_ELEMENT_ENTRY_ID 512
|
|
|
|
// 创建 RCB 客户端对象
|
|
ClientReportControlBlock ClientReportControlBlock_create(const char* objectReference);
|
|
|
|
// 读取 RCB 值 (从服务器)
|
|
ClientReportControlBlock IedConnection_getRCBValues(IedConnection self,
|
|
IedClientError* error,
|
|
const char* rcbReference,
|
|
ClientReportControlBlock rcb); // 已有对象或 NULL
|
|
|
|
// 异步读取 RCB
|
|
void IedConnection_getRCBValuesAsync(IedConnection self,
|
|
IedClientError* error,
|
|
const char* rcbReference,
|
|
ClientReportControlBlock rcb,
|
|
IedConnection_GetRCBValuesHandler handler, void* parameter);
|
|
|
|
// 设置 RCB 值 (写入服务器)
|
|
void IedConnection_setRCBValues(IedConnection self,
|
|
IedClientError* error,
|
|
ClientReportControlBlock rcb,
|
|
uint32_t parameterMask, // 要写入的参数掩码 (RCB_ELEMENT_*)
|
|
bool singleRequest); // true=单请求, false=分多请求
|
|
|
|
// 异步设置 RCB
|
|
void IedConnection_setRCBValuesAsync(IedConnection self,
|
|
IedClientError* error,
|
|
ClientReportControlBlock rcb,
|
|
uint32_t parameterMask,
|
|
bool singleRequest,
|
|
IedConnection_GenericServiceHandler handler, void* parameter);
|
|
|
|
// === ClientReportControlBlock getters/setters ===
|
|
const char* ClientReportControlBlock_getObjectReference(ClientReportControlBlock self);
|
|
const char* ClientReportControlBlock_getRptId(ClientReportControlBlock self);
|
|
bool ClientReportControlBlock_getRptEna(ClientReportControlBlock self);
|
|
|
|
void ClientReportControlBlock_setRptEna(ClientReportControlBlock self, bool value);
|
|
void ClientReportControlBlock_setRptId(ClientReportControlBlock self, const char* rptId);
|
|
void ClientReportControlBlock_setDataSetReference(ClientReportControlBlock self, const char* dataSetRef);
|
|
void ClientReportControlBlock_setTrgOps(ClientReportControlBlock self, uint8_t trgOps);
|
|
void ClientReportControlBlock_setOptFlds(ClientReportControlBlock self, uint8_t optFlds);
|
|
void ClientReportControlBlock_setBufTm(ClientReportControlBlock self, uint32_t bufTm);
|
|
void ClientReportControlBlock_setIntgPd(ClientReportControlBlock self, uint32_t intgPd);
|
|
void ClientReportControlBlock_setGI(ClientReportControlBlock self, bool value);
|
|
void ClientReportControlBlock_setResv(ClientReportControlBlock self, bool value);
|
|
void ClientReportControlBlock_setPurgeBuf(ClientReportControlBlock self, bool value);
|
|
void ClientReportControlBlock_setEntryId(ClientReportControlBlock self, uint8_t* entryId);
|
|
|
|
// 销毁
|
|
void ClientReportControlBlock_destroy(ClientReportControlBlock self);
|
|
```
|
|
|
|
### 5.4 报告配置典型流程
|
|
|
|
```c
|
|
// 1. 获取当前 RCB 值
|
|
ClientReportControlBlock rcb =
|
|
IedConnection_getRCBValues(con, &error, "simpleIOGenericIO/LLN0.RP.EventsRCB01", NULL);
|
|
|
|
// 2. 获取 rptId (用于报告回调匹配)
|
|
const char* rptId = ClientReportControlBlock_getRptId(rcb);
|
|
|
|
// 3. 安装报告回调
|
|
IedConnection_installReportHandler(con,
|
|
"simpleIOGenericIO/LLN0.RP.EventsRCB01",
|
|
rptId, reportCallback, NULL);
|
|
|
|
// 4. 配置 RCB 参数
|
|
ClientReportControlBlock_setTrgOps(rcb,
|
|
TRG_OPT_DATA_UPDATE | TRG_OPT_INTEGRITY | TRG_OPT_GI);
|
|
ClientReportControlBlock_setRptEna(rcb, true);
|
|
ClientReportControlBlock_setIntgPd(rcb, 5000); // 5秒完整性周期
|
|
|
|
// 5. 写入服务器
|
|
IedConnection_setRCBValues(con, &error, rcb,
|
|
RCB_ELEMENT_RPT_ENA | RCB_ELEMENT_TRG_OPS | RCB_ELEMENT_INTG_PD,
|
|
true);
|
|
|
|
// 6. 触发总召唤 (GI)
|
|
Thread_sleep(1000);
|
|
ClientReportControlBlock_setGI(rcb, true);
|
|
IedConnection_setRCBValues(con, &error, rcb, RCB_ELEMENT_GI, true);
|
|
|
|
// 7. 一段时间后禁用报告
|
|
ClientReportControlBlock_setRptEna(rcb, false);
|
|
IedConnection_setRCBValues(con, &error, rcb, RCB_ELEMENT_RPT_ENA, true);
|
|
|
|
// 8. 清理
|
|
ClientReportControlBlock_destroy(rcb);
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 控制操作 (Control)
|
|
|
|
### 6.1 ControlObjectClient 创建与销毁
|
|
|
|
```c
|
|
// 创建控制对象客户端 (多线程模式)
|
|
ControlObjectClient ControlObjectClient_create(
|
|
const char* objectReference, // 如 "simpleIOGenericIO/GGIO1.SPCSO1"
|
|
IedConnection connection);
|
|
|
|
// 创建控制对象客户端 (非线程模式 - 需提供 varSpec)
|
|
ControlObjectClient ControlObjectClient_createEx(
|
|
const char* objectReference,
|
|
IedConnection connection,
|
|
ControlModel controlModel, // 控制模型
|
|
MmsVariableSpecification* varSpec); // 变量类型规格
|
|
|
|
// 销毁控制对象
|
|
void ControlObjectClient_destroy(ControlObjectClient self);
|
|
```
|
|
|
|
### 6.2 控制操作函数
|
|
|
|
```c
|
|
// === 直接操作 (Direct Operate) ===
|
|
bool ControlObjectClient_operate(ControlObjectClient self,
|
|
MmsValue* ctlVal, // 控制值
|
|
uint64_t timeStamp); // 定时操作的时间戳, 0=立即执行
|
|
// 返回: true=成功, false=失败
|
|
|
|
// === 选择 (Select) ===
|
|
bool ControlObjectClient_select(ControlObjectClient self);
|
|
// 返回: true=选择成功
|
|
|
|
// === 带值选择 (Select With Value) ===
|
|
bool ControlObjectClient_selectWithValue(ControlObjectClient self,
|
|
MmsValue* ctlVal);
|
|
|
|
// === 取消 (Cancel) ===
|
|
bool ControlObjectClient_cancel(ControlObjectClient self);
|
|
|
|
// === 异步操作 ===
|
|
void ControlObjectClient_operateAsync(ControlObjectClient self,
|
|
IedClientError* error,
|
|
MmsValue* ctlVal,
|
|
uint64_t timeStamp,
|
|
ControlAsyncHandler handler, void* parameter);
|
|
|
|
void ControlObjectClient_selectAsync(ControlObjectClient self,
|
|
IedClientError* error,
|
|
ControlAsyncHandler handler, void* parameter);
|
|
|
|
void ControlObjectClient_selectWithValueAsync(ControlObjectClient self,
|
|
IedClientError* error,
|
|
MmsValue* ctlVal,
|
|
ControlAsyncHandler handler, void* parameter);
|
|
|
|
// 异步回调类型
|
|
typedef void (*ControlAsyncHandler)(
|
|
uint32_t invokeId, void* parameter,
|
|
IedClientError err,
|
|
ControlActionType type, // select/operate/cancel
|
|
bool success);
|
|
```
|
|
|
|
### 6.3 CommandTermination (增强安全)
|
|
|
|
```c
|
|
// 命令终止处理器
|
|
typedef void (*CommandTerminationHandler)(
|
|
void* parameter,
|
|
ControlObjectClient connection);
|
|
|
|
void ControlObjectClient_setCommandTerminationHandler(
|
|
ControlObjectClient self,
|
|
CommandTerminationHandler handler, void* parameter);
|
|
|
|
// 获取上次应用错误
|
|
LastApplError ControlObjectClient_getLastApplError(ControlObjectClient self);
|
|
// LastApplError 包含: .ctlNum, .error, .addCause
|
|
// 当 error != 0 表示 CommandTermination-
|
|
// 当 error == 0 表示 CommandTermination+
|
|
```
|
|
|
|
### 6.4 来源设置
|
|
|
|
```c
|
|
// 设置控制来源
|
|
void ControlObjectClient_setOrigin(ControlObjectClient self,
|
|
const char* orIdent, // 来源标识字符串
|
|
int orCat); // 来源类别 (orCat)
|
|
|
|
// 来源类别常量 (orCat):
|
|
// CONTROL_ORCAT_NOT_SUPPORTED = 0
|
|
// CONTROL_ORCAT_BAY_CONTROL = 1
|
|
// CONTROL_ORCAT_STATION_CONTROL = 2
|
|
// CONTROL_ORCAT_REMOTE_CONTROL = 3
|
|
// CONTROL_ORCAT_AUTOMATIC_BAY = 4
|
|
// CONTROL_ORCAT_AUTOMATIC_STATION = 5
|
|
// CONTROL_ORCAT_AUTOMATIC_REMOTE = 6
|
|
// CONTROL_ORCAT_MAINTENANCE = 7
|
|
// CONTROL_ORCAT_PROCESS = 8
|
|
```
|
|
|
|
### 6.5 四种控制方式示例
|
|
|
|
```c
|
|
// 1. 直接控制 (Direct Normal)
|
|
ControlObjectClient ctl = ControlObjectClient_create(ref, con);
|
|
MmsValue* val = MmsValue_newBoolean(true);
|
|
ControlObjectClient_setOrigin(ctl, NULL, 3);
|
|
ControlObjectClient_operate(ctl, val, 0);
|
|
MmsValue_delete(val);
|
|
ControlObjectClient_destroy(ctl);
|
|
|
|
// 2. 选择前操作 (SBO Normal)
|
|
ControlObjectClient ctl = ControlObjectClient_create(ref, con);
|
|
if (ControlObjectClient_select(ctl)) {
|
|
MmsValue* val = MmsValue_newBoolean(true);
|
|
ControlObjectClient_operate(ctl, val, 0);
|
|
MmsValue_delete(val);
|
|
}
|
|
ControlObjectClient_destroy(ctl);
|
|
|
|
// 3. 直接控制-增强安全 (Direct Enhanced)
|
|
ControlObjectClient ctl = ControlObjectClient_create(ref, con);
|
|
ControlObjectClient_setCommandTerminationHandler(ctl, termHandler, NULL);
|
|
MmsValue* val = MmsValue_newBoolean(true);
|
|
ControlObjectClient_operate(ctl, val, 0);
|
|
// 等待 CommandTermination 回调
|
|
Thread_sleep(1000);
|
|
MmsValue_delete(val);
|
|
ControlObjectClient_destroy(ctl);
|
|
|
|
// 4. 选择前操作-增强安全 (SBO Enhanced)
|
|
ControlObjectClient ctl = ControlObjectClient_create(ref, con);
|
|
ControlObjectClient_setCommandTerminationHandler(ctl, termHandler, NULL);
|
|
MmsValue* val = MmsValue_newBoolean(true);
|
|
if (ControlObjectClient_selectWithValue(ctl, val)) {
|
|
ControlObjectClient_operate(ctl, val, 0);
|
|
Thread_sleep(1000);
|
|
}
|
|
MmsValue_delete(val);
|
|
ControlObjectClient_destroy(ctl);
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 服务器目录浏览与发现
|
|
|
|
### 7.1 同步函数
|
|
|
|
```c
|
|
// 获取服务器目录 (逻辑设备列表)
|
|
LinkedList IedConnection_getServerDirectory(IedConnection self,
|
|
IedClientError* error,
|
|
const char* continueAfter, // 续传点, 首次调用传 NULL
|
|
LinkedList result); // 存储结果, 传 NULL 创建新列表
|
|
|
|
// 获取逻辑设备变量列表
|
|
LinkedList IedConnection_getLogicalDeviceVariables(IedConnection self,
|
|
IedClientError* error,
|
|
const char* ldName, // 逻辑设备名称
|
|
const char* continueAfter,
|
|
LinkedList result);
|
|
|
|
// 获取逻辑设备数据集列表
|
|
LinkedList IedConnection_getLogicalDeviceDataSets(IedConnection self,
|
|
IedClientError* error,
|
|
const char* ldName,
|
|
const char* continueAfter,
|
|
LinkedList result);
|
|
|
|
// 获取变量类型规格 (用于非线程模式预获取 varSpec)
|
|
MmsVariableSpecification* IedConnection_getVariableSpecification(
|
|
IedConnection self,
|
|
IedClientError* error,
|
|
const char* objectReference,
|
|
FunctionalConstraint fc);
|
|
```
|
|
|
|
### 7.2 异步函数
|
|
|
|
```c
|
|
// NameList 回调类型
|
|
typedef void (*IedConnection_GetNameListHandler)(
|
|
uint32_t invokeId, void* parameter,
|
|
IedClientError err,
|
|
LinkedList nameList, // 名称列表 (LinkedList<char*>)
|
|
bool moreFollows); // 是否有更多数据
|
|
|
|
void IedConnection_getServerDirectoryAsync(IedConnection self,
|
|
IedClientError* error,
|
|
const char* continueAfter,
|
|
LinkedList result,
|
|
IedConnection_GetNameListHandler handler, void* parameter);
|
|
|
|
void IedConnection_getLogicalDeviceVariablesAsync(IedConnection self,
|
|
IedClientError* error,
|
|
const char* ldName,
|
|
const char* continueAfter,
|
|
LinkedList result,
|
|
IedConnection_GetNameListHandler handler, void* parameter);
|
|
|
|
void IedConnection_getLogicalDeviceDataSetsAsync(IedConnection self,
|
|
IedClientError* error,
|
|
const char* ldName,
|
|
const char* continueAfter,
|
|
LinkedList result,
|
|
IedConnection_GetNameListHandler handler, void* parameter);
|
|
|
|
// 变量规格回调
|
|
typedef void (*IedConnection_GetVariableSpecificationHandler)(
|
|
uint32_t invokeId, void* parameter,
|
|
IedClientError err,
|
|
MmsVariableSpecification* spec);
|
|
|
|
void IedConnection_getVariableSpecificationAsync(IedConnection self,
|
|
IedClientError* error,
|
|
const char* objectReference,
|
|
FunctionalConstraint fc,
|
|
IedConnection_GetVariableSpecificationHandler handler, void* parameter);
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 文件服务
|
|
|
|
```c
|
|
// 获取文件目录
|
|
bool IedConnection_getFileDirectory(IedConnection self,
|
|
IedClientError* error,
|
|
const char* fileSpecification, // 文件匹配模式 (NULL=根目录)
|
|
const char* continueAfter, // 续传点 (NULL=首次)
|
|
IedConnection_FileDirectoryHandler handler, void* parameter);
|
|
|
|
// 打开文件 (返回 FRSM ID)
|
|
int32_t IedConnection_fileOpen(IedConnection self,
|
|
IedClientError* error,
|
|
const char* filename,
|
|
uint32_t initialPosition, // 初始位置
|
|
uint32_t* fileSize, // 输出: 文件大小
|
|
uint64_t* lastModified); // 输出: 最后修改时间
|
|
|
|
// 读取文件数据块
|
|
bool IedConnection_fileRead(IedConnection self,
|
|
IedClientError* error,
|
|
int32_t frsmId, // FRSM ID
|
|
IedConnection_FileReadHandler handler, void* parameter);
|
|
// 返回: true=还有更多数据, false=已读完
|
|
|
|
// 关闭文件
|
|
void IedConnection_fileClose(IedConnection self,
|
|
IedClientError* error, int32_t frsmId);
|
|
|
|
// 删除文件
|
|
void IedConnection_fileDelete(IedConnection self,
|
|
IedClientError* error, const char* filename);
|
|
|
|
// 重命名文件
|
|
void IedConnection_fileRename(IedConnection self,
|
|
IedClientError* error,
|
|
const char* currentFileName, const char* newFileName);
|
|
|
|
// 下载文件 (ObtainFile)
|
|
void IedConnection_obtainFile(IedConnection self,
|
|
IedClientError* error,
|
|
const char* sourceFile, // 客户端源文件
|
|
const char* destinationFile); // 服务器目标文件
|
|
|
|
// 设置文件服务本地存储路径
|
|
void IedConnection_setFilestoreBasepath(IedConnection self, const char* basepath);
|
|
```
|
|
|
|
---
|
|
|
|
## 9. 日志服务 (Journal)
|
|
|
|
```c
|
|
// 按时间范围读取日志
|
|
LinkedList IedConnection_readJournalTimeRange(IedConnection self,
|
|
IedClientError* error,
|
|
const char* ldName, // 逻辑设备名 (domainId)
|
|
const char* journalRef, // 日志引用
|
|
MmsValue* startTime, // 开始时间 (MmsValue of type BINARY_TIME)
|
|
MmsValue* endTime, // 结束时间
|
|
bool* moreFollows); // 输出: 是否还有更多
|
|
|
|
// 按条目读取日志
|
|
LinkedList IedConnection_readJournalStartAfter(IedConnection self,
|
|
IedClientError* error,
|
|
const char* ldName,
|
|
const char* journalRef,
|
|
MmsValue* timeSpecification, // 时间起点
|
|
MmsValue* entrySpecification, // 条目起点
|
|
bool* moreFollows);
|
|
|
|
// 日志条目访问:
|
|
uint64_t IedConnection_JournalEntry_getEntryID(JournalEntry self);
|
|
uint64_t IedConnection_JournalEntry_getTimestamp(JournalEntry self);
|
|
LinkedList IedConnection_JournalEntry_getVariables(JournalEntry self);
|
|
```
|
|
|
|
---
|
|
|
|
## 10. GOOSE 订阅
|
|
|
|
### 10.1 GOOSE 订阅者 API
|
|
|
|
```c
|
|
#include "goose_receiver.h"
|
|
#include "goose_subscriber.h"
|
|
|
|
// 创建 GOOSE 接收器
|
|
GooseReceiver GooseReceiver_create(void);
|
|
|
|
// 设置网络接口
|
|
void GooseReceiver_setInterfaceId(GooseReceiver self, const char* interfaceId);
|
|
|
|
// 创建 GOOSE 订阅者
|
|
GooseSubscriber GooseSubscriber_create(
|
|
char* goCbRef, // GoCB 引用, 如 "simpleIOGenericIO/LLN0$GO$gcbAnalogValues"
|
|
MmsValue* dataSetValues); // 数据集值容器或 NULL
|
|
// 若为 NULL, 收到第一个匹配消息后自动创建
|
|
|
|
// 设置订阅者过滤器
|
|
void GooseSubscriber_setDstMac(GooseSubscriber self, uint8_t dstMac[6]);
|
|
// 设置后只接收目标MAC匹配的消息
|
|
|
|
void GooseSubscriber_setAppId(GooseSubscriber self, uint16_t appId);
|
|
// 设置后只接收 APPID 匹配的消息
|
|
|
|
// 设置为观察者模式 (接收所有GOOSE消息)
|
|
void GooseSubscriber_setObserver(GooseSubscriber self);
|
|
|
|
// 设置监听回调
|
|
typedef void (*GooseListener)(GooseSubscriber subscriber, void* parameter);
|
|
|
|
void GooseSubscriber_setListener(GooseSubscriber self,
|
|
GooseListener listener, void* parameter);
|
|
|
|
// 添加订阅者到接收器
|
|
void GooseReceiver_addSubscriber(GooseReceiver self, GooseSubscriber subscriber);
|
|
|
|
// 启动接收 (创建后台线程)
|
|
void GooseReceiver_start(GooseReceiver self);
|
|
|
|
// 检查运行状态
|
|
bool GooseReceiver_isRunning(GooseReceiver self);
|
|
|
|
// 停止接收
|
|
void GooseReceiver_stop(GooseReceiver self);
|
|
|
|
// 销毁接收器 (同时销毁所有订阅者)
|
|
void GooseReceiver_destroy(GooseReceiver self);
|
|
```
|
|
|
|
### 10.2 GooseSubscriber 信息获取
|
|
|
|
```c
|
|
// 消息有效性
|
|
bool GooseSubscriber_isValid(GooseSubscriber self);
|
|
GooseParseError GooseSubscriber_getParseError(GooseSubscriber self);
|
|
|
|
// 消息元数据
|
|
char* GooseSubscriber_getGoId(GooseSubscriber self);
|
|
char* GooseSubscriber_getGoCbRef(GooseSubscriber self);
|
|
char* GooseSubscriber_getDataSet(GooseSubscriber self);
|
|
|
|
uint32_t GooseSubscriber_getStNum(GooseSubscriber self);
|
|
uint32_t GooseSubscriber_getSqNum(GooseSubscriber self);
|
|
uint64_t GooseSubscriber_getTimestamp(GooseSubscriber self); // ms 时间戳
|
|
uint32_t GooseSubscriber_getTimeAllowedToLive(GooseSubscriber self);
|
|
uint32_t GooseSubscriber_getConfRev(GooseSubscriber self);
|
|
|
|
bool GooseSubscriber_isTest(GooseSubscriber self);
|
|
bool GooseSubscriber_needsCommission(GooseSubscriber self);
|
|
|
|
// MAC 地址
|
|
void GooseSubscriber_getSrcMac(GooseSubscriber self, uint8_t* buffer);
|
|
void GooseSubscriber_getDstMac(GooseSubscriber self, uint8_t* buffer);
|
|
|
|
// VLAN
|
|
bool GooseSubscriber_isVlanSet(GooseSubscriber self);
|
|
uint16_t GooseSubscriber_getVlanId(GooseSubscriber self);
|
|
uint8_t GooseSubscriber_getVlanPrio(GooseSubscriber self);
|
|
|
|
// 数据集值
|
|
MmsValue* GooseSubscriber_getDataSetValues(GooseSubscriber self);
|
|
// 注意: 如果接收器运行在独立线程, 此 MmsValue 仅应在回调函数内使用!
|
|
|
|
// 获取 APPID
|
|
int32_t GooseSubscriber_getAppId(GooseSubscriber self);
|
|
```
|
|
|
|
### 10.3 GOOSE 回调示例
|
|
|
|
```c
|
|
static void
|
|
gooseListener(GooseSubscriber subscriber, void* parameter)
|
|
{
|
|
printf("GOOSE: stNum=%u sqNum=%u\n",
|
|
GooseSubscriber_getStNum(subscriber),
|
|
GooseSubscriber_getSqNum(subscriber));
|
|
|
|
MmsValue* values = GooseSubscriber_getDataSetValues(subscriber);
|
|
|
|
char buf[1024];
|
|
MmsValue_printToBuffer(values, buf, 1024);
|
|
printf(" allData: %s\n", buf);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 11. GOOSE 发布 (独立)
|
|
|
|
(与服务端手册第11.2节相同)
|
|
|
|
```c
|
|
#include "goose_publisher.h"
|
|
|
|
// 通信参数
|
|
typedef struct sCommParameters {
|
|
uint8_t vlanPriority;
|
|
uint16_t vlanId;
|
|
uint16_t appId;
|
|
uint8_t dstAddress[6];
|
|
} CommParameters;
|
|
|
|
// 创建
|
|
GoosePublisher GoosePublisher_create(CommParameters* params, const char* interfaceID);
|
|
GoosePublisher GoosePublisher_createEx(CommParameters* params, const char* interfaceID, bool useVlanTag);
|
|
|
|
// 配置
|
|
void GoosePublisher_setGoID(GoosePublisher self, char* goID);
|
|
void GoosePublisher_setGoCbRef(GoosePublisher self, char* goCbRef);
|
|
void GoosePublisher_setDataSetRef(GoosePublisher self, char* dataSetRef);
|
|
void GoosePublisher_setConfRev(GoosePublisher self, uint32_t confRev);
|
|
void GoosePublisher_setTimeAllowedToLive(GoosePublisher self, uint32_t ttl);
|
|
void GoosePublisher_setSimulation(GoosePublisher self, bool simulation);
|
|
void GoosePublisher_setNeedsCommission(GoosePublisher self, bool ndsCom);
|
|
|
|
// 发布
|
|
int GoosePublisher_publish(GoosePublisher self, LinkedList dataSet);
|
|
// dataSet 是 MmsValue* 链表
|
|
|
|
// 状态数管理
|
|
uint64_t GoosePublisher_increaseStNum(GoosePublisher self); // 数据变化时调用
|
|
void GoosePublisher_reset(GoosePublisher self); // 重置 stNum/sqNum
|
|
void GoosePublisher_setStNum(GoosePublisher self, uint32_t stNum); // 测试用
|
|
void GoosePublisher_setSqNum(GoosePublisher self, uint32_t sqNum); // 测试用
|
|
|
|
// 销毁
|
|
void GoosePublisher_destroy(GoosePublisher self);
|
|
```
|
|
|
|
---
|
|
|
|
## 12. Sampled Values 客户端
|
|
|
|
### 12.1 SV 发布者 (独立)
|
|
|
|
```c
|
|
#include "sv_publisher.h"
|
|
|
|
// 创建
|
|
SVPublisher SVPublisher_create(CommParameters* params, const char* interfaceId);
|
|
SVPublisher SVPublisher_createEx(CommParameters* params, const char* interfaceId, bool useVlanTag);
|
|
|
|
// 添加 ASDU
|
|
SVPublisher_ASDU SVPublisher_addASDU(SVPublisher self,
|
|
const char* svId, // SV ID 字符串
|
|
const char* datset, // 数据集引用
|
|
uint32_t confRev); // 配置版本
|
|
|
|
// 向 ASDU 添加数据点
|
|
int SVPublisher_ASDU_addFLOAT(SVPublisher_ASDU asdu);
|
|
int SVPublisher_ASDU_addINT32(SVPublisher_ASDU asdu);
|
|
int SVPublisher_ASDU_addINT64(SVPublisher_ASDU asdu);
|
|
int SVPublisher_ASDU_addTimestamp(SVPublisher_ASDU asdu);
|
|
int SVPublisher_ASDU_addQuality(SVPublisher_ASDU asdu);
|
|
|
|
// 完成配置 (锁定, 不能再添加数据点)
|
|
void SVPublisher_setupComplete(SVPublisher self);
|
|
|
|
// 设置数据点值
|
|
void SVPublisher_ASDU_setFLOAT(SVPublisher_ASDU asdu, int index, float value);
|
|
void SVPublisher_ASDU_setINT32(SVPublisher_ASDU asdu, int index, int32_t value);
|
|
void SVPublisher_ASDU_setINT64(SVPublisher_ASDU asdu, int index, int64_t value);
|
|
void SVPublisher_ASDU_setTimestamp(SVPublisher_ASDU asdu, int index, Timestamp value);
|
|
void SVPublisher_ASDU_setQuality(SVPublisher_ASDU asdu, int index, Quality value);
|
|
|
|
// 递增采样计数
|
|
void SVPublisher_ASDU_increaseSmpCnt(SVPublisher_ASDU asdu);
|
|
|
|
// 发送 SV 消息
|
|
void SVPublisher_publish(SVPublisher self);
|
|
|
|
// 销毁
|
|
void SVPublisher_destroy(SVPublisher self);
|
|
```
|
|
|
|
### 12.2 SV 订阅者
|
|
|
|
```c
|
|
#include "sv_subscriber.h"
|
|
|
|
// 创建接收器
|
|
SVReceiver SVReceiver_create(void);
|
|
void SVReceiver_setInterfaceId(SVReceiver self, const char* interfaceId);
|
|
|
|
// 创建订阅者
|
|
SVSubscriber SVSubscriber_create(const char* svId, uint16_t appId);
|
|
// svId 为 NULL 时不按 SV ID 过滤
|
|
|
|
// 设置监听回调
|
|
typedef void (*SVUpdateListener)(
|
|
SVSubscriber subscriber, void* parameter, SVSubscriber_ASDU asdu);
|
|
|
|
void SVSubscriber_setListener(SVSubscriber self,
|
|
SVUpdateListener listener, void* parameter);
|
|
|
|
// 添加订阅者到接收器
|
|
void SVReceiver_addSubscriber(SVReceiver self, SVSubscriber subscriber);
|
|
|
|
// 启动/停止
|
|
void SVReceiver_start(SVReceiver self);
|
|
bool SVReceiver_isRunning(SVReceiver self);
|
|
void SVReceiver_stop(SVReceiver self);
|
|
void SVReceiver_destroy(SVReceiver self);
|
|
|
|
// ASDU 信息获取
|
|
const char* SVSubscriber_ASDU_getSvId(SVSubscriber_ASDU asdu);
|
|
uint32_t SVSubscriber_ASDU_getSmpCnt(SVSubscriber_ASDU asdu);
|
|
uint32_t SVSubscriber_ASDU_getConfRev(SVSubscriber_ASDU asdu);
|
|
uint32_t SVSubscriber_ASDU_getDataSize(SVSubscriber_ASDU asdu);
|
|
|
|
// 获取数据 (按字节偏移量)
|
|
float SVSubscriber_ASDU_getFLOAT32(SVSubscriber_ASDU asdu, uint32_t byteOffset);
|
|
int32_t SVSubscriber_ASDU_getINT32(SVSubscriber_ASDU asdu, uint32_t byteOffset);
|
|
int64_t SVSubscriber_ASDU_getINT64(SVSubscriber_ASDU asdu, uint32_t byteOffset);
|
|
Timestamp SVSubscriber_ASDU_getTimestamp(SVSubscriber_ASDU asdu, uint32_t byteOffset);
|
|
Quality SVSubscriber_ASDU_getQuality(SVSubscriber_ASDU asdu, uint32_t byteOffset);
|
|
// 注意: 需要先验知识了解数据集结构!
|
|
```
|
|
|
|
---
|
|
|
|
## 13. SV 控制块 (SVCB)
|
|
|
|
```c
|
|
// 创建 SVCB 客户端对象
|
|
ClientSVControlBlock ClientSVControlBlock_create(
|
|
IedConnection connection, const char* reference);
|
|
|
|
void ClientSVControlBlock_destroy(ClientSVControlBlock self);
|
|
|
|
// 判断是否为组播
|
|
bool ClientSVControlBlock_isMulticast(ClientSVControlBlock self);
|
|
|
|
// 获取最后一次通讯错误
|
|
IedClientError ClientSVControlBlock_getLastComError(ClientSVControlBlock self);
|
|
|
|
// 启用/禁用 SV
|
|
bool ClientSVControlBlock_setSvEna(ClientSVControlBlock self, bool value);
|
|
bool ClientSVControlBlock_getSvEna(ClientSVControlBlock self);
|
|
|
|
// 预留
|
|
bool ClientSVControlBlock_setResv(ClientSVControlBlock self, bool value);
|
|
bool ClientSVControlBlock_getResv(ClientSVControlBlock self);
|
|
|
|
// MSV/Usv ID
|
|
char* ClientSVControlBlock_getMsvID(ClientSVControlBlock self);
|
|
```
|
|
|
|
---
|
|
|
|
## 14. MmsValue 完整操作手册
|
|
|
|
### 14.1 MmsValue 类型定义 (MmsType)
|
|
|
|
```c
|
|
typedef enum {
|
|
MMS_ARRAY = 0, MMS_STRUCTURE = 1,
|
|
MMS_BOOLEAN = 2, MMS_BIT_STRING = 3,
|
|
MMS_INTEGER = 4, MMS_UNSIGNED = 5,
|
|
MMS_FLOAT = 6, MMS_OCTET_STRING = 7,
|
|
MMS_VISIBLE_STRING = 8, MMS_GENERALIZED_TIME = 9,
|
|
MMS_BINARY_TIME = 10, MMS_BCD = 11,
|
|
MMS_BOOLEAN_ARRAY = 12, MMS_OBJ_ID = 13,
|
|
MMS_STRING = 14, MMS_UTC_TIME = 15,
|
|
MMS_DATA_ACCESS_ERROR = 16,
|
|
MMS_INTEGER_64 = 17
|
|
} MmsType;
|
|
```
|
|
|
|
### 14.2 创建 MmsValue
|
|
|
|
```c
|
|
// === 基本类型创建 ===
|
|
MmsValue* MmsValue_newBoolean(bool value);
|
|
MmsValue* MmsValue_newFloat(float value);
|
|
MmsValue* MmsValue_newDouble(double value);
|
|
MmsValue* MmsValue_newIntegerFromInt8(int8_t value);
|
|
MmsValue* MmsValue_newIntegerFromInt16(int16_t value);
|
|
MmsValue* MmsValue_newIntegerFromInt32(int32_t value);
|
|
MmsValue* MmsValue_newIntegerFromInt64(int64_t value);
|
|
MmsValue* MmsValue_newUnsignedFromUint32(uint32_t value);
|
|
|
|
// === 字符串 ===
|
|
MmsValue* MmsValue_newVisibleString(const char* string);
|
|
MmsValue* MmsValue_newVisibleStringWithSize(int size);
|
|
MmsValue* MmsValue_newString(const char* string);
|
|
MmsValue* MmsValue_newStringWithSize(int size);
|
|
|
|
// === 时间 ===
|
|
MmsValue* MmsValue_newUtcTimeByMsTime(uint64_t msTime);
|
|
MmsValue* MmsValue_newUtcTime(uint32_t timeInSecWithQuality);
|
|
MmsValue* MmsValue_newBinaryTime(bool timeOfDay);
|
|
|
|
// === 位串 ===
|
|
MmsValue* MmsValue_newBitString(int bitSize);
|
|
|
|
// === 字节串 ===
|
|
MmsValue* MmsValue_newOctetString(int size, int maxSize);
|
|
|
|
// === 数组/结构体 ===
|
|
MmsValue* MmsValue_createArray(const MmsVariableSpecification* elementType, int size);
|
|
MmsValue* MmsValue_createEmptyArray(int size);
|
|
MmsValue* MmsValue_createEmptyStructure(int size);
|
|
```
|
|
|
|
### 14.3 读取 MmsValue
|
|
|
|
```c
|
|
// === 获取类型 ===
|
|
MmsType MmsValue_getType(const MmsValue* self);
|
|
|
|
// === 类型转换读取 ===
|
|
int64_t MmsValue_toInt64(const MmsValue* self);
|
|
int32_t MmsValue_toInt32(const MmsValue* self);
|
|
uint32_t MmsValue_toUint32(const MmsValue* self);
|
|
double MmsValue_toDouble(const MmsValue* self);
|
|
float MmsValue_toFloat(const MmsValue* self);
|
|
bool MmsValue_getBoolean(const MmsValue* self);
|
|
|
|
// === 字符串 ===
|
|
const char* MmsValue_toString(MmsValue* self);
|
|
int MmsValue_getStringSize(MmsValue* self);
|
|
|
|
// === 时间 ===
|
|
uint32_t MmsValue_toUnixTimestamp(const MmsValue* self);
|
|
|
|
// === 数组/结构体 ===
|
|
uint32_t MmsValue_getArraySize(const MmsValue* self);
|
|
MmsValue* MmsValue_getElement(const MmsValue* array, int index);
|
|
|
|
// === 位串 ===
|
|
bool MmsValue_getBitStringBit(const MmsValue* self, int bitPos);
|
|
int MmsValue_getBitStringSize(const MmsValue* self);
|
|
int MmsValue_getBitStringByteSize(const MmsValue* self);
|
|
|
|
// === 数据访问错误 ===
|
|
MmsDataAccessError MmsValue_getDataAccessError(const MmsValue* self);
|
|
```
|
|
|
|
### 14.4 修改 MmsValue
|
|
|
|
```c
|
|
// === 设置值 ===
|
|
void MmsValue_setFloat(MmsValue* self, float newValue);
|
|
void MmsValue_setDouble(MmsValue* self, double newValue);
|
|
void MmsValue_setBoolean(MmsValue* self, bool value);
|
|
void MmsValue_setInt8(MmsValue* self, int8_t value);
|
|
void MmsValue_setInt16(MmsValue* self, int16_t value);
|
|
void MmsValue_setInt32(MmsValue* self, int32_t value);
|
|
void MmsValue_setInt64(MmsValue* self, int64_t value);
|
|
void MmsValue_setUint8(MmsValue* self, uint8_t value);
|
|
void MmsValue_setUint16(MmsValue* self, uint16_t value);
|
|
void MmsValue_setUint32(MmsValue* self, uint32_t value);
|
|
|
|
// === 字符串 ===
|
|
void MmsValue_setVisibleString(MmsValue* self, const char* string);
|
|
void MmsValue_setString(MmsValue* self, const char* string);
|
|
|
|
// === 时间 ===
|
|
void MmsValue_setUtcTimeMs(MmsValue* self, uint64_t msTime);
|
|
void MmsValue_setUtcTimeByBuffer(MmsValue* self, const uint8_t* buf);
|
|
void MmsValue_setBinaryTime(MmsValue* self, bool timeOfDay);
|
|
|
|
// === 位串 ===
|
|
void MmsValue_setBitStringBit(MmsValue* self, int bitPos, bool value);
|
|
void MmsValue_deleteAllBitStringBits(MmsValue* self);
|
|
void MmsValue_setBitStringFromInteger(MmsValue* self, uint32_t intValue);
|
|
|
|
// === 数组/结构体元素 ===
|
|
void MmsValue_setElement(MmsValue* complexValue, int index, MmsValue* elementValue);
|
|
// 替换现有元素，调用者负责释放被替换的值
|
|
```
|
|
|
|
### 14.5 序列化与打印
|
|
|
|
```c
|
|
// 打印到缓冲区
|
|
void MmsValue_printToBuffer(const MmsValue* self, char* buffer, int bufferSize);
|
|
|
|
// MMS 数据编解码
|
|
int MmsValue_encodeMmsData(const MmsValue* self,
|
|
uint8_t* buffer, int bufOffset, bool berEncoding);
|
|
|
|
MmsValue* MmsValue_decodeMmsData(const uint8_t* buffer, int bufOffset, int bufLength);
|
|
```
|
|
|
|
### 14.6 内存管理
|
|
|
|
```c
|
|
// 删除单个 MmsValue (只删除自身，不删除子元素)
|
|
void MmsValue_delete(MmsValue* value);
|
|
|
|
// 深度删除 MmsValue (递归删除所有子元素)
|
|
void MmsValue_deleteDeep(MmsValue* value);
|
|
```
|
|
|
|
---
|
|
|
|
## 15. MmsVariableSpecification
|
|
|
|
用于描述 MMS 变量的类型规格，在获取变量规格或创建数据集时使用。
|
|
|
|
```c
|
|
// 销毁
|
|
void MmsVariableSpecification_destroy(MmsVariableSpecification* self);
|
|
|
|
// 获取类型
|
|
MmsType MmsVariableSpecification_getType(MmsVariableSpecification* self);
|
|
|
|
// 获取名称
|
|
const char* MmsVariableSpecification_getName(MmsVariableSpecification* self);
|
|
|
|
// 获取大小 (结构体/数组的元素数, 或整数/字符串的位/字节大小)
|
|
int MmsVariableSpecification_getSize(MmsVariableSpecification* self);
|
|
|
|
// 检查值是否匹配此类型
|
|
bool MmsVariableSpecification_isValueOfType(
|
|
MmsVariableSpecification* self, const MmsValue* value);
|
|
|
|
// 获取子规格
|
|
MmsVariableSpecification* MmsVariableSpecification_getChildSpecificationByIndex(
|
|
MmsVariableSpecification* self, int index);
|
|
MmsVariableSpecification* MmsVariableSpecification_getChildSpecificationByName(
|
|
MmsVariableSpecification* self, const char* name, int* index);
|
|
MmsVariableSpecification* MmsVariableSpecification_getArrayElementSpecification(
|
|
MmsVariableSpecification* self);
|
|
|
|
// 递归查找命名变量
|
|
MmsVariableSpecification* MmsVariableSpecification_getNamedVariableRecursive(
|
|
MmsVariableSpecification* self, const char* nameId);
|
|
|
|
// 获取子值
|
|
MmsValue* MmsVariableSpecification_getChildValue(
|
|
MmsVariableSpecification* self, MmsValue* value, const char* childId);
|
|
|
|
// 获取结构体元素名列表
|
|
LinkedList MmsVariableSpecification_getStructureElements(
|
|
MmsVariableSpecification* self);
|
|
|
|
// 浮点数格式信息
|
|
int MmsVariableSpecification_getExponentWidth(MmsVariableSpecification* self);
|
|
```
|
|
|
|
### 15.1 MmsVariableAccessSpecification (数据集条目规格)
|
|
|
|
```c
|
|
// 创建简单条目
|
|
MmsVariableAccessSpecification* MmsVariableAccessSpecification_create(
|
|
char* domainId, char* itemId);
|
|
|
|
// 创建带可选访问的条目 (数组元素或数组元素组件)
|
|
MmsVariableAccessSpecification* MmsVariableAccessSpecification_createAlternateAccess(
|
|
char* domainId, char* itemId,
|
|
int32_t index, // 数组索引
|
|
char* componentName); // 组件名 (NULL 表示整个数组元素)
|
|
|
|
// 销毁
|
|
void MmsVariableAccessSpecification_destroy(MmsVariableAccessSpecification* self);
|
|
```
|
|
|
|
---
|
|
|
|
## 16. TLS 安全连接
|
|
|
|
```c
|
|
#include "tls_config.h"
|
|
|
|
// 创建 TLS 配置
|
|
TLSConfiguration tlsConfig = TLSConfiguration_create();
|
|
|
|
// 设置为客户端模式
|
|
void TLSConfiguration_setClientMode(TLSConfiguration self);
|
|
|
|
// 加载 CA 证书
|
|
bool TLSConfiguration_addCACertificateFromFile(TLSConfiguration self,
|
|
const char* certFilename);
|
|
|
|
// 加载客户端私钥
|
|
bool TLSConfiguration_setOwnKeyFromFile(TLSConfiguration self,
|
|
const char* keyFilename, const char* password);
|
|
|
|
// 加载客户端证书
|
|
bool TLSConfiguration_setOwnCertificateFromFile(TLSConfiguration self,
|
|
const char* certFilename);
|
|
|
|
// 证书链验证
|
|
void TLSConfiguration_setChainValidation(TLSConfiguration self, bool enable);
|
|
|
|
// 仅允许已知证书
|
|
void TLSConfiguration_setAllowOnlyKnownCertificates(TLSConfiguration self, bool enable);
|
|
|
|
// 安全事件处理器
|
|
void TLSConfiguration_setEventHandler(TLSConfiguration self,
|
|
TLSEventHandler handler, void* parameter);
|
|
|
|
// 创建 TLS 连接
|
|
IedConnection con = IedConnection_createWithTlsSupport(tlsConfig);
|
|
// 或 IedConnection con = IedConnection_createEx(tlsConfig, true);
|
|
|
|
// 连接后销毁配置
|
|
TLSConfiguration_destroy(tlsConfig);
|
|
```
|
|
|
|
### TLS 事件级别
|
|
|
|
```c
|
|
typedef enum {
|
|
TLS_SEC_EVT_INFO = 0, // 信息
|
|
TLS_SEC_EVT_WARNING = 1, // 警告
|
|
TLS_SEC_EVT_INCIDENT = 2 // 事件
|
|
} TLSEventLevel;
|
|
|
|
// 事件代码:
|
|
// TLS_EVENT_CODE_ALM_ALGO_NOT_SUPPORTED 1
|
|
// TLS_EVENT_CODE_ALM_UNSECURE_COMMUNICATION 2
|
|
// TLS_EVENT_CODE_ALM_CERT_UNAVAILABLE 3
|
|
```
|
|
|
|
---
|
|
|
|
## 17. 单线程模式 (非线程模式)
|
|
|
|
不使用后台线程，适合嵌入式环境。
|
|
|
|
```c
|
|
// 1. 创建非线程连接
|
|
IedConnection con = IedConnection_createEx(NULL, false);
|
|
|
|
// 2. 安装状态变化处理器 (跟踪连接状态)
|
|
IedConnection_installStateChangedHandler(con, stateChangedHandler, NULL);
|
|
|
|
// 3. 异步连接
|
|
IedConnection_connectAsync(con, &error, hostname, port);
|
|
|
|
// 4. 主循环: 调用 IedConnection_tick() 直到连接建立
|
|
while (IedConnection_getState(con) != IED_STATE_CONNECTED) {
|
|
if (IedConnection_getState(con) == IED_STATE_CLOSED) {
|
|
// 连接失败
|
|
break;
|
|
}
|
|
if (IedConnection_tick(con) == true)
|
|
Thread_sleep(10);
|
|
}
|
|
|
|
// 5. 使用所有异步API (*Async) 变体
|
|
IedConnection_readObjectAsync(con, &error, ref, fc, readHandler, param);
|
|
|
|
// 6. 周期性调用 tick 处理消息
|
|
uint64_t start = Hal_getTimeInMs();
|
|
while (Hal_getTimeInMs() < start + 1000) {
|
|
if (IedConnection_tick(con) == true)
|
|
Thread_sleep(10);
|
|
}
|
|
|
|
// 7. 异步释放
|
|
IedConnection_releaseAsync(con, &error);
|
|
while (IedConnection_getState(con) != IED_STATE_CLOSED) {
|
|
if (IedConnection_tick(con) == true)
|
|
Thread_sleep(10);
|
|
}
|
|
|
|
// 8. 销毁
|
|
IedConnection_destroy(con);
|
|
```
|
|
|
|
### 异步回调通用模式
|
|
|
|
```c
|
|
// 读取回调
|
|
static void readObjectHandler(uint32_t invokeId, void* parameter,
|
|
IedClientError err, MmsValue* value)
|
|
{
|
|
if (err == IED_ERROR_OK) {
|
|
printf("Value: %f\n", MmsValue_toFloat(value));
|
|
MmsValue_delete(value); // 用户负责释放!
|
|
}
|
|
}
|
|
|
|
// 通用服务回调
|
|
static void genericHandler(uint32_t invokeId, void* parameter,
|
|
IedClientError err)
|
|
{
|
|
printf("Operation result: %i\n", err);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 18. MmsConnection 底层接口
|
|
|
|
通过 `IedConnection_getMmsConnection()` 获取，提供 MMS 级精细控制。
|
|
|
|
### 18.1 连接管理
|
|
|
|
```c
|
|
// 创建
|
|
MmsConnection MmsConnection_create(void);
|
|
MmsConnection MmsConnection_createSecure(TLSConfiguration tlsConfig);
|
|
MmsConnection MmsConnection_createNonThreaded(TLSConfiguration tlsConfig);
|
|
|
|
// 连接
|
|
bool MmsConnection_connect(MmsConnection self, MmsError* error,
|
|
const char* serverName, int serverPort);
|
|
|
|
void MmsConnection_connectAsync(MmsConnection self, MmsError* error,
|
|
const char* serverName, int serverPort);
|
|
|
|
// 非线程模式: 周期性调用
|
|
bool MmsConnection_tick(MmsConnection self);
|
|
|
|
// 关闭/Abort/Conclude
|
|
void MmsConnection_close(MmsConnection self);
|
|
void MmsConnection_abort(MmsConnection self, MmsError* error);
|
|
void MmsConnection_abortAsync(MmsConnection self, MmsError* error);
|
|
void MmsConnection_conclude(MmsConnection self, MmsError* error);
|
|
void MmsConnection_concludeAsync(MmsConnection self, MmsError* error,
|
|
MmsConnection_ConcludeAbortHandler handler, void* parameter);
|
|
|
|
// 销毁
|
|
void MmsConnection_destroy(MmsConnection self);
|
|
```
|
|
|
|
### 18.2 配置
|
|
|
|
```c
|
|
// 设置请求超时
|
|
void MmsConnection_setRequestTimeout(MmsConnection self, uint32_t timeoutInMs);
|
|
uint32_t MmsConnection_getRequestTimeout(MmsConnection self);
|
|
|
|
// 设置连接超时
|
|
void MmsConnection_setConnectTimeout(MmsConnection self, uint32_t timeoutInMs);
|
|
|
|
// 设置 MMS PDU 最大尺寸 (localDetail)
|
|
void MmsConnection_setLocalDetail(MmsConnection self, int32_t localDetail);
|
|
int32_t MmsConnection_getLocalDetail(MmsConnection self);
|
|
|
|
// 设置文件存储路径
|
|
void MmsConnection_setFilestoreBasepath(MmsConnection self, const char* basepath);
|
|
|
|
// 获取 ISO/MMS 连接参数
|
|
IsoConnectionParameters MmsConnection_getIsoConnectionParameters(MmsConnection self);
|
|
MmsConnectionParameters MmsConnection_getMmsConnectionParameters(MmsConnection self);
|
|
void MmsConnection_setIsoConnectionParameters(MmsConnection self,
|
|
IsoConnectionParameters* params);
|
|
|
|
// 安装连接状态变化处理器
|
|
void MmsConnection_setConnectionStateChangedHandler(MmsConnection self,
|
|
MmsConnectionStateChangedHandler handler, void* parameter);
|
|
|
|
// 安装连接丢失处理器
|
|
typedef void (*MmsConnectionLostHandler)(MmsConnection connection, void* parameter);
|
|
void MmsConnection_setConnectionLostHandler(MmsConnection self,
|
|
MmsConnectionLostHandler handler, void* parameter);
|
|
|
|
// 安装 InformationReport 处理器 (接收服务器主动发送的未请求消息)
|
|
typedef void (*MmsInformationReportHandler)(void* parameter,
|
|
char* domainName, char* variableListName,
|
|
MmsValue* value, bool isVariableListName);
|
|
void MmsConnection_setInformationReportHandler(MmsConnection self,
|
|
MmsInformationReportHandler handler, void* parameter);
|
|
|
|
// 安装原始消息处理器 (调试用)
|
|
typedef void (*MmsRawMessageHandler)(void* parameter,
|
|
uint8_t* message, int messageLength, bool received);
|
|
void MmsConnection_setRawMessageHandler(MmsConnection self,
|
|
MmsRawMessageHandler handler, void* parameter);
|
|
// 需要 CONFIG_MMS_RAW_MESSAGE_LOGGING
|
|
```
|
|
|
|
### 18.3 MMS 读写操作
|
|
|
|
```c
|
|
// 读取变量
|
|
MmsValue* MmsConnection_readVariable(MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* itemId);
|
|
|
|
void MmsConnection_readVariableAsync(MmsConnection self,
|
|
uint32_t* usedInvokeId, MmsError* error,
|
|
const char* domainId, const char* itemId,
|
|
MmsConnection_ReadVariableHandler handler, void* parameter);
|
|
|
|
// 读取变量组件
|
|
MmsValue* MmsConnection_readVariableComponent(MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* itemId, const char* componentId);
|
|
|
|
// 读取数组元素
|
|
MmsValue* MmsConnection_readArrayElements(MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* itemId,
|
|
uint32_t startIndex, uint32_t numberOfElements);
|
|
|
|
// 读取单个数组元素及组件
|
|
MmsValue* MmsConnection_readSingleArrayElementWithComponent(
|
|
MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* itemId,
|
|
uint32_t index, const char* componentId);
|
|
|
|
// 读取多个变量
|
|
MmsValue* MmsConnection_readMultipleVariables(MmsConnection self, MmsError* error,
|
|
const char* domainId, LinkedList /*<char*>*/ items);
|
|
|
|
// 写入变量
|
|
MmsDataAccessError MmsConnection_writeVariable(MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* itemId, MmsValue* value);
|
|
|
|
// 写入变量组件
|
|
MmsDataAccessError MmsConnection_writeVariableComponent(MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* itemId,
|
|
const char* componentId, MmsValue* value);
|
|
|
|
// 写入数组元素
|
|
MmsDataAccessError MmsConnection_writeArrayElements(MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* itemId,
|
|
int index, int numberOfElements, MmsValue* value);
|
|
|
|
// 写入单个数组元素组件
|
|
MmsDataAccessError MmsConnection_writeSingleArrayElementWithComponent(
|
|
MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* itemId,
|
|
uint32_t arrayIndex, const char* componentId, MmsValue* value);
|
|
|
|
// 写入多个变量
|
|
void MmsConnection_writeMultipleVariables(MmsConnection self, MmsError* error,
|
|
const char* domainId,
|
|
LinkedList /*<char*>*/ items,
|
|
LinkedList /*<MmsValue*>*/ values,
|
|
LinkedList* /*<MmsValue*>*/ accessResults);
|
|
```
|
|
|
|
### 18.4 命名变量列表 (Named Variable List) 操作
|
|
|
|
```c
|
|
// 读取命名变量列表
|
|
MmsValue* MmsConnection_readNamedVariableListValues(MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* listName, bool specWithResult);
|
|
|
|
MmsValue* MmsConnection_readNamedVariableListValuesAssociationSpecific(
|
|
MmsConnection self, MmsError* error,
|
|
const char* listName, bool specWithResult);
|
|
|
|
// 写入命名变量列表
|
|
void MmsConnection_writeNamedVariableList(MmsConnection self, MmsError* error,
|
|
bool isAssociationSpecific,
|
|
const char* domainId, const char* itemId,
|
|
LinkedList /*<MmsValue*>*/ values,
|
|
LinkedList* /*<MmsValue*>*/ accessResults);
|
|
|
|
// 定义命名变量列表 (创建数据集)
|
|
void MmsConnection_defineNamedVariableList(MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* listName,
|
|
LinkedList /*<MmsVariableAccessSpecification*>*/ variableSpecs);
|
|
|
|
void MmsConnection_defineNamedVariableListAssociationSpecific(
|
|
MmsConnection self, MmsError* error,
|
|
const char* listName, LinkedList variableSpecs);
|
|
|
|
// 读取命名变量列表目录
|
|
LinkedList MmsConnection_readNamedVariableListDirectory(MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* listName, bool* deletable);
|
|
|
|
LinkedList MmsConnection_readNamedVariableListDirectoryAssociationSpecific(
|
|
MmsConnection self, MmsError* error,
|
|
const char* listName, bool* deletable);
|
|
|
|
// 删除命名变量列表
|
|
bool MmsConnection_deleteNamedVariableList(MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* listName);
|
|
|
|
bool MmsConnection_deleteAssociationSpecificNamedVariableList(
|
|
MmsConnection self, MmsError* error, const char* listName);
|
|
```
|
|
|
|
### 18.5 目录浏览
|
|
|
|
```c
|
|
// 获取 VMD 变量名列表
|
|
LinkedList MmsConnection_getVMDVariableNames(MmsConnection self, MmsError* error);
|
|
|
|
// 获取域列表
|
|
LinkedList MmsConnection_getDomainNames(MmsConnection self, MmsError* error);
|
|
|
|
// 获取域内变量名列表
|
|
LinkedList MmsConnection_getDomainVariableNames(MmsConnection self, MmsError* error,
|
|
const char* domainId);
|
|
|
|
// 获取域内数据集名列表
|
|
LinkedList MmsConnection_getDomainVariableListNames(MmsConnection self, MmsError* error,
|
|
const char* domainId);
|
|
|
|
// 获取域内日志名列表
|
|
LinkedList MmsConnection_getDomainJournals(MmsConnection self, MmsError* error,
|
|
const char* domainId);
|
|
|
|
// 获取关联特定数据集名列表
|
|
LinkedList MmsConnection_getVariableListNamesAssociationSpecific(
|
|
MmsConnection self, MmsError* error);
|
|
|
|
// 获取变量类型规格
|
|
MmsVariableSpecification* MmsConnection_getVariableAccessAttributes(
|
|
MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* itemId);
|
|
```
|
|
|
|
### 18.6 服务器状态与身份
|
|
|
|
```c
|
|
// 获取服务器身份
|
|
MmsServerIdentity* MmsConnection_identify(MmsConnection self, MmsError* error);
|
|
// MmsServerIdentity: { char* vendorName; char* modelName; char* revision; }
|
|
void MmsServerIdentity_destroy(MmsServerIdentity* self);
|
|
|
|
// 获取服务器状态
|
|
void MmsConnection_getServerStatus(MmsConnection self, MmsError* error,
|
|
int* vmdLogicalStatus, int* vmdPhysicalStatus,
|
|
bool extendedDerivation);
|
|
// vmdLogicalStatus: 0-3 (STATE_CHANGES_ALLOWED/NO_CHANGES/LIMITED/SUPPORT)
|
|
// vmdPhysicalStatus: 0-3 (OPERATIONAL/PARTIALLY/INOPERATIONAL/NEEDS_COMMISSIONING)
|
|
```
|
|
|
|
### 18.7 MMS 文件服务
|
|
|
|
```c
|
|
// 获取文件目录
|
|
bool MmsConnection_getFileDirectory(MmsConnection self, MmsError* error,
|
|
const char* fileSpecification, const char* continueAfter,
|
|
MmsFileDirectoryHandler handler, void* handlerParameter);
|
|
|
|
// 打开文件
|
|
int32_t MmsConnection_fileOpen(MmsConnection self, MmsError* error,
|
|
const char* filename, uint32_t initialPosition,
|
|
uint32_t* fileSize, uint64_t* lastModified);
|
|
|
|
// 读取文件块
|
|
bool MmsConnection_fileRead(MmsConnection self, MmsError* error,
|
|
int32_t frsmId, MmsFileReadHandler handler, void* handlerParameter);
|
|
|
|
// 关闭文件
|
|
void MmsConnection_fileClose(MmsConnection self, MmsError* error, int32_t frsmId);
|
|
|
|
// 删除文件
|
|
void MmsConnection_fileDelete(MmsConnection self, MmsError* error,
|
|
const char* fileName);
|
|
|
|
// 重命名文件
|
|
void MmsConnection_fileRename(MmsConnection self, MmsError* error,
|
|
const char* currentFileName, const char* newFileName);
|
|
|
|
// 下载文件 (ObtainFile)
|
|
void MmsConnection_obtainFile(MmsConnection self, MmsError* error,
|
|
const char* sourceFile, const char* destinationFile);
|
|
```
|
|
|
|
### 18.8 MMS 日志服务
|
|
|
|
```c
|
|
// 按时间范围读取
|
|
LinkedList MmsConnection_readJournalTimeRange(MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* itemId,
|
|
MmsValue* startTime, MmsValue* endTime, bool* moreFollows);
|
|
|
|
// 按条目读取
|
|
LinkedList MmsConnection_readJournalStartAfter(MmsConnection self, MmsError* error,
|
|
const char* domainId, const char* itemId,
|
|
MmsValue* timeSpecification, MmsValue* entrySpecification, bool* moreFollows);
|
|
|
|
// 日志条目结构
|
|
struct sMmsJournalEntry {
|
|
MmsValue* entryID; // MMS_OCTET_STRING
|
|
MmsValue* occurenceTime; // MMS_BINARY_TIME
|
|
LinkedList journalVariables;// LinkedList<MmsJournalVariable>
|
|
};
|
|
|
|
struct sMmsJournalVariable {
|
|
char* tag;
|
|
MmsValue* value;
|
|
};
|
|
|
|
// 访问日志条目
|
|
MmsValue* MmsJournalEntry_getEntryID(MmsJournalEntry self);
|
|
MmsValue* MmsJournalEntry_getOccurenceTime(MmsJournalEntry self);
|
|
LinkedList MmsJournalEntry_getJournalVariables(MmsJournalEntry self);
|
|
const char* MmsJournalVariable_getTag(MmsJournalVariable self);
|
|
MmsValue* MmsJournalVariable_getValue(MmsJournalVariable self);
|
|
void MmsJournalEntry_destroy(MmsJournalEntry self);
|
|
```
|
|
|
|
---
|
|
|
|
## 19. 完整代码示例
|
|
|
|
### 19.1 基本客户端 (同步模式)
|
|
|
|
```c
|
|
#include "iec61850_client.h"
|
|
#include "hal_thread.h"
|
|
#include <stdlib.h>
|
|
#include <stdio.h>
|
|
|
|
void reportCallback(void* parameter, ClientReport report)
|
|
{
|
|
MmsValue* values = ClientReport_getDataSetValues(report);
|
|
printf("Report received for %s\n", ClientReport_getRcbReference(report));
|
|
|
|
for (int i = 0; i < 4; i++) {
|
|
ReasonForInclusion reason = ClientReport_getReasonForInclusion(report, i);
|
|
if (reason != IEC61850_REASON_NOT_INCLUDED) {
|
|
printf(" [%i] = %i (reason=%i)\n", i,
|
|
MmsValue_getBoolean(MmsValue_getElement(values, i)), reason);
|
|
}
|
|
}
|
|
}
|
|
|
|
int main(int argc, char** argv)
|
|
{
|
|
const char* host = (argc > 1) ? argv[1] : "localhost";
|
|
int port = (argc > 2) ? atoi(argv[2]) : 102;
|
|
|
|
IedClientError error;
|
|
IedConnection con = IedConnection_create();
|
|
IedConnection_connect(con, &error, host, port);
|
|
|
|
if (error != IED_ERROR_OK) {
|
|
printf("Connect failed: %i\n", error);
|
|
IedConnection_destroy(con);
|
|
return -1;
|
|
}
|
|
|
|
// --- 读取模拟量 ---
|
|
MmsValue* val = IedConnection_readObject(con, &error,
|
|
"simpleIOGenericIO/GGIO1.AnIn1.mag.f", IEC61850_FC_MX);
|
|
|
|
if (val) {
|
|
printf("AnIn1.mag.f = %f\n", MmsValue_toFloat(val));
|
|
MmsValue_delete(val);
|
|
}
|
|
|
|
// --- 写入 ---
|
|
MmsValue* strVal = MmsValue_newVisibleString("libiec61850.com");
|
|
IedConnection_writeObject(con, &error,
|
|
"simpleIOGenericIO/GGIO1.NamPlt.vendor", IEC61850_FC_DC, strVal);
|
|
MmsValue_delete(strVal);
|
|
|
|
// --- 读取数据集 ---
|
|
ClientDataSet ds = IedConnection_readDataSetValues(con, &error,
|
|
"simpleIOGenericIO/LLN0.Events", NULL);
|
|
if (ds) {
|
|
printf("DataSet has %d entries\n", ClientDataSet_getDataSetSize(ds));
|
|
ClientDataSet_destroy(ds);
|
|
}
|
|
|
|
// --- 报告 ---
|
|
ClientReportControlBlock rcb = IedConnection_getRCBValues(con, &error,
|
|
"simpleIOGenericIO/LLN0.RP.EventsRCB01", NULL);
|
|
if (rcb) {
|
|
IedConnection_installReportHandler(con,
|
|
"simpleIOGenericIO/LLN0.RP.EventsRCB01",
|
|
ClientReportControlBlock_getRptId(rcb),
|
|
reportCallback, NULL);
|
|
|
|
ClientReportControlBlock_setTrgOps(rcb,
|
|
TRG_OPT_DATA_UPDATE | TRG_OPT_INTEGRITY | TRG_OPT_GI);
|
|
ClientReportControlBlock_setRptEna(rcb, true);
|
|
ClientReportControlBlock_setIntgPd(rcb, 5000);
|
|
IedConnection_setRCBValues(con, &error, rcb,
|
|
RCB_ELEMENT_RPT_ENA | RCB_ELEMENT_TRG_OPS | RCB_ELEMENT_INTG_PD, true);
|
|
|
|
if (error != IED_ERROR_OK)
|
|
printf("Report activation failed: %i\n", error);
|
|
|
|
Thread_sleep(1000);
|
|
|
|
// 触发 GI
|
|
ClientReportControlBlock_setGI(rcb, true);
|
|
IedConnection_setRCBValues(con, &error, rcb, RCB_ELEMENT_GI, true);
|
|
|
|
ClientReportControlBlock_destroy(rcb);
|
|
}
|
|
|
|
// --- 控制 ---
|
|
ControlObjectClient ctl = ControlObjectClient_create(
|
|
"simpleIOGenericIO/GGIO1.SPCSO1", con);
|
|
if (ctl) {
|
|
MmsValue* ctlVal = MmsValue_newBoolean(true);
|
|
ControlObjectClient_setOrigin(ctl, NULL, CONTROL_ORCAT_REMOTE_CONTROL);
|
|
|
|
if (ControlObjectClient_operate(ctl, ctlVal, 0))
|
|
printf("Control OK\n");
|
|
else
|
|
printf("Control FAILED\n");
|
|
|
|
// 读取状态确认
|
|
MmsValue* stVal = IedConnection_readObject(con, &error,
|
|
"simpleIOGenericIO/GGIO1.SPCSO1.stVal", IEC61850_FC_ST);
|
|
if (stVal) {
|
|
printf("Status = %i\n", MmsValue_getBoolean(stVal));
|
|
MmsValue_delete(stVal);
|
|
}
|
|
|
|
MmsValue_delete(ctlVal);
|
|
ControlObjectClient_destroy(ctl);
|
|
}
|
|
|
|
IedConnection_close(con);
|
|
IedConnection_destroy(con);
|
|
return 0;
|
|
}
|
|
```
|
|
|
|
### 19.2 GOOSE 订阅者完整示例
|
|
|
|
```c
|
|
#include "goose_receiver.h"
|
|
#include "goose_subscriber.h"
|
|
#include "hal_thread.h"
|
|
#include <signal.h>
|
|
#include <stdio.h>
|
|
|
|
static int running = 1;
|
|
void sigint_handler(int sig) { running = 0; }
|
|
|
|
static void gooseListener(GooseSubscriber sub, void* param)
|
|
{
|
|
printf("GOOSE: stNum=%u sqNum=%u TTL=%u %s\n",
|
|
GooseSubscriber_getStNum(sub),
|
|
GooseSubscriber_getSqNum(sub),
|
|
GooseSubscriber_getTimeAllowedToLive(sub),
|
|
GooseSubscriber_isValid(sub) ? "VALID" : "INVALID");
|
|
|
|
MmsValue* vals = GooseSubscriber_getDataSetValues(sub);
|
|
char buf[1024];
|
|
MmsValue_printToBuffer(vals, buf, 1024);
|
|
printf(" Data: %s\n", buf);
|
|
}
|
|
|
|
int main(int argc, char** argv)
|
|
{
|
|
GooseReceiver rx = GooseReceiver_create();
|
|
GooseReceiver_setInterfaceId(rx, (argc > 1) ? argv[1] : "eth0");
|
|
|
|
uint8_t dstMac[6] = {0x01, 0x0c, 0xcd, 0x01, 0x00, 0x01};
|
|
GooseSubscriber sub = GooseSubscriber_create(
|
|
"simpleIOGenericIO/LLN0$GO$gcbAnalogValues", NULL);
|
|
GooseSubscriber_setDstMac(sub, dstMac);
|
|
GooseSubscriber_setAppId(sub, 1000);
|
|
GooseSubscriber_setListener(sub, gooseListener, NULL);
|
|
|
|
GooseReceiver_addSubscriber(rx, sub);
|
|
GooseReceiver_start(rx);
|
|
|
|
if (!GooseReceiver_isRunning(rx)) {
|
|
printf("Failed to start receiver\n");
|
|
GooseReceiver_destroy(rx);
|
|
return -1;
|
|
}
|
|
|
|
signal(SIGINT, sigint_handler);
|
|
while (running) Thread_sleep(100);
|
|
|
|
GooseReceiver_stop(rx);
|
|
GooseReceiver_destroy(rx);
|
|
return 0;
|
|
}
|
|
```
|