PNDriver用户编程接口说明之三

本文源自西门子的技术文档《IO-Base User Programming Interface for PN Driver》第4章的前半部分，描述了PN主站协议栈代码中的接口函数调用方法，将作为PNDriver用户编程接口说明的第三篇笔记。

4 函数和数据类型

在用户代码中#include<pniobase.h>后，就可以调用以下函数实现相应功能，诸如IO控制器管理、读写IO数据、读写记录数据和报警诊断等。

4.1. 控制器管理

在OFFLINE模式下的可以调用控制器管理的相关接口

4.1.1 PNIO_controller_open

描述：该函数实例化一个控制器，在初始化过程中注册一个IO控制器，控制器打开后处于OFFLINE模式下。

函数形式：

PNIO_UINT32 PNIO_CODE_ATTR PNIO_interface_open(
    PNIO_UINT32 CpIndex,         //in
    PNIO_UINT32 ExtPar,          //in
    PNIO_CBF cbf_rec_read_conf,  //in
    PNIO_CBF cbf_rec_write_conf, //in
    PNIO_CBF cbf_alarm_ind,      //in
    PNIO_UINT32 * Handle         //out
);

参数名	参数描述
CpIndex	模块索引
ExtPar	扩展参数
cbf_rec_read_conf	响应读记录数据的回调函数，不能为空
cbf_rec_write_conf	响应写记录数据的回调函数，不能为空
cbf_Alarmcbf_alarm_indInd	响应报警事件的回调函数，不能为空
Handle	打开控制器成功将返回控制器句柄，该句柄将作为后续函数的输入

返回值：

• PNIO_OK
• PNIO_ERR_CREATE_INSTANCE
• PNIO_ERR_INTERNAL
• PNIO_ERR_NO_RESOURCE
• PNIO_ERR_RPM_CALLBACK
• PNIO_ERR_PRM_CP_ID
• PNIO_ERR_PRM_HND
• PNIO_ERR_PRM_EXT_PAR

4.1.2 PNIO_register_cbf

描述：手动注册控制器相关事件及其回调函数

PNIO_UINT32 PNIO_CODE_ATTR PNIO_register_cbf(
    PNIO_UINT32  Handle //in
    PNIO_CBE_TYPE CbeType, //in
    PNIO_CBF Cbf //in
);

参数名	参数描述
Handle	控制器句柄
CbeType	事件类型
Cbf	回调函数注意：该参数不可为空

返回值：

• PNIO_OK
• PNIO_ERR_MODE_VALUE
• PNIO_ERR_ALLREADY_DONE
• PNIO_ERR_PRM_CALLBACK
• PNIO_ERR_PRM_TYPE
• PNIO_ERR_SEQUENCE
• PNIO_ERR_WRONG_HND

4.1.3 PNIO_controller_close

描述：该函数关闭控制器实例，调用该函数后就不能收到相关的事件

函数形式：

PNIO_UINT32 PNIO_CODE_ATTR PNIO_controller_close(
    PNIO_UINT32  Handle //in
);

参数名	参数描述
Handle	控制器句柄

返回值：

• PNIO_OK
• PNIO_ERR_NO_RESOURCE
• PNIO_ERR_WRONG_HND

4.1.4 PNIO_iosystem_reconfig

4.1.5 SERV_CP_init

描述：该函数初始化通信服务，需要在PN驱动前调用，将开启以下几个任务：

• 跟踪子系统
• PNIO协议栈
• 邮箱
• 线程
• 线程运行

函数形式：

PNIO_UINT32 PNIO_CODE_ATTR SERV_CP_init(
    PNIO_DEBUG_SETTINGS_PTR_TYPE DebugSetting
);

参数名	参数描述
DebugSetting	是否允许开启跟踪功能

返回值：

• PNIO_OK
• PNIO_ERR_SEQUENCE

4.1.6 SERV_CP_undo_init

4.1.7 SERV_CP_get_network_adapters

描述：该函数获取以太网接口数据结构

函数形式：

PNIO_UINT32 PNIO_CODE_ATTR SERV_CP_get_network_adapters(
    PNIO_CP_ID_PTR_TYPE CpList, // output
    PNIO_UINT8 * NumberOfCps // output
);

参数名	参数描述
CpList	以太网接口数据结构体指针
NumberOfCps	以太网接口数目

返回值：

• PNIO_OK

4.1.8 SERV_CP_startup

描述：该函数启动通信服务，将需要以下几个参数：

• PCI本地以太网接口
• 以太网接口数目
• 配置数据
• 存储卡中数据
• 产品描述数据

4.1.9 SERV_CP_shutdown

描述：该函数关闭通信服务

4.1.10 SERV_CP_set_trace_level

跟踪信息打印级别

4.1.11 SERV_CP_set_trace_buffer

跟踪信息缓冲区大小设置

4.2 运行模式相关接口函数

控制器处于运行模式下的相关接口

4.2.1 PNIO_set_mode

描述：该函数手动设置控制器运行模式：OFFLINE、CLEAR、OPERATE

函数形式：

PNIO_UINT32 PNIO_CODE_ATTR PNIO_set_mode(
    PNIO_UINT32  Handle, //in
    PNIO_MODE_TYPE Mode //in
);

参数名	参数描述
Handle	控制器句柄
Mode	运行模式

返回值：

• PNIO_OK
• PNIO_ERR_MODE_VALUE
• PNIO_ERR_NO_RESOURCE
• PNIO_ERR_SET_MODE_NOT_ALLOWED
• PNIO_ERR_WRONG_HND
• PNIO_ERR_SEQUENCE

4.2.2 41 PNIO_CBE_MODE_IND事件

描述：设置控制器运行模式后会触发运行模式修改事件

结构体：
typedef struct {
PNIO_MODE_TYPE Mode;
} ATTR_PACKED PNIO_CBE_PRM_MODE_IND;

成员变量	描述
Mode	运行模式

4.2.3 PNIO_device_activate

本文着重控制器应用程序编程，设备应用程序接口暂不做介绍，后续将陆续增加。

4.2.4 PNIO_CBE_DEV_ACT_CONF事件

本文着重控制器应用程序编程，设备数据结构暂不做介绍，后续将陆续增加。

4.3 读写IO数据接口函数

这是控制器应用程序读写过程数据的重要函数。

4.3.1 PNIO_data_read

描述：过程数据区是一片共享内存区，协议栈收到设备上送的输入数据后更新该区域，PNIO_data_read函数也从该区域读出输入数据。函数立刻返回。

4.3.2 PNIO_data_write

控制器数据发给设备

参数	read	write
函数名	PNIO_data_read	PNIO_data_write
Handle	控制器句柄
pAddr	子模块逻辑地址
BufLen	缓冲区长度
pDataLen	实际读出的数据长度	×
pBuffer	数据缓冲区地址
IOIocState	输入数据状态	输出数据状态
pIOremState	远端状态，读入数据结果	数据写出的结果

举个例子：假设有两个输入模块，一个输入模块对应%IB0-%IB1，长度2字节；另一个输入模块对应%IB2-%IB5，长度4字节，那么对应的输入数据为：

I地址	长度	数据区	返回值
2	8	4	OK
2	2	4	OK
3	2	4	OK
5	1	3	OK
5	8	1	OK
1	2	1	OK
1	1	1	OK

返回值：

• PNIO_OK
• PNIO_ERR_PRM_ADD
• PNIO_ERR_PRM_BUF
• PNIO_ERR_PRM_IO_TYPE
• PNIO_ERR_PRM_LEN
• PNIO_ERR_PRM_LOC_STATE
• PNIO_ERR_PRM_RSTATE
• PNIO_ERR_UNKNOWN_ADDR
• PNIO_ERR_VALUE_LEN
• PNIO_ERR_WRONG_HND
• PNIO_WARN_IRT_INCONSISTENT

4.4 读记录数据

4.4.1 PNIO_rec_read_req

调用PNIO_rec_read_req会让控制器发出读纪录数据请求。

PNIO_UINT32 PNIO_CODE_ATTR PNIO_rec_read_req(
    PNIO_UINT32 Handle, //in
    PNIO_ADDR * pAddr, //in
    PNIO_UINT32 RecordIndex, //in
    PNIO_REF ReqRef, //in
    PNIO_UINT32 Length //in
);

参数	说明
AppHandle	控制器句柄
pAddr	IO设备记录数据的地址
RecordIndex	记录数据索引
ReqRef
Length	记录数据长度

返回值：

• PNIO_OK
• PNIO_ERR_PRM_ADD
• PNIO_ERR_PRM_REC_INDEX
• PNIO_ERR_SEQUENCE
• PNIO_ERR_VALUE_LEN
• PNIO_ERR_WRONG_HND

4.4.2 PNIO_CBE_REC_READ_CONF

在调用PNIO_rec_read_req函数后，会触发PNIO_CBE_REC_READ_CONF事件

4.5 写记录数据

4.5.1 PNIO_rec_write_req

PNIO_UINT32 PNIO_CODE_ATTR PNIO_rec_write_req(
    PNIO_UINT32 Handle, //in
    PNIO_ADDR * pAddr, //in
    PNIO_UINT32 RecordIndex, //in
    PNIO_REF ReqRef, //in
    PNIO_UINT32 Length, //in
    PNIO_UINT8 * pBuffer // in
);

参数	说明
AppHandle	控制器句柄
pAddr	IO设备记录数据的地址
RecordIndex	记录数据索引
ReqRef
Length	记录数据长度
pBuufer	记录数据地址

返回值：

• PNIO_OK
• PNIO_ERR_PRM_ADD
• PNIO_ERR_PRM_REC_INDEX
• PNIO_ERR_SEQUENCE
• PNIO_ERR_VALUE_LEN
• PNIO_ERR_WRONG_HND

4.5.2 PNIO_CBE_REC_WRITE_CONF

在调用PNIO_rec_write_req函数后，会触发PNIO_CBE_REC_WRITE_CONF事件

4.6 报警接口

协议栈会生成报警，并向应用程序层发出PNIO_CBE_ALARM_IND事件，所支持的所有报警类型参考PNIO_ALARM_TYPE。

4.6.1 PNIO_CBE_ALARM_IND

当IO设备向IO控制器发出报警时会触发该事件

4.7 读配置

4.7.1 PNIO_ctrl_diag_req

该函数将触发一个诊断请求PNIO_CBE_CTRL_DIAG_CONF事件

PNIO_UINT32 PNIO_CODE_ATTR PNIO_ctrl_diag_req(
    PNIO_UINT32 Handle, //in
    PNIO_CTRL_DIAG * pDiagReq //in
);

参数	说明
AppHandle	控制器句柄
pDiagReq	PNIO_CTRL_DIAG结构体指针

返回：

• PNIO_OK
• PNIO_ERR_NO_RESOURCE
• PNIO_ERR_WRONG_HND
• PNIO_ERR_PRM_POINTER
• PNIO_ERR_PRM_INVALIDARG
• PNIO_ERR_PRM_ADD
• PNIO_ERR_SEQUENCE

4.7.2 PNIO_CBE_CTRL_DIAG_CONF

在调用PNIO_ctrl_diag_req函数后，会触发PNIO_CBE_CTRL_DIAG_CONF事件

4.8 保留数据的接口

保留数据保存了上次掉电时的一些信息，包括了IPv4、设备名称和MIB对象，将在下一次系统启动时加载。

PN Driver使用一个XML文件保存了保留数据，IO-Base的控制器应用程序咋系统重启时加载该XML文件。

4.8.1 PNIO_CBE_REMA_READ_CONF

如果修改了保留数据文件，将会触发PNIO_CBE_REMA_READ_CONF事件

4.8.1.1 PNIO_interface_set_ip_and_nos

设置通信接口的IP地址和设备名

4.8.1.2 DCP/SNMP请求

4.8.1.3 ResetToFactory

恢复出厂设置

4.9 等时实时（IRT）接口函数

本文着重控制器RT实时等级应用程序编程，IRT接口暂是没有用到，后续将陆续增加。

4.9.1 PNIO_CP_register_cbf

注册事件及其回调函数，当事件发生时将触发执行回调函数。注意：该函数调用只能在控制器的OFFLINE模式下

4.9.2 PNIO_CP_CBE_STARTOP_IND和PNIO_CP_CBE_STARTOP_CYCLEINFO_IND

本文着重控制器RT实时等级应用编程，该事件用于IRT，后续将陆续增加。

4.9.3 PNIO_CP_set_opdone

本文着重控制器RT实时等级应用编程，该函数为IRT接口，后续将陆续增加。

4.9.4 PNIO_CP_CBE_OPFAULT_IND

本文着重控制器RT实时等级应用编程，该事件用于IRT，后续将陆续增加。