PNDriver用户编程接口说明之二

5 以太网接口的功能和数据类型

本文源自西门子的技术文档《IO-Base User Programming Interface for PN Driver》的第5章，描述了PROFINET主站中与以太网接口相关的接口与方法，将作为PNDriver用户编程接口说明的第二篇笔记。

5.1 接口函数

5.1.1 PNIO_interface_open

描述：调用该函数打开以太网接口，在初始化过程中进行调用，通过注册报警、读写数据纪录、修改IP地址、修改设备名相关的事件及其回调函数，可以获取与以太网接口相关的事件。

函数形式：

PNIO_UINT32 PNIO_CODE_ATTR PNIO_interface_open(
    PNIO_UINT32 CpIndex,
    PNIO_CBF cbf_RecReadConf, //in
    PNIO_CBF cbf_RecWriteConf, //in
    PNIO_CBF cbf_AlarmInd, //in
    PNIO_UINT32 * Handle //in
);

参数名	参数描述
CpIndex	模块索引
cbf_RecReadConf	读记录数据回调函数，可以为空
cbf_RecWriteConf	写记录数据回调函数，可以为空
cbf_AlarmInd	报警通知回调函数，可以为空
Handle	控制器句柄

返回值：

• PNIO_OK
• PNIO_ERR_CREATE_INSTANCE
• PNIO_ERR_INTERNAL
• PNIO_ERR_NO_RESOURCE
• PNIO_ERR_PRM_CP_ID
• PNIO_ERR_PRM_HND
• PNIO_ERR_SEQUENCE
• PNIO_ERR_WRONG_HND

5.1.2 PNIO_interface_register_cbf

描述：该函数可以手动注册以太网接口相关的事件及其回调函数

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

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

返回值：

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

5.1.3 PNIO_interface_close

描述：该函数关闭以太网接口，调用该函数后就不能收到诸如和以太网接口相关的报警、读写数据纪录、修改IP地址、修改设备名相关的事件

函数形式：

PNIO_UINT32 PNIO_CODE_ATTR PNIO_interface_close(
    PNIO_UINT32  Handle //in
);

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

返回值：

• PNIO_OK
• PNIO_ERR_NO_RESOURCE
• PNIO_ERR_WRONG_HND

5.1.4 PNIO_interface_set_ip_and_nos

描述：调用该函数用于修改IP地址和设备名

注意：需要保证IP地址没有提前分配，而且从站设备名能够被修改

函数形式：

PNIO_UINT32 PNIO_CODE_ATTR PNIO_interface_set_ip_and_nos(
    PNIO_UINT32 Handle, //in
    PNIO_SET_IP_NOS_MODE_TYPE Mode, //in
    PNIO_IPv4 IPv4, //in
    PNIO_NOS NoS //in
);

参数名	参数描述
CpIndex	模块索引
Mode	修改IP地址还是设置设备名
IPv4	IP地址
NoS	设备名NoS

返回值：

• PNIO_OK
• PNIO_ERR_INTERNAL
• PNIO_ERR_MODE_VALUE
• PNIO_ERR_NOT_REENTERABLE
• PNIO_ERR_PRM_HND
• PNIO_ERR_PRM_IP PNIO_ERR_PRM_NOS
• PNIO_ERR_PRM_NOS_LEN
• PNIO_ERR_SEQUENCE
• PNIO_ERR_SET_IP_NOS_NOT_ALLOWED
• PNIO_ERR_WRONG_HND

5.2 数据记录函数及其数据结构

5.2.1 PNIO_interface_rec_read_req

描述：该函数用于请求读取网络设备的记录数据

函数形式：

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

参数名	参数描述
CpIndex	模块索引
pAddr	模块地址
RecodeIndex	纪录数据索引
ReqRef
Length	读出记录数据的长度

返回值：

• PNIO_OK
• PNIO_ERR_INTERNAL
• PNIO_ERR_NO_RESOURCE
• PNIO_ERR_PRM_ADD
• PNIO_ERR_PRM_REC_INDEX
• PNIO_ERR_SEQUENCE
• PNIO_ERR_VALUE_LEN
• PNIO_ERR_WRONG_HND

5.2.2 PNIO_CBE_IFC_REC_READ_CONF

记录数据读取事件

结构体：

typedef struct {
    PNIO_ADDR * pAddr;
    PNIO_UINT32 RecordIndex;
    PNIO_REF ReqRef;
    PNIO_UINT32 Response;
    PNIO_ERR_STAT Err;
    PNIO_UINT32 Length;
    const PNIO_UINT8 * pBuffer;
} ATTR_PACKED PNIO_CBE_PRM_REC_READ_CONF;

说明：

成员变量	描述
pAddr	模块地址
RecodeIndex	纪录数据索引
ReqRef	写入事件
Response	写请求的回复
Err	错误码
Length	需要d读出的记录数据长度
pBuffer	读出的记录数据的缓冲区

5.2.3 PNIO_interface_rec_write_req

描述：该函数用于请求写入网络设备的记录数据

函数形式：

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

参数名	参数描述
CpIndex	模块索引
pAddr	模块地址
RecodeIndex	纪录数据索引
ReqRef	写入事件
Length	需要写入的记录数据长度
pBuffer	写入的记录数据的缓冲区

返回值：

• PNIO_OK
• PNIO_ERR_NO_RESOURCE
• PNIO_ERR_PRM_ADD
• PNIO_ERR_PRM_BUF
• PNIO_ERR_PRM_REC_INDEX
• PNIO_ERR_SEQUENCE
• PNIO_ERR_VALUE_LEN
• PNIO_ERR_WRONG_HND

5.2.4 PNIO_CBE_IFC_REC_WRITE_CONF

记录数据写入事件

结构体：

typedef struct {
    PNIO_ADDR * pAddr;
    PNIO_UINT32 RecordIndex;
    PNIO_REF ReqRef;
    PNIO_UINT32 Response;
    PNIO_ERR_STAT Err;
} ATTR_PACKED PNIO_CBE_PRM_REC_WRITE_CONF;

说明：

成员变量	描述
pAddr	模块地址
RecodeIndex	纪录数据索引
ReqRef	写入事件
Response	写请求的回复
Err	错误码

5.3 报警接口

5.3.1 PNIO_CBE_IFC_ALARM_IND

当主站以太网接口出现异常时将会产生以太网接口报警事件。

结构体：

typedef struct {
    PNIO_ADDR * pAddr;
    PNIO_REF IndRef;
    const PNIO_CTRL_ALARM_DATA * pAlarmData;
} ATTR_PACKED PNIO_CBE_PRM_ALARM_IND;

说明：

成员变量	描述
pAddr	发出报警事件的模块地址
ReqRef	报警事件
pAlarmData	报警相关数据信息

5.4 应用程序就绪指示接口函数

5.4.1 PNIO_CBE_IFC_APPL_READY

PNIO_CBE_IFC_APPL_READY作为以太网接口就绪事件，用于在以太网接口完成参数化后进行通知，如果要处理该事件，可以在SERV_CP_startup函数中注册以太网接口就绪事件回调函数。

注意：在应用程序中不是一定需要注册应用就绪事件，如果没有注册该事件，那么该事件由协议栈默认处理，处理方式就是立刻返回，只有注册了回调函数时，该时间才会由回调函数进行额外处理，这里有的像嵌入式操作系统中的中断处理，分为isr和实际处理两个部分，前者快速返回，后者实际处理中断

结构体：

typedef struct {
    const PNIO_CTRL_APPL_READY_DATA * pApplReadyData;
} ATTR_PACKED PNIO_CBE_PRM_APPL_READY_IND;

说明：

成员变量	描述
pApplReadyData	以太网接口就绪事件相关数据信息