C++ API
Darra PnSlave C++ SDK：header-only pnet.hpp，命名空间 darra::pnet。产品入口是 PnetService。
#include "pnet.hpp"
using namespace darra::pnet;
实时主路径映射 \Device\DarraRT_Pnet_GlobalIO，不打开 \\.\DarraRT_Pnet，不加载 darra_pnet.dll。用户面无周期 / Tick：只要读、写。失败抛 PnetException。
生命周期
Connect() → Start → Write / Read / PDO().In · PDO().Out → Stop（卸映射）→ Close
快速开始
#include "pnet.hpp"
#include <cstdio>
using namespace darra::pnet;
int main()
{
PnetService service;
try {
service.Connect(); // 无 host = 实时
service.Start(); // 映射 GlobalIO
auto q = service.Read(); // Q：控制器 → 设备
service.Write({0x01, 0x02, 0x03, 0x04}); // I：设备 → 控制器
printf("PDO In[0]=0x%02X\n",
(unsigned)service.PDO().In[0].Content());
service.PDO().Out[0].Content(0x11);
service.Stop(); // 卸映射；在连不撕 AR
service.Close();
} catch (const PnetException& e) {
printf("错误: %s\n", e.what());
return 1;
}
return 0;
}
连接
| 类别 | 成员 | 类型 | 读写 | 说明 |
|---|---|---|---|---|
| 生命周期 | Connect() | void | 写 | 实时主路径。无 host，不探测 HTTP。Start 时映射 GlobalIO |
| 生命周期 | Connect("127.0.0.1") | void | 写 | HTTP 备用。探测 GET /api/info。仅本地回环可达；端口默认 kDefaultPort（18840） |
| 生命周期 | Connect(host, port, api_key) | void | 写 | 备用完整签名。服务端配置密钥后必传 api_key |
| 生命周期 | Close() | void | 写 | 释放会话。不向服务端发 stop。析构自动调用 |
| 设备 | kDefaultPort | uint16_t | 只读 | HTTP 备用端口 18840（编译期常量，不可配置） |
| 设备 | IsConnected() | bool | 只读 | 会话是否已连接 |
| 设备 | Host() / Port() | string / uint16_t | 只读 | 备用路径主机 / 端口 |
- 实时：
service.Connect();—— 空 host。 - 备用：
service.Connect("127.0.0.1");—— 服务不可达 / 非 Darra 服务抛PnetException。
方向契约
过程映像方向固定，写 Q 必须失败。
| 区 | 方向 | 允许 | 禁止 |
|---|---|---|---|
| I | 设备 → 控制器（OutputArea + OutputDirty） | Write / PDO().Out / Write* | — |
| Q | 控制器 → 设备（InputArea） | Read / PDO().In / Read* | 任何写 Q |
WriteArea(PnetServiceArea::Output, …) / WriteBool("Q0.0", …) 抛 PnetException（文案：Q 区 (输出面, 控制器 -> 设备) 只读）。字 / 双字一律大端。
启停与运行态
| 类别 | 成员 | 类型 | 读写 | 说明 |
|---|---|---|---|---|
| 生命周期 | Start() | void | 写 | 映射 GlobalIO。已映射不 POST /api/start。Section 打不开才走 HTTP 备用 |
| 生命周期 | Stop() | void | 写 | 卸映射。仅空闲才备用 POST /api/stop；主站在连不撕 AR |
| 生命周期 | IsStarted() | bool | 只读 | 本地会话是否已启动 |
| 生命周期 | ResetDevice(mode) | void | 写 | 复位。mode = "communication" / "factory" |
| 运行态 | State() / Status() | PnetState | 只读 | 运行态枚举。SHM 已映射时只信共享内存头 |
| 运行态 | StatusEx() | PnetServiceStatus | 只读 | state / connected / error_code 一次取回 |
| 运行态 | ErrorCode() | PnetRuntimeErrorCode | 只读 | 运行错误码枚举。未识别 = Unknown |
| 运行态 | ErrorMessage() | string | 只读 | 错误码中文消息 |
| 诊断 | LastError() | const string& | 只读 | 最近一次调用错误（成功后清空） |
| IO | IoStatus() | PnetIoStatus | 只读 | IOPS / IOCS 快照。空快照不虚构 GOOD |
PnetServiceStatus::connected = 是否已与 IO 控制器建立周期数据交换。error_code 为原值（0 = 无错误）；未识别值仍经该字段透传。
整区 IO
| 类别 | 成员 | 类型 | 读写 | 说明 |
|---|---|---|---|---|
| IO | Read() | vector<uint8_t> | 只读 | 读整区 Q |
| IO | Write(data) | void | 只写 | 写 I，从偏移 0 起，允许短写 |
| IO | ReadArea(area, offset, length) | vector<uint8_t> | 只读 | 按区截取 |
| IO | WriteArea(area, offset, data) | void | 只写 | 按区写入。写 Q 抛异常 |
| IO | GetIo() | pair<vector<uint8_t>, vector<uint8_t>> | 只读 | 快照：first = I，second = Q |
| IO | operator[] / at(offset) | IoByte | 读写 | 绝对字节。get = Q，set = I |
std::vector<uint8_t> q = service.Read();
service.Write({0x01, 0x02, 0x03, 0x04});
PDO
对齐 PDO().In / PDO().Out。In 只读 Q，Out 可写 I。无 live 指针、无用户周期。
| 类别 | 成员 | 类型 | 方向 | 说明 |
|---|---|---|---|---|
| PDO | PDO() | Pdo | — | 取访问器 |
| PDO | PDO().In[offset] | PdoDataItem | 只读 | Q 区字节偏移 |
| PDO | PDO().Out[offset] | PdoDataItem | 只写 | I 区字节偏移 |
| PDO | Content() / Content(v) | uint8_t / void | 只读 / 只写 | 1 字节。In 只读；Out 可写 |
| PDO | AsInt16 / AsUInt16 / AsInt32 / AsUInt32 | 对应宽度 | 读写 | 大端。In 读 Q，Out 写 I |
| PDO | CopyInputsTo(dest, dest_size) | int | 只读 | 整区 Q → 缓冲。失败返 0 |
| PDO | CopyToOutputs(src, src_size) | int | 只写 | 短写 I。失败返 0 |
| PDO | InputsMapping<T>() | T | 只读 | Q 打包字节拷到平凡结构体（无 live 指针） |
uint8_t q0 = service.PDO().In[0].Content();
service.PDO().Out[0].Content(0x11);
service.PDO().Out[2].AsInt16(-2);
#pragma pack(push, 1)
struct QFrame { uint8_t b0; uint8_t b1; int16_t w; };
#pragma pack(pop)
QFrame frame = service.InputsMapping<QFrame>();
地址化读写
HSL 式地址，与 C# PnetAddress.Parse 对齐。字 / 双字偏移即字节偏移，不强制 2 / 4 对齐（IW3 合法）。
| 区域 | 地址 | 方向 |
|---|---|---|
| I | I0.0 / IB0 / IW2 / ID4 | 设备 → 控制器 |
| Q | Q0.0 / QB0 / QW2 / QD4 | 控制器 → 设备；只读 |
| M | M0.0 / MB0 / MW100 / MD0 | 内部存储，映射输入面 |
| DB | DB1.DBX0.0 / DB1.DBB2 / DB1.DBW0 / DB1.DBD4 | 槽位 1。编号 > 1 抛 PnetException |
| 类别 | 成员 | 类型 | 读写 | 说明 |
|---|---|---|---|---|
| 地址 | ParseAddress(text) | PnetServiceAddress | 只读 | 静态解析 |
| IO | ReadBool / ReadInt16 / ReadInt32 | bool / int16_t / int32_t | 只读 | 位 / 字 / 双字。字双字大端 |
| IO | WriteBool / WriteInt16 / WriteInt32 | void | 只写 | 写 I / M / DB。写 Q 抛 PnetException |
service.WriteBool("I0.0", true);
service.WriteInt16("IW2", 0x1234);
bool start = service.ReadBool("Q0.0");
int16_t cmd = service.ReadInt16("QW0");
报警 / 标识 / 记录
HTTP 备用路径。实时 IO 不必走这些接口。
| 类别 | 成员 | 类型 | 读写 | 说明 |
|---|---|---|---|---|
| 报警 | GetAlarms() | vector<PnetServiceAlarmItem> | 只读 | 活动报警。空列表不是失败 |
| 报警 | AcknowledgeAlarm(id) | void | 写 | 确认单条 |
| 报警 | AcknowledgeAllAlarms() | int | 写 | 确认全部，返回条数 |
| 报警 | SendProcessAlarm(slot, subslot, usi, data, len) | void | 写 | 发送过程报警 |
| 标识 | GetIm() | PnetServiceImInfo | 只读 | I&M 观测 |
| 记录 | GetRecords() | PnetServiceRecords | 只读 | 应用参数记录 |
异常与枚举
| 类别 | 类型 | 读写 | 说明 |
|---|---|---|---|
| 诊断 | PnetException | — | 失败抛出。code() 为错误码，what() 为消息 |
| 运行态 | PnetState | 只读 | Disconnected / Connecting / Connected / Running / Idle / ConfigError / Unknown |
| 运行态 | PnetRuntimeErrorCode | 只读 | Ok=0 / ErrInit=-1 / ErrCfg=-2 / ErrThread=-3 / ErrRunning=-4 / ErrPdi=-5 / Unknown=-10000 |
C++17，仅 Windows（WinHTTP / ntdll）。运行前提：驱动已创建 GlobalIO Section（通常需管理员）。示例见 Darra_Pnet_SDK/CPP/examples/basic_service.cpp。