137 lines
4.3 KiB
Markdown
137 lines
4.3 KiB
Markdown
# API 参考
|
||
|
||
本文仅记录 AISU 830T Card Reader SDK v0.1.0 中面向 Unity 使用者的公开 API。命名空间为 `Aisu.CardReader`。
|
||
|
||
## CardReaderManager
|
||
|
||
`CardReaderManager` 是场景级读卡器管理组件。将它添加到场景中的 GameObject，并保持一个实例。
|
||
|
||
### 主要属性
|
||
|
||
```csharp
|
||
public static CardReaderManager Instance { get; }
|
||
public SerialDeviceOptions SerialOptions { get; set; }
|
||
public bool IsConnected { get; }
|
||
```
|
||
|
||
- `Instance`：当前场景中的 Manager。
|
||
- `SerialOptions`：Inspector 和代码使用的串口配置。
|
||
- `IsConnected`：当前是否已连接。
|
||
|
||
### 主要方法
|
||
|
||
```csharp
|
||
public void OpenReader();
|
||
public void CloseReader();
|
||
```
|
||
|
||
`OpenReader()` 启动读卡器连接。`CloseReader()` 关闭当前连接并停止自动重连；之后可以再次调用 `OpenReader()`。
|
||
|
||
### 事件
|
||
|
||
```csharp
|
||
public UnityEvent OnConnected { get; }
|
||
public UnityEvent OnDisconnected { get; }
|
||
public UnityEvent<SerialDeviceState> OnStateChanged { get; }
|
||
public UnityEvent<CardInfo> OnCardReceived { get; }
|
||
public UnityEvent<CardReaderErrorEventArgs> OnError { get; }
|
||
```
|
||
|
||
事件使用 `AddListener` 和 `RemoveListener`。通过 Manager 接收的 UnityEvent 在 Unity 主线程派发。
|
||
|
||
## CardReaderApi
|
||
|
||
`CardReaderApi` 是当前 `CardReaderManager` 的静态访问入口，适合在业务脚本中使用。
|
||
|
||
```csharp
|
||
public static bool IsConnected { get; }
|
||
public static void Open();
|
||
public static void Close();
|
||
|
||
public static UnityEvent OnConnected { get; }
|
||
public static UnityEvent OnDisconnected { get; }
|
||
public static UnityEvent<SerialDeviceState> OnStateChanged { get; }
|
||
public static UnityEvent<CardInfo> OnCardReceived { get; }
|
||
public static UnityEvent<CardReaderErrorEventArgs> OnError { get; }
|
||
```
|
||
|
||
`Open()` 与 `Close()` 的行为分别是启动连接和关闭连接。没有活动的 `CardReaderManager` 时，调用方法或访问事件会抛出 `InvalidOperationException`。
|
||
|
||
## SerialDeviceOptions
|
||
|
||
`SerialDeviceOptions` 是 `CardReaderManager.SerialOptions` 的配置类型。当前公开字段如下：
|
||
|
||
| 字段 | 类型 | 默认值 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `PortName` | `string` | 无 | Windows COM 端口名称。 |
|
||
| `BaudRate` | `int` | `9600` | 波特率。 |
|
||
| `Parity` | `Parity` | `None` | 校验方式。 |
|
||
| `DataBits` | `int` | `8` | 数据位。 |
|
||
| `StopBits` | `StopBits` | `One` | 停止位。 |
|
||
| `Handshake` | `Handshake` | `None` | 握手方式。 |
|
||
| `ReadTimeout` | `int` | `100` | 读超时，单位毫秒。 |
|
||
| `WriteTimeout` | `int` | `1000` | 写超时，单位毫秒。 |
|
||
| `RtsEnable` | `bool` | `true` | 是否启用 RTS。 |
|
||
| `DtrEnable` | `bool` | `true` | 是否启用 DTR。 |
|
||
| `AutoReconnect` | `bool` | `true` | 连接异常后是否继续自动重连。 |
|
||
| `ReconnectInterval` | `int` | `1000` | 自动重连间隔，单位毫秒。 |
|
||
| `MaxPendingSendCount` | `int` | `256` | 待发送数据容量。 |
|
||
|
||
实际设备的 COM 口和 UART 参数可能不同，请以设备配置为准。
|
||
|
||
## CardInfo
|
||
|
||
`CardInfo` 是 `OnCardReceived` 提供的卡片信息：
|
||
|
||
```csharp
|
||
public CardType CardType { get; }
|
||
public byte CardTypeCode { get; }
|
||
public string CardNumber { get; }
|
||
```
|
||
|
||
- `CardType`：当前已知类型为 `CardType.EM4100`。
|
||
- `CardTypeCode`：设备上报的原始类型码。未知类型不会丢失。
|
||
- `CardNumber`：十进制卡号字符串。
|
||
|
||
### CardNumber 规则
|
||
|
||
`CardNumber` 的类型为 `string`，表示十进制卡号字符串。默认最小长度为 10 位：不足 10 位时左侧补 `0`，超过 10 位时不截断。
|
||
|
||
## CardType
|
||
|
||
```csharp
|
||
public enum CardType
|
||
{
|
||
Unknown = 0,
|
||
EM4100 = 0x02
|
||
}
|
||
```
|
||
|
||
## 错误事件
|
||
|
||
`OnError` 提供 `CardReaderErrorEventArgs`：
|
||
|
||
```csharp
|
||
public CardReaderException Exception { get; }
|
||
```
|
||
|
||
`Exception` 是真实异常对象。常见原因包括 COM 端口不存在、端口被其他程序占用和连接失败。相同的连接错误不会持续重复派发，但在 `AutoReconnect` 开启时 SDK 仍会继续尝试连接。
|
||
|
||
## 事件使用约定
|
||
|
||
推荐在 `OnEnable` 中使用 `AddListener` 注册，在 `OnDisable` 中使用 `RemoveListener` 解除。生命周期示例：
|
||
|
||
```csharp
|
||
private void OnEnable()
|
||
{
|
||
CardReaderApi.OnCardReceived.AddListener(OnCardReceived);
|
||
}
|
||
|
||
private void OnDisable()
|
||
{
|
||
CardReaderApi.OnCardReceived.RemoveListener(OnCardReceived);
|
||
}
|
||
```
|
||
|
||
`CardReaderManager` 销毁或应用退出时会自动释放串口资源。
|