C API

Darra PnSlave C SDK：映射过程映像，读写 I / Q。符号仍为 PnetService* / PnetPdo*。

#include "pnet.h"

实时主路径不经 HTTP、不打开 \\.\DarraRT_Pnet、不加载 DarraPnet.dll。用户面无周期 / Tick：只要读、写。

生命周期

PnetServiceConnectRealtime → PnetServiceStart → 写 I / 读 Q / PnetPdoIn* · PnetPdoOut* → PnetServiceStop（卸映射）→ PnetServiceClose

快速开始

#include "pnet.h"
#include <stdio.h>

int main(void)
{
    pnet_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;

    /* 无 host = 实时；HTTP 备用见 PnetServiceConnect */
    if (PnetServiceConnectRealtime(&session) != PNET_OK)
        return 1;
    if (PnetServiceStart(session) != PNET_OK) {
        PnetServiceClose(session);
        return 1;
    }

    q_len = (uint16_t)sizeof(q);
    PnetServiceRead(session, &q_len, q);          /* 读 Q */
    PnetServiceWrite(session, i_area, 4);         /* 写 I，允许短写 */

    PnetPdoInU8(session, 0, &q0);                 /* PDO：读 Q[0] */
    PnetPdoOutU8(session, 0, 0x11);               /* PDO：写 I[0] */

    PnetServiceStop(session);                     /* 卸映射；在连不撕 AR */
    PnetServiceClose(session);
    return 0;
}

连接

类别	函数	类型	读写	说明
生命周期	PnetServiceConnectRealtime(p_session)	pnet_result_t	写	实时主路径。无 host。创建会话，Start 时映射 \Device\DarraRT_Pnet_GlobalIO
生命周期	PnetServiceConnect(host, port, api_key, p_session)	pnet_result_t	写	HTTP 备用。host 传 "127.0.0.1"（或 NULL 默认回环）；端口固定 PNET_SERVICE_PORT_DEFAULT（18840）；探测 GET /api/info
生命周期	PnetServiceClose(session)	pnet_result_t	写	释放会话。不向服务端发 stop。NULL 句柄安全

• 实时：PnetServiceConnectRealtime —— 不探测 Web API。
• 备用：PnetServiceConnect("127.0.0.1", 0, NULL, &session) —— 服务不可达 / 非 Darra 服务返回 PNET_ERR_NO_CONNECTION，会话不建立。

方向契约

过程映像方向固定，写 Q 必须失败。

区	方向	允许	禁止
I	设备 → 控制器（SHM OutputArea + OutputDirty）	PnetServiceWrite / PnetPdoOut* / Write*	—
Q	控制器 → 设备（SHM InputArea）	PnetServiceRead / PnetPdoIn* / Read*	任何 Write* / PnetPdoOut* 写 Q

写 Q / WriteArea(OUTPUT, …) 返回 PNET_ERR_NOT_SUPPORTED。字 / 双字一律大端（PROFINET 网络序）。

启停与运行态

类别	函数	类型	读写	说明
生命周期	PnetServiceStart / StartEx	pnet_result_t	写	先映射 GlobalIO。已映射不 POST /api/start。Section 打不开才走 HTTP 备用
生命周期	PnetServiceStop / StopEx	pnet_result_t	写	卸映射。仅空闲（头 Connected==0 或 HTTP 侧明确空闲）才 POST /api/stop；主站在连不撕 AR
生命周期	PnetServiceIsStarted	bool	只读	本地会话是否已启动
生命周期	PnetServiceReset(session, mode)	pnet_result_t	写	复位（COMMUNICATION / FACTORY）。HTTP 备用路径
运行态	PnetServiceGetStatus	pnet_result_t	只读	出参：state / connected / error_code。SHM 已映射时只信共享内存头
运行态	PnetServiceLastRuntimeError	pnet_runtime_error_code_t	只读	最近一次运行错误码枚举
运行态	PnetServiceLastRuntimeErrorRaw	int	只读	最近一次错误码原值（未识别时枚举为 UNKNOWN，原值不丢）
诊断	PnetServiceLastError	const char *	只读	最近一次调用错误描述

StartEx / StopEx 经 p_error_code 出参返回枚举（可为 NULL，与无 Ex 版本等价）。

整区 IO

用户面主路径：整区短名。无周期、无 Tick。

类别	函数	类型	读写	说明
IO	PnetServiceRead(session, p_len, p_data)	pnet_result_t	只读	读整区 Q。p_data 为 NULL 仅回写长度
IO	PnetServiceWrite(session, p_data, length)	pnet_result_t	只写	写 I，从偏移 0 起，允许短写前 N 字节
IO	PnetServiceReadArea(session, area, offset, length, p_len, p_data)	pnet_result_t	只读	按区截取。I / M = 设备→控制器；Q = 控制器→设备
IO	PnetServiceWriteArea(session, area, offset, p_data, length)	pnet_result_t	只写	按区写入。Q 区返回 PNET_ERR_NOT_SUPPORTED
IO	PnetServiceGetIo(session, …)	pnet_result_t	只读	过程映像快照（I 区 + Q 区）。缓冲过小回写实际长度

PDO

叠在 Read / Write 上，不另开映射。In = Q，Out = I。

类别	函数	类型	方向	说明
PDO	PnetPdoInU8 / InU16 / InU32 / InI16 / InI32	pnet_result_t	只读	读 Q 区字节偏移。字 / 双字大端
PDO	PnetPdoOutU8 / OutU16 / OutU32 / OutI16 / OutI32	pnet_result_t	只写	写 I 区字节偏移。字 / 双字大端
PDO	PnetPdoCopyInputsTo(session, dest, dest_len, copied)	pnet_result_t	只读	整区 Q → 调用方缓冲。dest 为 NULL 仅回写长度
PDO	PnetPdoCopyToOutputs(session, src, src_len, written)	pnet_result_t	只写	短写 I，从偏移 0 起
PDO	PnetPdoReadStruct(session, dest, len)	pnet_result_t	只读	Q 前 len 字节 → 打包缓冲（网络大端）
PDO	PnetPdoWriteStruct(session, src, len)	pnet_result_t	只写	打包缓冲 → I 前 len 字节（允许短写）

uint8_t q0 = 0;
PnetPdoInU8(session, 0, &q0);     /* Q[0] */
PnetPdoOutU8(session, 0, 0x11);   /* I[0] */

int16_t qw;
PnetPdoInI16(session, 0, &qw);    /* Q 大端 Int16 */
PnetPdoOutI16(session, 2, -2);    /* I 偏移 2 写大端 Int16 */

地址化读写

HSL 式地址，与 C# PnetAddress.Parse 对齐。字 / 双字偏移即字节偏移，不强制 2 / 4 对齐（IW3 合法）。

区域	地址	方向
I	I0.0 / IB0 / IW2 / ID4	设备 → 控制器；Write* 发送，Read* 读回本地影子
Q	Q0.0 / QB0 / QW2 / QD4	控制器 → 设备；只读。Write* 返回 PNET_ERR_NOT_SUPPORTED
M	M0.0 / MB0 / MW100 / MD0	内部存储，映射输入面
DB	DB1.DBX0.0 / DB1.DBB2 / DB1.DBW0 / DB1.DBD4	槽位 1 数据块。编号 > 1 返回 PNET_ERR_NOT_FOUND

类别	函数	类型	读写	说明
地址	PnetServiceParseAddress(text, p_out)	pnet_result_t	只读	解析为 pnet_service_address_t
IO	PnetServiceReadBool / ReadInt16 / ReadInt32	pnet_result_t	只读	位 / 字 / 双字。字双字大端
IO	PnetServiceWriteBool / WriteInt16 / WriteInt32	pnet_result_t	只写	写 I / M / DB。写 Q 返回 PNET_ERR_NOT_SUPPORTED
IO	PnetServiceReadBytes / WriteBytes	pnet_result_t	只读 / 只写	地址化底层原语

报警 / 标识 / 记录

HTTP 备用路径（GUI / 服务控制面）。实时 IO 不必走这些接口。

类别	函数	类型	读写	说明
报警	PnetServiceGetAlarms	pnet_result_t	只读	活动报警列表。空列表不是失败
报警	PnetServiceAlarmAck / AlarmAckAll	pnet_result_t	写	确认单条 / 全部
报警	PnetServiceSendAlarm	pnet_result_t	写	发送过程报警（设备 → 控制器）
标识	PnetServiceGetIm	pnet_result_t	只读	I&M 观测（pnet_service_im_info_t）
记录	PnetServiceGetRecords	pnet_result_t	只读	应用参数记录列表

常量与返回码

类别	符号	类型	读写	说明
设备	PNET_SERVICE_PORT_DEFAULT	宏	只读	HTTP 备用端口 18840（固定，不可配置）
设备	PNET_SERVICE_APIKEY_HEADER	宏	只读	X-Darra-Pnet-Api-Key
设备	PNET_OK	pnet_result_t	只读	成功。其余失败码见 PnetResultText

所有调用返回 pnet_result_t（PNET_OK = 0）。状态 / 运行错误码返回枚举，不返回裸整数充当语义。

运行前提：驱动已加载且 GlobalIO Section 已创建（通常需管理员）。示例见 Darra_Pnet_SDK/C/examples/basic_service.c。

相关

• C++ API
• C# API（基准）
• 快速开始
• 概念说明