属性与状态机
属性
| 类别 | 属性 | 类型 | 访问 | 说明 |
|---|---|---|---|---|
| 静态 | isServiceReady() | boolean | 只读 | 本机服务是否就绪 |
getLastError() | String | 只读 | 全应用最近一次失败文案（sticky，成功路径不清空） | |
getLastErrorCode() | PnSErr | 只读 | 全应用最近一次失败的调用错误码。从未失败为 OK | |
isServiceConnected() | boolean | 只读 | 主站是否周期交换。服务没起来 = false | |
getServiceState() | PnSState | 只读 | 运行态。服务没起来 = UNKNOWN | |
getServiceWaitReason() | String | 只读 | 等待原因。服务没起来 = 「服务未就绪」 | |
getServiceStatusMessage() | String | 只读 | 状态文案。服务没起来 = 「服务未就绪」 | |
| 连接与会话 | isConnected() | boolean | 只读 | IO 控制器是否已经建立周期数据交换。true 才表示周期数据在换 |
isAttached() | boolean | 只读 | 本 SDK 会话是否已连上本机服务。stop 不改变 | |
isStarted() | boolean | 只读 | IO 设备是否已启用（start 之后、stop 之前） | |
| 运行态 | getStatus() | PnSState | 只读 | 运行态枚举。读不到真实状态为 UNKNOWN |
getWaitReason() | String | 只读 | 本会话等待原因。主站已连时为空 | |
isEverConnected() | boolean | 只读 | 是否曾与 IO 控制器建立过连接。true 且 isConnected 为 false = 掉线 | |
| 错误码 | getErrorCodeEnum() | PnSRuntimeErrorCode | 只读 | 最近一次运行错误。未识别值 UNKNOWN |
getErrorCodeRaw() | int | 只读 | 运行错误原值（0 = 无错误）。未识别值仍经本方法透传 | |
getErrorMessage() | String | 只读 | 运行错误中文消息 | |
getLastServiceError() | String | 只读 | 本会话最近一次失败文案（sticky，成功路径不清空） | |
| 诊断入口 | getEvents() | PnSEvents | 只读 | 运行态事件。见事件页 |
getDiagSnapshot() | PnSDiagSnapshot | 只读 | 诊断快照。字段见诊断页 | |
getIoStatus() | PnSIoStatus | 只读 | IOPS / IOCS。见诊断页 | |
getProcessData() | ProcessData | 只读 | 过程数据。见过程数据页 | |
| 本机会话 | getHost() | String | 只读 | 本会话连接的服务主机 |
getPort() | int | 只读 | 本会话连接的服务端口 |
PnSState
运行态类型。取值见 枚举参考。
PnSRuntimeErrorCode
运行错误码类型。取值见 枚举参考。
启停
start()
public void start()
启用 IO 设备。已 start 且尚未 stop 则直接返回。这不是主站已周期交换，主站是否在换数据看 isConnected()。
失败抛 PnSServiceException，并写入静态 getLastError()。
示例：
try {
device.start();
} catch (PnSServiceException e) {
System.err.println(PnSService.getLastError());
}
stop()
public void stop()
停用 IO 设备。实例仍在，可再次 start()。未 start 或已 stop 则直接返回。失败写 getLastError，不抛。
不是 close()：stop 不结束 SDK 会话。
示例：
device.stop();
运行态
getStatus()
运行态。start / stop 只管启用 / 停用 IO 设备；本方法始终按现场如实读。读不到真实状态为 UNKNOWN。不可达时抛 PnSServiceException。
public PnSState getStatus()
示例：
if (device.getStatus() == PnSState.DATA_EXCHANGE)
System.out.println("周期数据交换中");
getStatusEx()
public ServiceStatus getStatusEx()
一次取回运行态、是否已交换、运行错误码。未建立会话 / 不可达抛 PnSServiceException。
ServiceStatus
public static final class ServiceStatus {
public PnSState getState() { }
public boolean isConnected() { }
public int getErrorCode() { }
public PnSRuntimeErrorCode getErrorCodeEnum() { }
public String getWaitReason() { }
public String getStatusMessage() { }
public int getAlarmCount() { }
public int getCriticalAlarmCount() { }
public boolean isEverConnected() { }
}
示例：
PnSService.ServiceStatus snap = device.getStatusEx();
if (!snap.isConnected())
System.out.println(snap.getState() + " " + snap.getWaitReason());
getWaitReason()
public String getWaitReason()
本会话等待原因。主站已连时为空。循环 if (!device.isConnected()) 时读本方法或 getLastServiceError()。
示例：
if (!device.isConnected())
System.out.println(device.getWaitReason());
isEverConnected()
public boolean isEverConnected()
是否曾与 IO 控制器建立过连接。false = 从未连过；true 且 isConnected() == false = 掉线。掉线后此判别仍保留。
示例：
if (!device.isConnected() && device.isEverConnected())
System.out.println("掉线");
错误码
getErrorCodeEnum()
public PnSRuntimeErrorCode getErrorCodeEnum()
最近一次运行错误（枚举）。未识别值 UNKNOWN。原值仍经 getErrorCodeRaw() 透传。中文消息用 getErrorMessage()。
示例：
PnSRuntimeErrorCode err = device.getErrorCodeEnum();
String text = device.getErrorMessage();
int raw = device.getErrorCodeRaw();
getErrorCodeRaw()
public int getErrorCodeRaw()
运行错误原值（0 = 无错误）。未识别值仍经本方法透传。
示例：
int raw = device.getErrorCodeRaw();
getErrorMessage()
public String getErrorMessage()
运行错误中文消息。未识别码返回带原值的说明，不丢信息。
示例：
System.out.println(device.getErrorMessage());
getLastServiceError()
public String getLastServiceError()
本会话最近一次失败文案（sticky）。成功路径不清空。循环 if (!isConnected()) 时若本方法为空，读 getWaitReason()。
示例：
System.out.println(device.getLastServiceError());
诊断
getDiagSnapshot()
public PnSDiagSnapshot getDiagSnapshot()
一次取回链路、帧计数、看门狗、抖动。读不到时 isOk() == false，读 getMessage()，不视为异常。字段见 诊断。
示例：
PnSDiagSnapshot snap = device.getDiagSnapshot();
if (!snap.isOk())
System.out.println(snap.getMessage());
getIoStatus()
public PnSIoStatus getIoStatus()
IOPS / IOCS 快照。0x80 = GOOD，0x00 = BAD。掉线如实全 BAD。读不到返回 PnSIoStatus.getEmpty()。字段见 诊断。
示例：
if (!device.getIoStatus().isAllGood())
System.out.println(device.getIoStatus().toString());
调用异常
失败抛 PnSServiceException（继承 com.darra.pns.PnSSdkException，携带 PnSErr 错误码与细节）。
public class PnSServiceException extends PnSSdkException
| 类别 | 属性 | 类型 | 访问 | 说明 |
|---|---|---|---|---|
| 调用异常 | getMessage() | String | 只读 | 中文消息（码描述 + 细节） |
getCode() | PnSErr | 只读 | SDK 调用错误码 | |
getDetail() | String | 只读 | 失败细节 | |
getServerErrorCode() | int | 只读 | 运行错误原值。0 = 未携带 |
示例：
try {
device.writeInt16("QW0", (short) 1);
} catch (PnSServiceException e) {
System.err.println(e.getMessage());
System.err.println(e.getCode());
if (e.getServerErrorCode() != 0)
System.err.println(e.getServerErrorCode());
}
PnSErr
SDK 调用错误码（0 = 成功）。取值见 枚举参考。
Java 现用正值编码，与其它语言负值制语义对应但数值不同。
静态 PnSService.getLastError() / getLastErrorCode() 在没有实例时读最近失败（sticky）。
完整示例
import com.darra.pns.service.PnSService;
import com.darra.pns.service.PnSServiceException;
try (PnSService device = new PnSService()) {
device.start();
while (running) {
if (!device.isConnected()) {
System.out.println(device.getStatus());
System.out.println(device.getWaitReason());
System.out.println(device.getErrorMessage());
continue;
}
device.writeBool("Q0.0", true);
boolean fromPlc = device.readBool("I0.0");
}
device.stop();
} catch (PnSServiceException e) {
System.err.println(e.getMessage());
}