# libiec61850-1.5.3 MMS 客户端 API 开发手册

> 本文档基于 libiec61850 v1.5.3 源码，覆盖 MMS 客户端全部公开 C API，达到开发者脱离源码即可进行项目开发的标准。

---

## 目录

1. [架构概述](#1-架构概述)
2. [核心数据类型](#2-核心数据类型)
3. [连接管理](#3-连接管理)
4. [数据读写](#4-数据读写)
5. [报告服务（Report）](#5-报告服务report)
6. [控制服务（Control）](#6-控制服务control)
7. [数据集服务（DataSet）](#7-数据集服务dataset)
8. [文件服务（File）](#8-文件服务file)
9. [日志服务（Log）](#9-日志服务log)
10. [模型发现服务](#10-模型发现服务)
11. [SV/GOOSE 控制块处理](#11-svgoose-控制块处理)
12. [MSO 传输层访问](#12-mms低层传输层访问)
13. [错误码完整参考](#13-错误码完整参考)
14. [运行模式：线程模式 vs 非线程模式](#14-运行模式线程模式-vs-非线程模式)
15. [与 RTU 项目对照](#15-与-rtu-项目对照)

---

## 1. 架构概述

libiec61850 客户端 API 提供两个抽象层级：

| 层级 | API 头文件 | 描述 |
|------|-----------|------|
| **高层 IEC 61850** | `iec61850_client.h` | 封装 IEC 61850 语义（FC, LD/LN/DO/DA），推荐使用 |
| **底层 MMS** | `mms_client_connection.h` | 直接操作 MMS 协议 domain/item，一般不需要直接使用 |

客户端核心不透明句柄为 `IedConnection`，所有操作围绕它展开。

### 协议栈层次

```
┌─────────────────────────────────────────────────────┐
│  高层 IEC 61850 API (iec61850_client.h)              │
│  IedConnection / ClientReport / ControlObjectClient │
├─────────────────────────────────────────────────────┤
│  底层 MMS API (mms_client_connection.h)              │
│  MmsConnection / MmsValue                            │
├─────────────────────────────────────────────────────┤
│  ISO 传输层 (ACSE + Presentation + Session)          │
├─────────────────────────────────────────────────────┤
│  ASN.1 BER 编解码 + TCP/IP                           │
└─────────────────────────────────────────────────────┘
```

### 两类运行模式

| 模式 | 创建方式 | 消息处理 | 适用场景 |
|------|---------|---------|---------|
| **线程模式**（默认） | `IedConnection_create()` | 库内部后台线程自动处理 | 大多数场景 |
| **非线程模式** | `IedConnection_createEx(tlsConfig, false)` | 用户周期性调用 `IedConnection_tick()` | 需要精确控制线程的嵌入式系统 |

在非线程模式下，禁止使用同步（阻塞）API，必须使用 `*Async` 异步版本。

---

## 2. 核心数据类型

### 2.1 主要不透明句柄

```c
typedef struct sIedConnection* IedConnection;            // 客户端连接
typedef struct sClientReportControlBlock* ClientReportControlBlock;  // RCB 本地对象
typedef struct sClientReport* ClientReport;              // 接收到的报告
typedef struct sClientDataSet* ClientDataSet;            // 数据集本地对象
typedef struct sControlObjectClient* ControlObjectClient; // 控制对象
typedef struct sClientSVControlBlock* ClientSVControlBlock;          // SV控制块
typedef struct sClientGooseControlBlock* ClientGooseControlBlock;    // GOOSE控制块
```

### 2.2 连接状态

```c
typedef enum {
    IED_STATE_CLOSED = 0,     // 空闲/关闭
    IED_STATE_CONNECTING = 1, // 连接中
    IED_STATE_CONNECTED = 2,  // 已连接
    IED_STATE_CLOSING = 3     // 关闭中
} IedConnectionState;
```

### 2.3 功能约束（FunctionalConstraint）

客户端读写数据时，**必须指定 FC**：

| FC 枚举 | 值 | 含义 | 典型使用 |
|---------|----|------|---------|
| `IEC61850_FC_ST` | 0 | 状态信息 | 读遥信状态 |
| `IEC61850_FC_MX` | 1 | 测量值 | 读遥测值 |
| `IEC61850_FC_SP` | 2 | 设定值 | 读设定点 |
| `IEC61850_FC_SV` | 3 | 替代值 | 读替代值 |
| `IEC61850_FC_CF` | 4 | 配置 | 读配置 |
| `IEC61850_FC_DC` | 5 | 描述 | 读描述 |
| `IEC61850_FC_SG` | 6 | 定值组 | 读定值组活跃值 |
| `IEC61850_FC_SE` | 7 | 可编辑定值组 | 读/写编辑定值组 |
| `IEC61850_FC_CO` | 12 | 控制 | 写控制命令 |
| `IEC61850_FC_RP` | 15 | 非缓存报告 | RCB 操作 |
| `IEC61850_FC_BR` | 16 | 缓存报告 | BRCB 操作 |

**引用格式**：`"LD名/LN名.DO名.DA名"`，如 `"simpleIOGenericIO/GGIO1.ST.Ind1.stVal"`。

### 2.4 控制模型

```c
typedef enum {
    CONTROL_MODEL_STATUS_ONLY = 0,    // 只读，不支持控制
    CONTROL_MODEL_DIRECT_NORMAL = 1,  // 直控-普通安全
    CONTROL_MODEL_SBO_NORMAL = 2,     // 选控-普通安全（需Select再Operate）
    CONTROL_MODEL_DIRECT_ENHANCED = 3,// 直控-增强安全（含CommandTermination）
    CONTROL_MODEL_SBO_ENHANCED = 4    // 选控-增强安全（SelectWithValue再Operate）
} ControlModel;
```

### 2.5 Quality 质量

```c
typedef uint16_t Quality;

// 有效性（低2位）
#define QUALITY_VALIDITY_GOOD          0
#define QUALITY_VALIDITY_INVALID       2
#define QUALITY_VALIDITY_QUESTIONABLE  3

// 详情标志
#define QUALITY_DETAIL_OVERFLOW      4    // 溢出
#define QUALITY_DETAIL_OUT_OF_RANGE  8    // 超量程
#define QUALITY_DETAIL_BAD_REFERENCE 16   // 坏基准值
#define QUALITY_DETAIL_OSCILLATORY   32   // 振荡
#define QUALITY_DETAIL_FAILURE       64   // 故障
#define QUALITY_DETAIL_OLD_DATA      128  // 旧数据
#define QUALITY_DETAIL_INCONSISTENT  256  // 不一致
#define QUALITY_DETAIL_INACCURATE    512  // 不精确
#define QUALITY_SOURCE_SUBSTITUTED   1024 // 替代值
#define QUALITY_TEST                 2048 // 测试
#define QUALITY_OPERATOR_BLOCKED     4096 // 操作员闭锁

// Quality 操作函数
Validity  Quality_getValidity(Quality* self);
void      Quality_setValidity(Quality* self, Validity validity);
void      Quality_setFlag(Quality* self, int flag);
void      Quality_unsetFlag(Quality* self, int flag);
bool      Quality_isFlagSet(Quality* self, int flag);
Quality   Quality_fromMmsValue(const MmsValue* mmsValue);
MmsValue* Quality_toMmsValue(Quality* self, MmsValue* mmsValue);
```

### 2.6 Timestamp

```c
typedef union {
    uint8_t val[8];
} Timestamp;

Timestamp* Timestamp_create(void);
Timestamp* Timestamp_createFromByteArray(const uint8_t* byteArray);
void       Timestamp_destroy(Timestamp* self);
void       Timestamp_clearFlags(Timestamp* self);
uint32_t   Timestamp_getTimeInSeconds(Timestamp* self);   // 秒级时间戳
uint64_t   Timestamp_getTimeInMs(Timestamp* self);         // 毫秒级时间戳
uint64_t   Timestamp_getTimeInNs(Timestamp* self);         // 纳秒级时间戳
bool       Timestamp_isLeapSecondKnown(Timestamp* self);
void       Timestamp_setLeapSecondKnown(Timestamp* self, bool value);
bool       Timestamp_hasClockFailure(Timestamp* self);
void       Timestamp_setClockFailure(Timestamp* self, bool value);
bool       Timestamp_isClockNotSynchronized(Timestamp* self);
void       Timestamp_setClockNotSynchronized(Timestamp* self, bool value);
int        Timestamp_getSubsecondPrecision(Timestamp* self);
void       Timestamp_setSubsecondPrecision(Timestamp* self, int subsecondPrecision);
void       Timestamp_setTimeInSeconds(Timestamp* self, uint32_t secondsSinceEpoch);
void       Timestamp_setTimeInMilliseconds(Timestamp* self, uint64_t msTime);
void       Timestamp_setTimeInNanoseconds(Timestamp* self, uint64_t nsTime);
void       Timestamp_setByMmsUtcTime(Timestamp* self, const MmsValue* mmsValue);
MmsValue*  Timestamp_toMmsValue(Timestamp* self, MmsValue* mmsValue);
Timestamp* Timestamp_fromMmsValue(Timestamp* self, MmsValue* mmsValue);
```

### 2.7 回调函数类型速查

```c
// 通用服务回调（写操作完成等）
typedef void (*IedConnection_GenericServiceHandler)(uint32_t invokeId, void* parameter, IedClientError err);

// 连接状态变化回调
typedef void (*IedConnection_StateChangedHandler)(void* parameter, IedConnection connection, IedConnectionState newState);

// 读对象回调
typedef void (*IedConnection_ReadObjectHandler)(uint32_t invokeId, void* parameter, IedClientError err, MmsValue* value);

// 报告接收回调
typedef void (*ReportCallbackFunction)(void* parameter, ClientReport report);

// 控制操作完成回调
typedef void (*ControlObjectClient_ControlActionHandler)(uint32_t invokeId, void* parameter, IedClientError err, ControlActionType type, bool success);

// 命令终止回调
typedef void (*CommandTerminationHandler)(void* parameter, ControlObjectClient controlClient);

// 文件下载数据回调
typedef bool (*IedClientGetFileHandler)(void* parameter, uint8_t* buffer, uint32_t bytesRead);
```

### 2.8 MmsValue 基础操作

`MmsValue` 是所有客户端数据交换的统一容器类型。每个 `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_STRING          = 9,   // MMS 字符串
    MMS_UTC_TIME        = 10,  // UTC 时间
    MMS_DATA_ACCESS_ERROR = 11,
} MmsType;
```

**构造**（仅在需要主动创建值时使用，读取操作由库自动创建）：

```c
MmsValue* MmsValue_newBoolean(bool boolean);
MmsValue* MmsValue_newFloat(float value);
MmsValue* MmsValue_newDouble(double value);
MmsValue* MmsValue_newIntegerFromInt32(int32_t integer);
MmsValue* MmsValue_newIntegerFromInt64(int64_t integer);
MmsValue* MmsValue_newUnsignedFromUint32(uint32_t integer);
MmsValue* MmsValue_newVisibleString(const char* string);
MmsValue* MmsValue_newUtcTime(uint32_t timeval);        // 秒级时间戳
MmsValue* MmsValue_newUtcTimeByMsTime(uint64_t timeval); // 毫秒级时间戳
MmsValue* MmsValue_newOctetString(int size, int maxSize);
MmsValue* MmsValue_newBitString(int bitSize);
MmsValue* MmsValue_newStructure(const MmsVariableSpecification* typeSpec);
MmsValue* MmsValue_createEmptyStructure(int size);
MmsValue* MmsValue_createEmptyArray(int size);
```

**取值**：

```c
bool      MmsValue_getBoolean(const MmsValue* value);
float     MmsValue_toFloat(const MmsValue* self);
double    MmsValue_toDouble(const MmsValue* self);
int32_t   MmsValue_toInt32(const MmsValue* value);
int64_t   MmsValue_toInt64(const MmsValue* self);
uint32_t  MmsValue_toUint32(const MmsValue* value);
uint64_t  MmsValue_getUtcTimeInMs(const MmsValue* value);
uint64_t  MmsValue_getUtcTimeInMsWithUs(const MmsValue* self, uint32_t* usec);
uint32_t  MmsValue_toUnixTimestamp(const MmsValue* self);
const char* MmsValue_toString(MmsValue* self);  // 对 VISIBLE_STRING/STRING 类型

// 数组/结构体
MmsValue* MmsValue_getElement(const MmsValue* array, int index);
uint32_t  MmsValue_getArraySize(const MmsValue* self);

// 位串
bool      MmsValue_getBitStringBit(const MmsValue* self, int bitPos);
int       MmsValue_getBitStringSize(const MmsValue* self);
uint32_t  MmsValue_getBitStringAsInteger(const MmsValue* self);
uint32_t  MmsValue_getBitStringAsIntegerBigEndian(const MmsValue* self);

// 字节串
uint16_t  MmsValue_getOctetStringSize(const MmsValue* self);
uint8_t*  MmsValue_getOctetStringBuffer(MmsValue* self);
uint8_t   MmsValue_getOctetStringOctet(MmsValue* self, int octetPos);
```

**赋值**：

```c
void MmsValue_setBoolean(MmsValue* value, bool boolValue);
void MmsValue_setFloat(MmsValue* self, float newFloatValue);
void MmsValue_setDouble(MmsValue* self, double newFloatValue);
void MmsValue_setInt32(MmsValue* self, int32_t integer);
void MmsValue_setInt64(MmsValue* value, int64_t integer);
void MmsValue_setUint32(MmsValue* value, uint32_t integer);
void MmsValue_setVisibleString(MmsValue* self, const char* string);
MmsValue* MmsValue_setUtcTime(MmsValue* self, uint32_t timeval);   // 秒
MmsValue* MmsValue_setUtcTimeMs(MmsValue* self, uint64_t timeval); // 毫秒
void MmsValue_setOctetString(MmsValue* self, const uint8_t* buf, int size);
void MmsValue_setBitStringBit(MmsValue* self, int bitPos, bool value);
void MmsValue_setElement(MmsValue* complexValue, int index, MmsValue* elementValue);
```

**生命周期**：

```c
MmsValue* MmsValue_clone(const MmsValue* self);           // 深拷贝，调用者负责释放
void      MmsValue_delete(MmsValue* self);                 // 递归删除所有子元素
bool      MmsValue_update(MmsValue* self, const MmsValue* source);
bool      MmsValue_equals(const MmsValue* self, const MmsValue* otherValue);
MmsType   MmsValue_getType(const MmsValue* self);
```

---

## 3. 连接管理

### 3.1 完整连接生命周期

```c
// 步骤1：创建连接
IedConnection conn = IedConnection_create();
// 或高级版本：IedConnection_createEx(tlsConfig, useThreads);

// 步骤2（可选）：设置参数
IedConnection_setLocalAddress(conn, "0.0.0.0", 0);   // 本地绑定地址和端口，0=自动分配
IedConnection_setConnectTimeout(conn, 5000);          // 连接超时(ms)，须在connect前调用
IedConnection_setRequestTimeout(conn, 3000);          // 请求超时(ms)，可随时调用
IedConnection_setTimeQuality(conn, true, false, false, 10);  // 时间品质

// 步骤3：连接服务器（阻塞版本）
IedClientError err;
IedConnection_connect(conn, &err, "192.168.1.100", 102);
if (err != IED_ERROR_OK) { /* 处理错误 */ }

// 步骤3'：连接服务器（异步版本）
IedConnection_connectAsync(conn, &err, "192.168.1.100", 102);
// 轮询 IedConnection_getState(conn) 或安装状态回调来等待连接完成

// 步骤4：安装连接状态回调（可选）
void stateHandler(void* param, IedConnection connection, IedConnectionState newState) {
    switch (newState) {
        case IED_STATE_CONNECTED:  /* 连接成功 */ break;
        case IED_STATE_CLOSED:     /* 连接关闭 */ break;
        // ...
    }
}
IedConnection_installStateChangedHandler(conn, stateHandler, NULL);

// 步骤5：进行业务操作...

// 步骤6：关闭连接（三选一）
IedConnection_close(conn);            // 直接关闭 TCP（最常用）
IedConnection_abort(conn, &err);      // 发送 ACSE Abort 后关闭
IedConnection_release(conn, &err);    // 发送 MMS Conclude（优雅关闭）

// 步骤7：释放资源
IedConnection_destroy(conn);
```

### 3.2 连接状态查询

```c
IedConnectionState IedConnection_getState(IedConnection self);

// 状态流转：
// CLOSED → connect() → CONNECTING → 连接成功 → CONNECTED
// CONNECTED → close()/abort() → CLOSING → TCP断开 → CLOSED
```

### 3.3 连接参数

| API | 说明 |
|-----|------|
| `IedConnection_setLocalAddress(conn, ip, port)` | 绑定本地地址（可选，不调用由OS自动分配） |
| `IedConnection_setConnectTimeout(conn, ms)` | 连接超时，须在connect前调用 |
| `IedConnection_setRequestTimeout(conn, ms)` | 请求超时，可随时调整 |
| `IedConnection_getRequestTimeout(conn)` | 获取当前请求超时值 |
| `IedConnection_setTimeQuality(conn, a,b,c,d)` | 设置本连接生成的所有时间戳的品质 |

### 3.4 获取底层连接

```c
MmsConnection IedConnection_getMmsConnection(IedConnection self);
```
返回底层 `MmsConnection` 句柄，可用于直接调用低层 MMS API。

---

## 4. 数据读写

### 4.1 通用读写（通过 FCDA 引用 + FC）

```c
// 同步读：返回 MmsValue*，失败返回 NULL
MmsValue* val = IedConnection_readObject(conn, &err, 
    "simpleIOGenericIO/GGIO1.ST.Ind1.stVal", IEC61850_FC_ST);
if (val) {
    float f = MmsValue_toFloat(val);
    // 注意：不要手动 delete val，生命周期由库管理
}

// 同步写
MmsValue* writeVal = MmsValue_newBoolean(true);
IedConnection_writeObject(conn, &err,
    "simpleIOGenericIO/GGIO1.SP.Pos1.ctlVal", IEC61850_FC_CO, writeVal);
MmsValue_delete(writeVal);

// 异步读
void readHandler(uint32_t invokeId, void* param, IedClientError err, MmsValue* value) {
    if (err == IED_ERROR_OK) { /* 使用 value */ }
}
uint32_t id = IedConnection_readObjectAsync(conn, &err, "ref", IEC61850_FC_ST,
    readHandler, myParam);

// 异步写
uint32_t id = IedConnection_writeObjectAsync(conn, &err, "ref", IEC61850_FC_CO,
    value, genericHandler, myParam);
```

### 4.2 便捷类型读写（推荐用于简单类型）

**读**：

```c
bool      v = IedConnection_readBooleanValue(conn, &err, "ref", IEC61850_FC_ST);
float     v = IedConnection_readFloatValue(conn, &err, "ref", IEC61850_FC_MX);
int32_t   v = IedConnection_readInt32Value(conn, &err, "ref", IEC61850_FC_ST);
int64_t   v = IedConnection_readInt64Value(conn, &err, "ref", IEC61850_FC_ST);
uint32_t  v = IedConnection_readUnsigned32Value(conn, &err, "ref", IEC61850_FC_ST);
char*     v = IedConnection_readStringValue(conn, &err, "ref", IEC61850_FC_CF); // 需手动 free!
Quality   v = IedConnection_readQualityValue(conn, &err, "ref", IEC61850_FC_ST);
Timestamp* v = IedConnection_readTimestampValue(conn, &err, "ref", IEC61850_FC_ST, NULL); // 需手动 free!
```

**注意**：`readStringValue` 返回的 `char*` 由库动态分配，调用者必须手动 `free()`。

`readTimestampValue` 如果传入 `NULL` 则库分配新 Timestamp 对象，调用者负责 `Timestamp_destroy()`；如果传入已有的 Timestamp 指针则复用。

**写**：

```c
IedConnection_writeBooleanValue(conn, &err, "ref", IEC61850_FC_CO, true);
IedConnection_writeFloatValue(conn, &err, "ref", IEC61850_FC_CO, 1.5f);
IedConnection_writeInt32Value(conn, &err, "ref", IEC61850_FC_CO, 42);
IedConnection_writeUnsigned32Value(conn, &err, "ref", IEC61850_FC_CO, 100);
IedConnection_writeVisibleStringValue(conn, &err, "ref", IEC61850_FC_CF, "hello");
IedConnection_writeOctetString(conn, &err, "ref", IEC61850_FC_CF, data, len);
```

---

## 5. 报告服务（Report）

报告是 IEC 61850 客户端接收服务端主动上送数据的机制。

### 5.1 RCB 类型

| 类型 | 引用名特征 | 行为 |
|------|-----------|------|
| **URCB** (Unbuffered) | 含 `RP`（如 `LLN0.RP.EventsRCB01`） | 不缓存，断连后丢失 |
| **BRCB** (Buffered) | 含 `BR`（如 `LLN0.BR.EventsBRCB01`） | 缓存报告，断连后可重传 |

### 5.2 RCB 元素掩码（setRCBValues 时指定要写入哪些字段）

```c
#define RCB_ELEMENT_RPT_ID        1        // 报告ID
#define RCB_ELEMENT_RPT_ENA       2        // 报告使能
#define RCB_ELEMENT_RESV          4        // 预留（仅URCB）
#define RCB_ELEMENT_DATSET        8        // 数据集
#define RCB_ELEMENT_CONF_REV      16       // 配置版本
#define RCB_ELEMENT_OPT_FLDS      32       // 选项字段
#define RCB_ELEMENT_BUF_TM        64       // 缓冲时间
#define RCB_ELEMENT_SQ_NUM        128      // 序列号
#define RCB_ELEMENT_TRG_OPS       256      // 触发选项
#define RCB_ELEMENT_INTG_PD       512      // 完整性周期
#define RCB_ELEMENT_GI            1024     // 总召
#define RCB_ELEMENT_PURGE_BUF     2048     // 清除缓冲区（仅BRCB）
#define RCB_ELEMENT_ENTRY_ID      4096     // 条目ID（仅BRCB）
#define RCB_ELEMENT_TIME_OF_ENTRY 8192     // 条目时间（仅BRCB）
#define RCB_ELEMENT_RESV_TMS      16384    // 预留时间（仅BRCB）
#define RCB_ELEMENT_OWNER         32768    // 所有者
```

### 5.3 触发选项（TrgOps）

```c
#define TRG_OPT_DATA_CHANGED   1    // 数据变化触发
#define TRG_OPT_QUALITY_CHANGED 2   // 品质变化触发
#define TRG_OPT_DATA_UPDATE    4    // 数据更新触发
#define TRG_OPT_INTEGRITY      8    // 周期性触发
#define TRG_OPT_GI             16   // 总召触发
#define TRG_OPT_TRANSIENT      128  // 仅上升沿触发（瞬态）
```

### 5.4 报告选项字段（OptFlds）— 决定报告包含哪些信息

```c
#define RPT_OPT_SEQ_NUM            1    // 序列号
#define RPT_OPT_TIME_STAMP         2    // 时标
#define RPT_OPT_REASON_FOR_INCLUSION 4  // 包含原因
#define RPT_OPT_DATA_SET           8    // 数据集名
#define RPT_OPT_DATA_REFERENCE     16   // 数据引用
#define RPT_OPT_BUFFER_OVERFLOW    32   // 缓冲区溢出标志
#define RPT_OPT_ENTRY_ID           64   // 条目ID
#define RPT_OPT_CONF_REV           128  // 配置版本
```

### 5.5 完整报告配置与接收流程

```c
// 步骤1：获取 RCB（读取服务端当前RCB值）
ClientReportControlBlock rcb = IedConnection_getRCBValues(conn, &err,
    "simpleIOGenericIO/LLN0.RP.EventsRCB01", NULL);
if (!rcb || err != IED_ERROR_OK) { /* 错误处理 */ }

// 或者异步获取
uint32_t id = IedConnection_getRCBValuesAsync(conn, &err, rcbRef, NULL, handler, param);

// 步骤2：配置 RCB 参数
ClientReportControlBlock_setRptEna(rcb, true);                     // 使能报告
ClientReportControlBlock_setDataSetReference(rcb, 
    "simpleIOGenericIO/LLN0$Events");                              // 设置数据集
ClientReportControlBlock_setOptFlds(rcb,
    RPT_OPT_SEQ_NUM | RPT_OPT_TIME_STAMP | 
    RPT_OPT_REASON_FOR_INCLUSION | RPT_OPT_DATA_SET |
    RPT_OPT_DATA_REFERENCE | RPT_OPT_BUF_OVERFLOW | RPT_OPT_CONF_REV);
ClientReportControlBlock_setTrgOps(rcb,
    TRG_OPT_DATA_CHANGED | TRG_OPT_INTEGRITY | TRG_OPT_GI);
ClientReportControlBlock_setBufTm(rcb, 100);                       // 缓冲时间 100ms
ClientReportControlBlock_setIntgPd(rcb, 60000);                    // 完整性周期 60s

// 步骤3：将配置写入服务端
IedConnection_setRCBValues(conn, &err, rcb,
    RCB_ELEMENT_RPT_ENA | RCB_ELEMENT_OPT_FLDS | RCB_ELEMENT_TRG_OPS |
    RCB_ELEMENT_DATSET | RCB_ELEMENT_BUF_TM | RCB_ELEMENT_INTG_PD,
    false);  // false=多变量合并单次MMS写请求（通常建议false）

// 异步版本
IedConnection_setRCBValuesAsync(conn, &err, rcb, mask, false, handler, param);

// 步骤4：安装报告回调
IedConnection_installReportHandler(conn,
    "simpleIOGenericIO/LLN0.RP.EventsRCB01",   // RCB引用
    "EventsRpt",                                // 报告标识符（RptID）
    rcbHandler,                                 // 回调函数
    myParam);                                   // 用户参数

// 步骤5：报告回调处理
void rcbHandler(void* parameter, ClientReport report) {
    // 获取数据集值（MmsValue 数组）
    MmsValue* values = ClientReport_getDataSetValues(report);
    int size = MmsValue_getArraySize(values);
    
    // 遍历数据集成员
    for (int i = 0; i < size; i++) {
        ReasonForInclusion reason = ClientReport_getReasonForInclusion(report, i);
        const char* ref = ClientReport_getDataReference(report, i);
        MmsValue* element = MmsValue_getElement(values, i);
        
        // 根据类型处理值...
    }
    
    // 报告元数据
    if (ClientReport_hasTimestamp(report))
        uint64_t ts = ClientReport_getTimestamp(report);
    if (ClientReport_hasSeqNum(report))
        uint16_t seq = ClientReport_getSeqNum(report);
    if (ClientReport_hasBufOvfl(report))
        bool ovfl = ClientReport_getBufOvfl(report);
    if (ClientReport_hasConfRev(report))
        uint32_t cr = ClientReport_getConfRev(report);
    if (ClientReport_hasSubSeqNum(report)) {      // 分段报告
        uint16_t subSeq = ClientReport_getSubSeqNum(report);
        bool more = ClientReport_getMoreSegmentsFollow(report);
    }
}

// 步骤6：触发总召（可选）
ClientReportControlBlock_setGI(rcb, true);
IedConnection_setRCBValues(conn, &err, rcb, RCB_ELEMENT_GI, false);

// 步骤7：注销报告
IedConnection_uninstallReportHandler(conn, 
    "simpleIOGenericIO/LLN0.RP.EventsRCB01");

// 步骤8：释放 RCB 对象
ClientReportControlBlock_destroy(rcb);
```

### 5.6 包含原因枚举

```c
typedef int ReasonForInclusion;
#define IEC61850_REASON_NOT_INCLUDED   0    // 未包含
#define IEC61850_REASON_DATA_CHANGE    1    // 数据变化
#define IEC61850_REASON_QUALITY_CHANGE 2    // 品质变化
#define IEC61850_REASON_DATA_UPDATE    4    // 数据更新
#define IEC61850_REASON_INTEGRITY      8    // 周期性上送
#define IEC61850_REASON_GI             16   // 总召
#define IEC61850_REASON_UNKNOWN        32   // 原因未知
```

### 5.7 ClientReport API 完整列表

```c
const char*       ClientReport_getDataSetName(ClientReport self);
MmsValue*         ClientReport_getDataSetValues(ClientReport self);     // 仅回调内有效
char*             ClientReport_getRcbReference(ClientReport self);
char*             ClientReport_getRptId(ClientReport self);
ReasonForInclusion ClientReport_getReasonForInclusion(ClientReport self, int elementIndex);
MmsValue*         ClientReport_getEntryId(ClientReport self);
bool              ClientReport_hasTimestamp(ClientReport self);
uint64_t          ClientReport_getTimestamp(ClientReport self);
bool              ClientReport_hasSeqNum(ClientReport self);
uint16_t          ClientReport_getSeqNum(ClientReport self);
bool              ClientReport_hasDataSetName(ClientReport self);
bool              ClientReport_hasReasonForInclusion(ClientReport self);
bool              ClientReport_hasConfRev(ClientReport self);
uint32_t          ClientReport_getConfRev(ClientReport self);
bool              ClientReport_hasBufOvfl(ClientReport self);
bool              ClientReport_getBufOvfl(ClientReport self);
bool              ClientReport_hasDataReference(ClientReport self);
const char*       ClientReport_getDataReference(ClientReport self, int elementIndex);
bool              ClientReport_hasSubSeqNum(ClientReport self);         // 分段报告
uint16_t          ClientReport_getSubSeqNum(ClientReport self);
bool              ClientReport_getMoreSegmentsFollow(ClientReport self);
char*             ReasonForInclusion_getValueAsString(ReasonForInclusion reasonCode);
```

### 5.8 ClientReportControlBlock API 完整列表

```c
ClientReportControlBlock ClientReportControlBlock_create(const char* rcbReference);
void     ClientReportControlBlock_destroy(ClientReportControlBlock self);
char*    ClientReportControlBlock_getObjectReference(ClientReportControlBlock self);
bool     ClientReportControlBlock_isBuffered(ClientReportControlBlock self);

// Getter/Setter
const char* ClientReportControlBlock_getRptId(ClientReportControlBlock self);
void        ClientReportControlBlock_setRptId(ClientReportControlBlock self, const char* rptId);
bool        ClientReportControlBlock_getRptEna(ClientReportControlBlock self);
void        ClientReportControlBlock_setRptEna(ClientReportControlBlock self, bool rptEna);
bool        ClientReportControlBlock_getResv(ClientReportControlBlock self);
void        ClientReportControlBlock_setResv(ClientReportControlBlock self, bool resv);
const char* ClientReportControlBlock_getDataSetReference(ClientReportControlBlock self);
void        ClientReportControlBlock_setDataSetReference(ClientReportControlBlock self, const char* dataSetReference);
uint32_t    ClientReportControlBlock_getConfRev(ClientReportControlBlock self);
int         ClientReportControlBlock_getOptFlds(ClientReportControlBlock self);
void        ClientReportControlBlock_setOptFlds(ClientReportControlBlock self, int optFlds);
uint32_t    ClientReportControlBlock_getBufTm(ClientReportControlBlock self);
void        ClientReportControlBlock_setBufTm(ClientReportControlBlock self, uint32_t bufTm);
uint16_t    ClientReportControlBlock_getSqNum(ClientReportControlBlock self);
int         ClientReportControlBlock_getTrgOps(ClientReportControlBlock self);
void        ClientReportControlBlock_setTrgOps(ClientReportControlBlock self, int trgOps);
uint32_t    ClientReportControlBlock_getIntgPd(ClientReportControlBlock self);
void        ClientReportControlBlock_setIntgPd(ClientReportControlBlock self, uint32_t intgPd);
bool        ClientReportControlBlock_getGI(ClientReportControlBlock self);
void        ClientReportControlBlock_setGI(ClientReportControlBlock self, bool gi);
bool        ClientReportControlBlock_getPurgeBuf(ClientReportControlBlock self);
void        ClientReportControlBlock_setPurgeBuf(ClientReportControlBlock self, bool purgeBuf);
bool        ClientReportControlBlock_hasResvTms(ClientReportControlBlock self);
int16_t     ClientReportControlBlock_getResvTms(ClientReportControlBlock self);
void        ClientReportControlBlock_setResvTms(ClientReportControlBlock self, int16_t resvTms);
MmsValue*   ClientReportControlBlock_getEntryId(ClientReportControlBlock self);
void        ClientReportControlBlock_setEntryId(ClientReportControlBlock self, MmsValue* entryId);
uint64_t    ClientReportControlBlock_getEntryTime(ClientReportControlBlock self);
MmsValue*   ClientReportControlBlock_getOwner(ClientReportControlBlock self);
```

---

## 6. 控制服务（Control）

客户端控制功能用于向服务端发送遥控命令。支持直控（Direct）和选控（SBO，Select Before Operate）。

### 6.1 控制对象生命周期

```c
// 创建（同步版本：会请求服务端获取 ctlModel 等信息，可能阻塞）
ControlObjectClient ctl = ControlObjectClient_create(
    "simpleIOGenericIO/GGIO1.SP.Pos1", conn);

// 创建（扩展版本：不阻塞，需要已知 ctlModel 和 controlObjectSpec）
ControlObjectClient ctl = ControlObjectClient_createEx(
    objRef, conn, CONTROL_MODEL_SBO_NORMAL, controlObjectSpec);

// 销毁
ControlObjectClient_destroy(ctl);
```

### 6.2 同步控制操作

```c
// === 直控-普通安全 (DIRECT_NORMAL) ===
// 直接发送 operate
MmsValue* ctlVal = MmsValue_newBoolean(true);
bool success = ControlObjectClient_operate(ctl, ctlVal, 0);  // operTime=0 立即执行
MmsValue_delete(ctlVal);

// === 选控-普通安全 (SBO_NORMAL) ===
// 第一步：select
bool ok = ControlObjectClient_select(ctl);
// 第二步：operate
bool ok = ControlObjectClient_operate(ctl, ctlVal, 0);

// === 选控-增强安全 (SBO_ENHANCED) ===
// 第一步：select with value
bool ok = ControlObjectClient_selectWithValue(ctl, ctlVal);
// 第二步：operate
bool ok = ControlObjectClient_operate(ctl, ctlVal, 0);

// === 取消操作 ===
bool ok = ControlObjectClient_cancel(ctl);
```

### 6.3 异步控制操作

```c
void actionHandler(uint32_t invokeId, void* param, IedClientError err, 
                   ControlActionType type, bool success) {
    switch (type) {
        case CONTROL_ACTION_TYPE_SELECT:  /* select 结果 */ break;
        case CONTROL_ACTION_TYPE_OPERATE: /* operate 结果 */ break;
        case CONTROL_ACTION_TYPE_CANCEL:  /* cancel 结果 */ break;
    }
}

uint32_t id;
id = ControlObjectClient_operateAsync(ctl, &err, ctlVal, 0, actionHandler, myParam);
id = ControlObjectClient_selectAsync(ctl, &err, actionHandler, myParam);
id = ControlObjectClient_selectWithValueAsync(ctl, &err, ctlVal, actionHandler, myParam);
id = ControlObjectClient_cancelAsync(ctl, &err, actionHandler, myParam);
```

### 6.4 命令终止回调（增强安全模式）

```c
void terminationHandler(void* parameter, ControlObjectClient controlClient) {
    LastApplError lastErr = ControlObjectClient_getLastApplError(controlClient);
    if (lastErr.error == CONTROL_ERROR_NO_ERROR) {
        // CommandTermination+ (成功)
    } else {
        // CommandTermination- (失败)
    }
}
ControlObjectClient_setCommandTerminationHandler(ctl, terminationHandler, param);
```

### 6.5 控制对象其他 API

```c
const char*  ControlObjectClient_getObjectReference(ControlObjectClient self);
ControlModel ControlObjectClient_getControlModel(ControlObjectClient self);
void         ControlObjectClient_setControlModel(ControlObjectClient self, ControlModel ctlModel);
void         ControlObjectClient_changeServerControlModel(ControlObjectClient self, ControlModel ctlModel);
MmsType      ControlObjectClient_getCtlValType(ControlObjectClient self);
IedClientError ControlObjectClient_getLastError(ControlObjectClient self);
LastApplError  ControlObjectClient_getLastApplError(ControlObjectClient self);

// 控制参数设置
void ControlObjectClient_setTestMode(ControlObjectClient self, bool value);
void ControlObjectClient_setOrigin(ControlObjectClient self, const char* orIdent, int orCat);
void ControlObjectClient_setInterlockCheck(ControlObjectClient self, bool value);
void ControlObjectClient_setSynchroCheck(ControlObjectClient self, bool value);
void ControlObjectClient_useConstantT(ControlObjectClient self, bool useConstantT);
```

**Originator 类别（orCat）**：

```c
#define CONTROL_ORCAT_NOT_SUPPORTED      0
#define CONTROL_ORCAT_BAY_CONTROL        1   // 间隔层操作员
#define CONTROL_ORCAT_STATION_CONTROL    2   // 站控层操作员
#define CONTROL_ORCAT_REMOTE_CONTROL     3   // 远方控制
#define CONTROL_ORCAT_AUTOMATIC_BAY      4   // 间隔层自动
#define CONTROL_ORCAT_AUTOMATIC_STATION  5   // 站控层自动
#define CONTROL_ORCAT_AUTOMATIC_REMOTE   6   // 远方自动
#define CONTROL_ORCAT_MAINTENANCE        7   // 维护工具
#define CONTROL_ORCAT_PROCESS            8   // 过程层
```

---

## 7. 数据集服务（DataSet）

数据集是一组 FCD/FCDA 引用的集合，用于报告、日志等。

### 7.1 读取数据集

```c
// 同步
ClientDataSet ds = IedConnection_readDataSetValues(conn, &err,
    "simpleIOGenericIO/LLN0$Events", NULL);  // NULL=创建新实例
if (ds) {
    MmsValue* values = ClientDataSet_getValues(ds);    // MMS_ARRAY
    int size = ClientDataSet_getDataSetSize(ds);
    char* ref = ClientDataSet_getReference(ds);
    ClientDataSet_destroy(ds);
}

// 异步
IedConnection_readDataSetValuesAsync(conn, &err, dsRef, NULL, handler, param);
// 回调: void handler(uint32_t invokeId, void* param, IedClientError err, ClientDataSet dataSet)
```

### 7.2 创建/删除数据集

```c
// 创建
LinkedList members = LinkedList_create();
LinkedList_add(members, strdup("simpleIOGenericIO/GGIO1.ST.Ind1.stVal[ST]"));
LinkedList_add(members, strdup("simpleIOGenericIO/GGIO1.ST.Ind2.stVal[ST]"));
IedConnection_createDataSet(conn, &err, "simpleIOGenericIO/LLN0.MyDS", members);
LinkedList_destroyDeep(members, free);

// 异步创建
IedConnection_createDataSetAsync(conn, &err, ref, members, handler, param);

// 删除
bool deleted = IedConnection_deleteDataSet(conn, &err, "simpleIOGenericIO/LLN0.MyDS");

// 异步删除
IedConnection_deleteDataSetAsync(conn, &err, ref, handler, param);
```

### 7.3 获取数据集目录

```c
// 同步：返回 LinkedList<char*> 所有成员引用
bool isDeletable;
LinkedList elements = IedConnection_getDataSetDirectory(conn, &err, ref, &isDeletable);

// 异步
IedConnection_getDataSetDirectoryAsync(conn, &err, ref, handler, param);
// 回调: void handler(uint32_t id, void* param, IedClientError err, LinkedList<char*> dir, bool isDeletable)
```

### 7.4 写入数据集

```c
LinkedList values = LinkedList_create();
LinkedList_add(values, MmsValue_newFloat(1.5f));
LinkedList_add(values, MmsValue_newBoolean(true));
LinkedList accessResults = NULL;
IedConnection_writeDataSetValues(conn, &err, ref, values, &accessResults);

// 异步
IedConnection_writeDataSetValuesAsync(conn, &err, ref, values, handler, param);
// 回调: void handler(uint32_t id, void* param, IedClientError err, LinkedList accessResults)
```

### 7.5 ClientDataSet API

```c
void      ClientDataSet_destroy(ClientDataSet self);
MmsValue* ClientDataSet_getValues(ClientDataSet self);       // MMS_ARRAY
char*     ClientDataSet_getReference(ClientDataSet self);
int       ClientDataSet_getDataSetSize(ClientDataSet self);  // 成员数
```

---

## 8. 文件服务（File）

### 8.1 获取文件目录

```c
// 获取根目录
LinkedList /*<FileDirectoryEntry>*/ dir = IedConnection_getFileDirectory(conn, &err, NULL);
if (dir) {
    // 遍历
    LinkedList element = LinkedList_getNext(dir);
    while (element) {
        FileDirectoryEntry entry = (FileDirectoryEntry) element->data;
        const char* name = FileDirectoryEntry_getFileName(entry);
        uint32_t size = FileDirectoryEntry_getFileSize(entry);
        uint64_t mtime = FileDirectoryEntry_getLastModified(entry);
        element = LinkedList_getNext(element);
    }
    LinkedList_destroyDeep(dir, (LinkedListValueDeleteFunction)FileDirectoryEntry_destroy);
}

// 扩展版本（支持分页）
bool moreFollows;
LinkedList dir = IedConnection_getFileDirectoryEx(conn, &err, NULL, NULL, &moreFollows);
// 如果 moreFollows=true，用最后一个文件名做 continueAfter 继续获取

// 异步版本
IedConnection_getFileDirectoryAsyncEx(conn, &err, dirName, continueAfter, handler, param);
```

### 8.2 下载文件（GetFile）

```c
// 同步
bool fileHandler(void* parameter, uint8_t* buffer, uint32_t bytesRead) {
    // 将 buffer 中的数据写入本地文件
    fwrite(buffer, 1, bytesRead, (FILE*)parameter);
    return true;  // 返回 true 继续下载
}
uint32_t totalBytes = IedConnection_getFile(conn, &err, "remoteFile.txt", fileHandler, fp);

// 异步
bool asyncFileHandler(uint32_t invokeId, void* parameter, IedClientError err, 
    uint32_t originalInvokeId, uint8_t* buffer, uint32_t bytesRead, bool moreFollows) {
    if (err != IED_ERROR_OK) { /* 错误处理 */ return false; }
    fwrite(buffer, 1, bytesRead, (FILE*)parameter);
    return moreFollows;  // 还有更多数据
}
uint32_t id = IedConnection_getFileAsync(conn, &err, "remoteFile.txt", asyncFileHandler, fp);
```

### 8.3 上传文件（SetFile）/ 删除文件

```c
// 上传
IedConnection_setFile(conn, &err, "localFile.txt", "remoteFile.txt");
// 异步
IedConnection_setFileAsync(conn, &err, src, dst, handler, param);

// 删除
IedConnection_deleteFile(conn, &err, "remoteFile.txt");
// 异步
IedConnection_deleteFileAsync(conn, &err, filename, handler, param);
```

---

## 9. 日志服务（Log）

```c
// 按时间范围查询日志
bool moreFollows;
LinkedList /* <MmsJournalEntry> */ entries = IedConnection_queryLogByTime(
    conn, &err, "LDName/LNName$LogName", startTime, endTime, &moreFollows);

// 按条目ID查询后续日志
LinkedList entries = IedConnection_queryLogAfter(
    conn, &err, "LDName/LNName$LogName", entryID, timeStamp, &moreFollows);

// 异步版本
IedConnection_queryLogByTimeAsync(conn, &err, ref, start, end, handler, param);
IedConnection_queryLogAfterAsync(conn, &err, ref, entryID, ts, handler, param);
```

---

## 10. 模型发现服务

用于动态发现服务器端设备模型结构。

### 10.1 获取完整设备模型

```c
IedConnection_getDeviceModelFromServer(conn, &err);
// 此调用会缓存模型，后续的查询基于缓存，不再产生网络请求
```

### 10.2 目录查询

```c
// 获取逻辑设备列表
LinkedList /* <char*> */ lds = IedConnection_getLogicalDeviceList(conn, &err);
// 或：IedConnection_getServerDirectory(conn, &err, false);

// 获取逻辑节点列表
LinkedList lns = IedConnection_getLogicalDeviceDirectory(conn, &err, "LDName");

// 获取逻辑节点目录（按ACSI类别过滤）
LinkedList items = IedConnection_getLogicalNodeDirectory(conn, &err, 
    "LDName/LLN0", ACSI_CLASS_DATA_SET);

// 获取数据对象（DO）的子元素
LinkedList das = IedConnection_getDataDirectory(conn, &err, "LDName/GGIO1.ST.Ind1");
LinkedList das = IedConnection_getDataDirectoryFC(conn, &err, "LDName/GGIO1.ST.Ind1");     // 带 FC 后缀
LinkedList das = IedConnection_getDataDirectoryByFC(conn, &err, "LDName/GGIO1.ST", IEC61850_FC_ST);

// 获取变量规格
MmsVariableSpecification* spec = IedConnection_getVariableSpecification(conn, &err, ref, fc);

// 获取逻辑设备所有MMS变量名
LinkedList vars = IedConnection_getLogicalDeviceVariables(conn, &err, "LDName");
// 获取逻辑设备所有数据集名
LinkedList dss = IedConnection_getLogicalDeviceDataSets(conn, &err, "LDName");
```

### 10.3 ACSI 类别枚举

```c
typedef enum {
    ACSI_CLASS_DATA_OBJECT,
    ACSI_CLASS_DATA_SET,
    ACSI_CLASS_BRCB,
    ACSI_CLASS_URCB,
    ACSI_CLASS_LCB,
    ACSI_CLASS_LOG,
    ACSI_CLASS_SGCB,
    ACSI_CLASS_GoCB,
    ACSI_CLASS_GsCB,
    ACSI_CLASS_MSVCB,
    ACSI_CLASS_USVCB
} ACSIClass;
```

### 10.4 异步模型发现

```c
IedConnection_getServerDirectoryAsync(conn, &err, NULL, NULL, handler, param);
IedConnection_getLogicalDeviceVariablesAsync(conn, &err, ld, NULL, NULL, handler, param);
IedConnection_getLogicalDeviceDataSetsAsync(conn, &err, ld, NULL, NULL, handler, param);
IedConnection_getVariableSpecificationAsync(conn, &err, ref, fc, handler, param);
```

---

## 11. SV/GOOSE 控制块处理

### 11.1 SV 控制块

```c
ClientSVControlBlock svcb = ClientSVControlBlock_create(conn, "ref");
bool ena = ClientSVControlBlock_getSvEna(svcb);
ClientSVControlBlock_setSvEna(svcb, true);
char* msvID = ClientSVControlBlock_getMsvID(svcb);
char* ds = ClientSVControlBlock_getDatSet(svcb);   // 需手动 free
uint32_t confRev = ClientSVControlBlock_getConfRev(svcb);
uint16_t smpRate = ClientSVControlBlock_getSmpRate(svcb);
uint8_t smpMod = ClientSVControlBlock_getSmpMod(svcb);
int noASDU = ClientSVControlBlock_getNoASDU(svcb);
PhyComAddress addr = ClientSVControlBlock_getDstAddress(svcb);
int optFlds = ClientSVControlBlock_getOptFlds(svcb);
bool mcast = ClientSVControlBlock_isMulticast(svcb);
IedClientError err = ClientSVControlBlock_getLastComError(svcb);
ClientSVControlBlock_destroy(svcb);
```

### 11.2 GOOSE 控制块

```c
ClientGooseControlBlock gcb = ClientGooseControlBlock_create("ref");

// 读取服务端GoCB
IedConnection_getGoCBValues(conn, &err, "simpleIOGenericIO/LLN0.gcbEvents", gcb);
// 或传入 NULL 创建新实例：gcb = IedConnection_getGoCBValues(conn, &err, ref, NULL);

// 读写属性
bool ena = ClientGooseControlBlock_getGoEna(gcb);
ClientGooseControlBlock_setGoEna(gcb, true);
const char* goID = ClientGooseControlBlock_getGoID(gcb);
ClientGooseControlBlock_setGoID(gcb, "newID");
const char* ds = ClientGooseControlBlock_getDatSet(gcb);
ClientGooseControlBlock_setDatSet(gcb, "LD/LLN0$ds1");
uint32_t confRev = ClientGooseControlBlock_getConfRev(gcb);
bool ndsComm = ClientGooseControlBlock_getNdsComm(gcb);
uint32_t minTime = ClientGooseControlBlock_getMinTime(gcb);
uint32_t maxTime = ClientGooseControlBlock_getMaxTime(gcb);
bool fixedOffs = ClientGooseControlBlock_getFixedOffs(gcb);
PhyComAddress addr = ClientGooseControlBlock_getDstAddress(gcb);
ClientGooseControlBlock_setDstAddress(gcb, value);

// 写入服务端
IedConnection_setGoCBValues(conn, &err, gcb, 
    GOCB_ELEMENT_GO_ENA | GOCB_ELEMENT_DATSET, false);

ClientGooseControlBlock_destroy(gcb);
```

**GoCB 元素掩码**：

```c
#define GOCB_ELEMENT_GO_ENA       1
#define GOCB_ELEMENT_GO_ID        2
#define GOCB_ELEMENT_DATSET       4
#define GOCB_ELEMENT_CONF_REV     8
#define GOCB_ELEMENT_NDS_COMM     16
#define GOCB_ELEMENT_DST_ADDRESS  32
#define GOCB_ELEMENT_MIN_TIME     64
#define GOCB_ELEMENT_MAX_TIME     128
#define GOCB_ELEMENT_FIXED_OFFS   256
#define GOCB_ELEMENT_ALL          511
```

---

## 12. MMS低层传输层访问

当高层 API 不够用时，可通过 `IedConnection_getMmsConnection()` 获取底层 `MmsConnection`，直接使用 `mms_client_connection.h` 中的低层 API：

```c
// 获取底层连接
MmsConnection mms = IedConnection_getMmsConnection(conn);

// 低层API包含：
// - 直接域名(domain)和变量名(item)的读写
// - 命名变量列表操作
// - 文件服务（底层的FileOpen/Read/Close等）
// - 日志/Journal读取
```

一般开发不需要使用低层 API，只有在高层 API 不支持的特殊场景（如非标准服务器）才需要。

---

## 13. 错误码完整参考

```c
typedef enum {
    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                        // 未知错误
} IedClientError;
```

---

## 14. 运行模式：线程模式 vs 非线程模式

### 线程模式（默认）

```c
IedConnection conn = IedConnection_create();
// 库内部创建后台线程自动处理 MMS 消息
// 可以使用所有同步/异步 API
IedConnection_connect(conn, &err, host, port);
IedConnection_destroy(conn);
```

### 非线程模式

```c
IedConnection conn = IedConnection_createEx(NULL, false);  // useThreads=false

// 必须使用异步 API
IedConnection_connectAsync(conn, &err, host, port);

// 周期性轮询
while (running) {
    bool canPause = IedConnection_tick(conn);
    // canPause=true: 当前无活跃请求，调用线程可以挂起
    // canPause=false: 忙，应尽快再次调用 tick
    
    if (canPause) {
        usleep(10000);  // 10ms
    }
}

// 警告：不要使用同步 API！它会永远阻塞（因为没有后台线程驱动）
```

---

## 15. 与 RTU 项目对照

RTU 项目中，`src/protocol/libmms_m/` 封装了客户端 API，核心数据结构为 `stru_mms_m_obj`：

| RTU 封装层 | libiec61850 API |
|-----------|----------------|
| `stru_mms_m_obj.run.con` | `IedConnection` |
| `stru_mms_m_obj.run.con_state` | `IedConnection_getState()` |
| `stru_ln_rpt.rcb` | `ClientReportControlBlock` |
| `stru_ld_dataset.ln_datasets[]` | `IedConnection_readDataSetValues()` |
| `stru_mms_m_obj.run.out_status_cb` | `IedConnection_installStateChangedHandler()` |
| `mms_m_sg.cpp` (定值组读写) | `IedConnection_readObject`/`writeObject` with FC=SG/SE |
| `mms_m_file.cpp` (文件传输) | `IedConnection_getFile`/`setFile` |

**线程模型**：RTU 客户端使用独立线程（`pthread_task`），通过 `sem` 信号量进行同步。运行间隔为 `MMS_M_THREAD_RUN_TM = 300ms`。

**关键使用模式**（参考 RTU 代码）：

```cpp
// RTU 中的典型初始化流程
stru_mms_m_obj* obj = new stru_mms_m_obj;
obj->run.con = IedConnection_create();
IedConnection_setConnectTimeout(obj->run.con, obj->connectionTimeout);

// 连接
IedClientError err;
IedConnection_connect(obj->run.con, &err, obj->run.ip.c_str(), obj->run.port);
obj->run.con_state = IedConnection_getState(obj->run.con);

// 安装报告回调
IedConnection_installReportHandler(obj->run.con,
    rcbRef.c_str(), rptId.c_str(), reportCallback, obj);
```

---

> 本文档基于 `libiec61850-1.5.3/src/iec61850/inc/iec61850_client.h` (3091行) 和 `src/mms/inc/mms_value.h` (1062行) 完整归纳，覆盖所有公开 C API。