C API
Darra Profinet Slave C SDK：读写 I / Q。符号为 PnSService* / PnSPdo*。
#include "pns.h"
周期自由配置，最低 1 ms。应用读写过程数据。
生命周期
PnSServiceConnectRealtime → PnSServiceStart → 写 I / 读 Q / PnSPdoIn* · PnSPdoOut* → PnSServiceStop → PnSServiceClose
快速开始
#include "pns.h"
#include <stdio.h>
int main(void)
{
pns_service_handle_t session = NULL;
uint8_t q[32];
uint16_t q_len;
uint8_t i_area[4] = { 0x11, 0x22, 0x33, 0x44 };
uint8_t q0 = 0;
/* 本机会话；指定本机服务见 PnSServiceConnect */
if (PnSServiceConnectRealtime(&session) != PNS_OK)
return 1;
if (PnSServiceStart(session) != PNS_OK) {
PnSServiceClose(session);
return 1;
}
q_len = (uint16_t)sizeof(q);
PnSServiceRead(session, &q_len, q); /* 读 Q */
PnSServiceWrite(session, i_area, 4); /* 写 I，允许短写 */
PnSPdoInU8(session, 0, &q0); /* PDO：读 Q[0] */
PnSPdoOutU8(session, 0, 0x11); /* PDO：写 I[0] */
PnSServiceStop(session);
PnSServiceClose(session);
return 0;
}
连接
| 类别 | 函数 | 类型 | 读写 | 说明 |
|---|---|---|---|---|
| 生命周期 | PnSServiceConnectRealtime(p_session) | pns_result_t | 写 | 本机会话 |
| 生命周期 | PnSServiceConnect(host, port, api_key, p_session) | pns_result_t | 写 | 指定本机服务。host 传 "127.0.0.1"（或 NULL 默认回环） |
| 生命周期 | PnSServiceClose(session) | pns_result_t | 写 | 释放会话。NULL 句柄安全 |
- 本机：
PnSServiceConnectRealtime。 - 指定服务：
PnSServiceConnect("127.0.0.1", 0, NULL, &session)—— 服务不可达返回PNS_ERR_NO_CONNECTION，会话不建立。
方向契约
过程映像方向固定，写 Q 必须失败。
| 区 | 方向 | 允许 | 禁止 |
|---|---|---|---|
| I | 设备 → 控制器 | PnSServiceWrite / PnSPdoOut* / Write* | — |
| Q | 控制器 → 设备 | PnSServiceRead / PnSPdoIn* / Read* | 任何 Write* / PnSPdoOut* 写 Q |
写 Q / WriteArea(OUTPUT, …) 返回 PNS_ERR_NOT_SUPPORTED。字 / 双字一律大端（PROFINET 网络序）。
启停与运行态
| 类别 | 函数 | 类型 | 读写 | 说明 |
|---|---|---|---|---|
| 生命周期 | PnSServiceStart / StartEx | pns_result_t | 写 | 启动会话。已启动则成功返回 |
| 生命周期 | PnSServiceStop / StopEx | pns_result_t | 写 | 停止本会话。主站在连时不要拆应用关系 |
| 生命周期 | PnSServiceIsStarted | bool | 只读 | 本地会话是否已启动 |
| 生命周期 | PnSServiceReset(session, mode) | pns_result_t | 写 | 复位（COMMUNICATION / FACTORY） |
| 运行态 | PnSServiceGetStatus | pns_result_t | 只读 | 出参：state / connected / error_code |
| 运行态 | PnSServiceLastRuntimeError | pns_runtime_error_code_t | 只读 | 最近一次运行错误码枚举 |
| 运行态 | PnSServiceLastRuntimeErrorRaw | int | 只读 | 最近一次错误码原值（未识别时枚举为 UNKNOWN，原值不丢） |
| 诊断 | PnSServiceLastError | const char * | 只读 | 最近一次调用错误描述 |
StartEx / StopEx 经 p_error_code 出参返回枚举（可为 NULL，与无 Ex 版本等价）。
整区 IO
用户面：整区短名。
| 类别 | 函数 | 类型 | 读写 | 说明 |
|---|---|---|---|---|
| IO | PnSServiceRead(session, p_len, p_data) | pns_result_t | 只读 | 读整区 Q。p_data 为 NULL 仅回写长度 |
| IO | PnSServiceWrite(session, p_data, length) | pns_result_t | 只写 | 写 I，从偏移 0 起，允许短写前 N 字节 |
| IO | PnSServiceReadArea(session, area, offset, length, p_len, p_data) | pns_result_t | 只读 | 按区截取。I / M = 设备→控制器；Q = 控制器→设备 |
| IO | PnSServiceWriteArea(session, area, offset, p_data, length) | pns_result_t | 只写 | 按区写入。Q 区返回 PNS_ERR_NOT_SUPPORTED |
| IO | PnSServiceGetIo(session, …) | pns_result_t | 只读 | 过程映像快照（I 区 + Q 区）。缓冲过小回写实际长度 |
PDO
叠在 Read / Write 上，不另开映射。In = Q，Out = I。
| 类别 | 函数 | 类型 | 方向 | 说明 |
|---|---|---|---|---|
| PDO | PnSPdoInU8 / InU16 / InU32 / InI16 / InI32 | pns_result_t | 只读 | 读 Q 区字节偏移。字 / 双字大端 |
| PDO | PnSPdoOutU8 / OutU16 / OutU32 / OutI16 / OutI32 | pns_result_t | 只写 | 写 I 区字节偏移。字 / 双字大端 |
| PDO | PnSPdoCopyInputsTo(session, dest, dest_len, copied) | pns_result_t | 只读 | 整区 Q → 调用方缓冲。dest 为 NULL 仅回写长度 |
| PDO | PnSPdoCopyToOutputs(session, src, src_len, written) | pns_result_t | 只写 | 短写 I，从偏移 0 起 |
| PDO | PnSPdoReadStruct(session, dest, len) | pns_result_t | 只读 | Q 前 len 字节 → 打包缓冲（网络大端） |
| PDO | PnSPdoWriteStruct(session, src, len) | pns_result_t | 只写 | 打包缓冲 → I 前 len 字节（允许短写） |
uint8_t q0 = 0;
PnSPdoInU8(session, 0, &q0); /* Q[0] */
PnSPdoOutU8(session, 0, 0x11); /* I[0] */
int16_t qw;
PnSPdoInI16(session, 0, &qw); /* Q 大端 Int16 */
PnSPdoOutI16(session, 2, -2); /* I 偏移 2 写大端 Int16 */
地址化读写
HSL 式地址，与 C# PnSAddress.Parse 对齐。字 / 双字偏移即字节偏移，不强制 2 / 4 对齐（IW3 合法）。
| 区域 | 地址 | 方向 |
|---|---|---|
| I | I0.0 / IB0 / IW2 / ID4 | 设备 → 控制器；Write* 发送，Read* 读回本地影子 |
| Q | Q0.0 / QB0 / QW2 / QD4 | 控制器 → 设备；只读。Write* 返回 PNS_ERR_NOT_SUPPORTED |
| M | M0.0 / MB0 / MW100 / MD0 | 内部存储，映射输入面 |
| DB | DB1.DBX0.0 / DB1.DBB2 / DB1.DBW0 / DB1.DBD4 | 槽位 1 数据块。编号 > 1 返回 PNS_ERR_NOT_FOUND |
| 类别 | 函数 | 类型 | 读写 | 说明 |
|---|---|---|---|---|
| 地址 | PnSServiceParseAddress(text, p_out) | pns_result_t | 只读 | 解析为 pns_service_address_t |
| IO | PnSServiceReadBool / ReadInt16 / ReadInt32 | pns_result_t | 只读 | 位 / 字 / 双字。字双字大端 |
| IO | PnSServiceWriteBool / WriteInt16 / WriteInt32 | pns_result_t | 只写 | 写 I / M / DB。写 Q 返回 PNS_ERR_NOT_SUPPORTED |
| IO | PnSServiceReadBytes / WriteBytes | pns_result_t | 只读 / 只写 | 地址化底层原语 |
报警 / 标识 / 记录
报警 / 标识 / 记录走服务接口。过程数据不必走这些接口。
| 类别 | 函数 | 类型 | 读写 | 说明 |
|---|---|---|---|---|
| 报警 | PnSServiceGetAlarms | pns_result_t | 只读 | 活动报警列表。空列表不是失败 |
| 报警 | PnSServiceAlarmAck / AlarmAckAll | pns_result_t | 写 | 确认单条 / 全部 |
| 报警 | PnSServiceSendAlarm | pns_result_t | 写 | 发送过程报警（设备 → 控制器） |
| 标识 | PnSServiceGetIm | pns_result_t | 只读 | I&M 观测（pns_service_im_info_t） |
| 记录 | PnSServiceGetRecords | pns_result_t | 只读 | 应用参数记录列表 |
常量与返回码
| 类别 | 符号 | 类型 | 读写 | 说明 |
|---|---|---|---|---|
| 设备 | PNS_SERVICE_PORT_DEFAULT | 宏 | 只读 | 本机服务默认端口 |
| 设备 | PNS_SERVICE_APIKEY_HEADER | 宏 | 只读 | X-Darra-PnSlave-Api-Key |
| 设备 | PNS_OK | pns_result_t | 只读 | 成功。其余失败码见 PnSResultText |
所有调用返回 pns_result_t（PNS_OK = 0）。状态 / 运行错误码返回枚举，不返回裸整数充当语义。
运行前提：驱动已加载（通常需管理员）。示例见 Darra_PnS_SDK/C/examples/basic_service.c。