属性与状态机
属性
| 类别 | 属性 | 类型 | 访问 | 说明 |
|---|---|---|---|---|
| 静态 | isServiceReady() | boolean | 只读 | 本机服务是否就绪 |
lastError() | String | 只读 | 全应用最近一次失败文案（sticky，成功路径不清空） | |
lastErrorCode() | PnSErr | 只读 | 全应用最近一次失败的调用错误码。从未失败为 OK | |
serviceConnected() | boolean | 只读 | 主站是否周期交换。服务没起来 = false | |
serviceState() | PnSState | 只读 | 运行态。服务没起来 = UNKNOWN | |
serviceWaitReason() | String | 只读 | 等待原因。服务没起来 = 「服务未就绪」 | |
serviceStatusMessage() | String | 只读 | 状态文案。服务没起来 = 「服务未就绪」 | |
| 连接与会话 | connected() / isConnected() | boolean | 只读 | IO 控制器是否已经建立周期数据交换。true 才表示周期数据在换 |
attached() / isAttached() | boolean | 只读 | 本 SDK 会话是否已连上本机服务。stop 不改变 | |
isStarted() | boolean | 只读 | IO 设备是否已启用（start 之后、stop 之前） | |
| 运行态 | status() | PnSState | 只读 | 运行态枚举。读不到真实状态为 UNKNOWN |
waitReason() | String | 只读 | 本会话等待原因。主站已连时为空 | |
everConnected() | boolean | 只读 | 是否曾与 IO 控制器建立过连接。true 且 connected 为 false = 掉线 | |
| 错误码 | errorCodeEnum() | PnSRuntimeErrorCode | 只读 | 最近一次运行错误。未识别值 UNKNOWN |
errorCodeRaw() | int | 只读 | 运行错误原值（0 = 无错误）。未识别值仍经本方法透传 | |
errorMessage() | String | 只读 | 运行错误中文消息 | |
lastServiceError() | String | 只读 | 本会话最近一次失败文案（sticky，成功路径不清空） | |
| 诊断入口 | events() | PnSEvents | 只读 | 运行态事件。见 [事件](./events) |
diagSnapshot() | PnSDiagSnapshot | 只读 | 诊断快照。字段见 [诊断](./diagnostics) | |
ioStatus() | PnSIoStatus | 只读 | IOPS / IOCS。见 [诊断](./diagnostics) | |
processData() | ProcessData | 只读 | 过程数据。见 [过程数据](./io) | |
| 本机会话 | host() | String | 只读 | 本会话连接的服务主机 |
port() | int | 只读 | 本会话连接的服务端口 |
PnSState
运行态类型。取值见 枚举参考。
PnSRuntimeErrorCode
运行错误码类型。取值见 枚举参考。
启停
start()
public void start()
启用 IO 设备。已 start 且尚未 stop 则直接返回。这不是主站已周期交换，主站是否在换数据看 connected()。
失败抛 PnSServiceException，并写入静态 lastError()。
示例：
try {
device.start();
} catch (PnSServiceException e) {
System.err.println(PnSService.lastError());
}
stop()
public void stop()
停用 IO 设备。实例仍在，可再次 start()。未 start 或已 stop 则直接返回。失败写 lastError，不抛。
不是 close()：stop 不结束 SDK 会话。
示例：
device.stop();
运行态
status()
运行态。start / stop 只管启用 / 停用 IO 设备；本方法始终按现场如实读。读不到真实状态为 UNKNOWN。不可达时抛 PnSServiceException。
public PnSState status()
示例：
if (device.status() == PnSState.RUNNING)
System.out.println("从站运行中");
statusEx()
public ServiceStatus statusEx()
一次取回运行态、是否已交换、运行错误码。未建立会话 / 不可达抛 PnSServiceException。
ServiceStatus
public static final class ServiceStatus {
public PnSState state() { }
public boolean connected() { }
public int errorCode() { }
public PnSRuntimeErrorCode errorCodeEnum() { }
public String waitReason() { }
public String statusMessage() { }
public int alarmCount() { }
public int criticalAlarmCount() { }
public boolean everConnected() { }
}
示例：
PnSService.ServiceStatus snap = device.statusEx();
if (!snap.connected())
System.out.println(snap.state() + " " + snap.waitReason());
waitReason()
public String waitReason()
本会话等待原因。主站已连时为空。循环 if (!device.connected()) 时读本方法或 lastServiceError()。
示例：
if (!device.connected())
System.out.println(device.waitReason());
everConnected()
public boolean everConnected()
是否曾与 IO 控制器建立过连接。false = 从未连过；true 且 connected() == false = 掉线。掉线后此判别仍保留。
示例：
if (!device.connected() && device.everConnected())
System.out.println("掉线");
错误码
errorCodeEnum()
public PnSRuntimeErrorCode errorCodeEnum()
最近一次运行错误（枚举）。未识别值 UNKNOWN。原值仍经 errorCodeRaw() 透传。中文消息用 errorMessage()。
示例：
PnSRuntimeErrorCode err = device.errorCodeEnum();
String text = device.errorMessage();
int raw = device.errorCodeRaw();
errorCodeRaw()
public int errorCodeRaw()
运行错误原值（0 = 无错误）。未识别值仍经本方法透传。
示例：
int raw = device.errorCodeRaw();
errorMessage()
public String errorMessage()
运行错误中文消息。未识别码返回带原值的说明，不丢信息。
示例：
System.out.println(device.errorMessage());
lastServiceError()
public String lastServiceError()
本会话最近一次失败文案（sticky）。成功路径不清空。循环 if (!connected()) 时若本方法为空，读 waitReason()。
示例：
System.out.println(device.lastServiceError());
诊断
diagSnapshot()
public PnSDiagSnapshot diagSnapshot()
一次取回链路、帧计数、看门狗、抖动。读不到时 ok() == false，读 message()，不视为异常。getDiag() 同义。字段见 诊断。
示例：
PnSDiagSnapshot snap = device.diagSnapshot();
if (!snap.ok())
System.out.println(snap.message());
ioStatus()
public PnSIoStatus ioStatus()
IOPS / IOCS 快照。0x80 = GOOD，0x00 = BAD。掉线如实全 BAD。读不到返回 PnSIoStatus.empty()。字段见 诊断。
示例：
if (!device.ioStatus().allGood())
System.out.println(device.ioStatus().toString());
调用异常
失败抛 PnSServiceException。
public class PnSServiceException extends RuntimeException
| 类别 | 属性 | 类型 | 访问 | 说明 |
|---|---|---|---|---|
| 调用异常 | getMessage() | String | 只读 | 中文消息（码描述 + 细节） |
code() | PnSErr | 只读 | SDK 调用错误码 | |
detail() | String | 只读 | 失败细节 | |
serverErrorCode() | int | 只读 | 运行错误原值。0 = 未携带 |
示例：
try {
device.writeInt16("QW0", (short) 1);
} catch (PnSServiceException e) {
System.err.println(e.getMessage());
System.err.println(e.code());
if (e.serverErrorCode() != 0)
System.err.println(e.serverErrorCode());
}
PnSErr
SDK 调用错误码（0 = 成功）。取值见 枚举参考。
Java 现用正值编码，与其它语言负值制语义对应但数值不同。
静态 PnSService.lastError() / lastErrorCode() 在没有实例时读最近失败（sticky）。
完整示例
import com.darra.pns.service.PnSService;
import com.darra.pns.service.PnSServiceException;
try (PnSService device = new PnSService()) {
device.start();
while (running) {
if (!device.connected()) {
System.out.println(device.status());
System.out.println(device.waitReason());
System.out.println(device.errorMessage());
continue;
}
device.writeBool("Q0.0", true);
boolean fromPlc = device.readBool("I0.0");
}
device.stop();
} catch (PnSServiceException e) {
System.err.println(e.getMessage());
}