289 lines
15 KiB
Markdown
289 lines
15 KiB
Markdown
# SDK API 参考
|
|
|
|
English documentation: [SDK_API_Reference.md](SDK_API_Reference.md).
|
|
|
|
本文列出 `xin.aisu.si-m1.face` 对外公开的业务层 API。公开包为 DLL-only 形式，不包含 SDK 源码。
|
|
|
|
## 命名空间
|
|
|
|
| 命名空间 | 说明 |
|
|
|---|---|
|
|
| `Aisu.SIM1.Face.Core` | Manager、配置、回调适配、日志、主线程调度 |
|
|
| `Aisu.SIM1.Face.Commands` | 业务服务、命令服务、加密适配接口 |
|
|
| `Aisu.SIM1.Face.Protocol` | 协议枚举、封包/拆包、编码工具 |
|
|
| `Aisu.SIM1.Face.Transport` | 通信接口、串口通信、Mock 通信 |
|
|
| `Aisu.SIM1.Face.Models` | Reply、Note、用户、验证、录入、图片、UVC 等模型 |
|
|
|
|
## FaceModuleManager
|
|
|
|
推荐使用 `FaceModuleManager` 作为统一入口：
|
|
|
|
```csharp
|
|
using Aisu.SIM1.Face.Core;
|
|
```
|
|
|
|
### 属性
|
|
|
|
| 属性 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| `Basic` | `FaceBasicService` | 基础命令服务 |
|
|
| `Verify` | `FaceVerifyService` | 人脸验证服务 |
|
|
| `Enrollment` | `FaceEnrollmentService` | 人脸录入服务 |
|
|
| `Users` | `FaceUserService` | 用户管理服务 |
|
|
| `QrCode` | `FaceQrCodeService` | 二维码服务 |
|
|
| `Images` | `FaceImageService` | 图片抓拍与照片注册服务 |
|
|
| `Features` | `FaceFeatureService` | 特征读写服务 |
|
|
| `Uvc` | `FaceUvcService` | UVC 和高级参数服务 |
|
|
| `Encryption` | `FaceEncryptionService` | 加密服务 |
|
|
| `Callback` | `FaceModuleCallbackAdapter` | 回调式 API 适配器 |
|
|
| `IsOpen` | `bool` | 通信是否打开 |
|
|
| `IsReady` | `bool` | 是否收到 READY |
|
|
| `CurrentStatus` | `FaceModuleStatus` | 当前模组状态 |
|
|
| `LastError` | `string` | 最近错误信息 |
|
|
| `CurrentCommand` | `string` | 当前命令名称 |
|
|
| `Config` | `FaceModuleConfig` | 当前运行配置 |
|
|
| `Settings` | `FaceSdkSettings` | 当前绑定配置资产 |
|
|
|
|
### 方法
|
|
|
|
| 方法 | 说明 |
|
|
|---|---|
|
|
| `ConfigureTransport(IFaceModuleTransport transport)` | 注入自定义通信层 |
|
|
| `Configure(bool useMockInEditor, string portName, int baudRate)` | 兼容旧代码的快速配置入口 |
|
|
| `ApplySettings(FaceSdkSettings sdkSettings)` | 应用 ScriptableObject 配置并重建 transport |
|
|
| `Open()` | 打开通信 |
|
|
| `Close()` | 关闭通信 |
|
|
| `WaitReadyAsync(int timeoutMs = 5000)` | 等待 READY NOTE |
|
|
| `ProbeReadyByStatusAsync()` | 主动查询状态并标记 READY |
|
|
| `SendRawBytes(byte[] bytes)` | 发送原始协议 bytes |
|
|
| `RefreshStatus()` | 异步刷新 `CurrentStatus` |
|
|
|
|
### 事件
|
|
|
|
| 事件 | 说明 |
|
|
|---|---|
|
|
| `OnReady` | 首次 READY |
|
|
| `OnStatusChanged(FaceModuleStatus)` | 当前状态变化 |
|
|
| `OnReplyReceived(FaceReply)` | 收到 REPLY 包 |
|
|
| `OnNoteReceived(FaceNote)` | 收到 NOTE 包 |
|
|
| `OnFaceStateUpdated(FaceFaceStateNote)` | 收到人脸状态 NOTE |
|
|
| `OnQrCodeReceived(string)` | 收到二维码 NOTE |
|
|
| `OnFeatureReceived(byte[])` | 收到特征数据包 |
|
|
| `OnDataPacketReceived(FacePacket)` | 收到图片或模板数据包 |
|
|
| `OnError(FaceResultCode, string)` | 错误上报 |
|
|
| `OnRawLog(string)` | 原始 TX/RX 日志 |
|
|
|
|
## 异步服务 API
|
|
|
|
### FaceBasicService
|
|
|
|
访问路径：`manager.Basic`
|
|
|
|
| 方法 | 返回 | 说明 |
|
|
|---|---|---|
|
|
| `ResetAsync()` | `Task<FaceReply>` | 复位模组 |
|
|
| `FaceResetAsync()` | `Task<FaceReply>` | 取消当前人脸流程 |
|
|
| `GetStatusAsync()` | `Task<FaceModuleStatus>` | 获取模组状态 |
|
|
| `GetVersionAsync()` | `Task<string>` | 获取固件版本 |
|
|
| `GetSnAsync()` | `Task<string>` | 获取设备序列号 |
|
|
| `SetDemoModeAsync(bool enable)` | `Task<FaceReply>` | 设置 Demo Mode |
|
|
| `UpgradeFirmwareAsync()` | `Task<FaceReply>` | 启动固件升级命令 |
|
|
|
|
### FaceVerifyService
|
|
|
|
访问路径：`manager.Verify`
|
|
|
|
| 方法 | 返回 | 说明 |
|
|
|---|---|---|
|
|
| `VerifyAsync(byte timeout, byte maxRecognitionTimes = 30)` | `Task<FaceVerifyResult>` | 单次人脸验证 |
|
|
| `AutoVerifyAsync(bool enable, byte timeout)` | `Task<FaceVerifyResult>` | 启用或关闭自动验证 |
|
|
|
|
### FaceEnrollmentService
|
|
|
|
访问路径：`manager.Enrollment`
|
|
|
|
| 方法 | 返回 | 说明 |
|
|
|---|---|---|
|
|
| `EnrollAsync(bool admin, string userName, FaceDirection direction, byte timeout)` | `Task<FaceEnrollResult>` | 交互式多方向录入 |
|
|
| `EnrollSingleAsync(bool admin, string userName, byte timeout)` | `Task<FaceEnrollResult>` | 单帧录入 |
|
|
| `EnrollIntegratedAsync(bool admin, string userName, FaceDirection direction, byte timeout, bool singleFrame = false, bool duplicateCheck = true)` | `Task<FaceEnrollResult>` | 集成式录入 |
|
|
| `EnrollSnapFaceImageAsync(bool admin, string userName)` | `Task<FaceEnrollResult>` | 抓拍人脸后注册 |
|
|
|
|
### FaceUserService
|
|
|
|
访问路径：`manager.Users`
|
|
|
|
| 方法 | 返回 | 说明 |
|
|
|---|---|---|
|
|
| `DeleteUserAsync(int userId)` | `Task<FaceReply>` | 删除指定用户 |
|
|
| `DeleteAllAsync()` | `Task<FaceReply>` | 删除全部用户 |
|
|
| `GetUserInfoAsync(int userId)` | `Task<FaceUserInfo>` | 查询指定用户信息 |
|
|
| `GetAllUserIdsAsync()` | `Task<List<int>>` | 查询全部用户 ID |
|
|
| `GetAllUserIds2Async()` | `Task<List<int>>` | 使用扩展命令查询全部用户 ID |
|
|
| `GetAllUserInfosAsync()` | `Task<List<FaceUserInfo>>` | 查询全部用户信息 |
|
|
| `GetAllUserInfos2Async()` | `Task<List<FaceUserInfo>>` | 使用扩展命令查询全部用户信息 |
|
|
|
|
### FaceQrCodeService
|
|
|
|
访问路径：`manager.QrCode`
|
|
|
|
| 方法 | 返回 | 说明 |
|
|
|---|---|---|
|
|
| `ScanQrCodeAsync(byte timeout)` | `Task<string>` | 扫描二维码并返回内容 |
|
|
|
|
### FaceImageService
|
|
|
|
访问路径：`manager.Images`
|
|
|
|
| 方法 | 返回 | 说明 |
|
|
|---|---|---|
|
|
| `SnapUploadImageAsync()` | `Task<FaceImageResult>` | 抓拍普通图片 |
|
|
| `SnapUploadFaceImageAsync()` | `Task<FaceImageResult>` | 抓拍人脸图片 |
|
|
| `SnapUploadLargeImageAsync(ImageDpi dpi)` | `Task<FaceImageResult>` | 抓拍大图 |
|
|
| `EnrollWithPhotoAsync(byte[] photoBytes, BioType type, string userName = null, bool duplicateCheck = true, Action<int, int> onProgress = null)` | `Task<FaceEnrollResult>` | 照片注册 |
|
|
| `EnrollWithPhotoAndIdAsync(int userId, byte[] photoBytes, BioType type, string userName = null, bool duplicateCheck = true, Action<int, int> onProgress = null)` | `Task<FaceEnrollResult>` | 指定用户 ID 照片注册 |
|
|
|
|
### FaceFeatureService
|
|
|
|
访问路径：`manager.Features`
|
|
|
|
| 方法 | 返回 | 说明 |
|
|
|---|---|---|
|
|
| `ReadFeatureAsync(int userId, FeatureType type)` | `Task<byte[]>` | 读取指定用户特征 |
|
|
| `WriteFeatureAsync(byte[] featureBytes, FeatureType type, string userName = null, Action<int, int> onProgress = null)` | `Task<FaceEnrollResult>` | 写入特征并注册 |
|
|
|
|
### FaceUvcService
|
|
|
|
访问路径：`manager.Uvc`
|
|
|
|
| 方法 | 返回 | 说明 |
|
|
|---|---|---|
|
|
| `ReadUsbUvcParametersAsync()` | `Task<UsbUvcParameters>` | 读取 USB/UVC 参数 |
|
|
| `SetUsbUvcParametersAsync(UsbUvcParameters parameters)` | `Task<FaceReply>` | 设置 USB/UVC 参数 |
|
|
| `SetFaceLocationDisplayAsync(bool visible)` | `Task<FaceReply>` | 设置人脸框显示 |
|
|
| `SetRgbLevelAsync(byte level)` | `Task<FaceReply>` | 设置 RGB 等级 |
|
|
| `SetDuplicateCheckAsync(bool enableCheck)` | `Task<FaceReply>` | 设置查重 |
|
|
| `ReadDuplicateCheckAsync()` | `Task<bool>` | 读取查重状态 |
|
|
|
|
### FaceEncryptionService
|
|
|
|
访问路径：`manager.Encryption`
|
|
|
|
| 方法 | 返回 | 说明 |
|
|
|---|---|---|
|
|
| `SetReleaseEncryptionKeyAsync(byte[] key16)` | `Task<FaceReply>` | 设置 Release 加密密钥 |
|
|
| `SetDebugEncryptionKeyAsync(byte[] key16)` | `Task<FaceReply>` | 设置 Debug 加密密钥 |
|
|
| `InitEncryptionAsync(byte[] seed4, byte mode)` | `Task<FaceReply>` | 初始化加密 |
|
|
| `EnableEncryption(IFaceModuleCrypto crypto)` | `void` | 启用本地加密算法适配器 |
|
|
| `DisableEncryption()` | `void` | 关闭本地加密算法适配器 |
|
|
|
|
```csharp
|
|
public interface IFaceModuleCrypto
|
|
{
|
|
byte[] Encrypt(byte[] plainBytes);
|
|
byte[] Decrypt(byte[] encryptedBytes);
|
|
byte[] GenerateSessionKey(byte[] seed4, byte[] encKey16);
|
|
}
|
|
```
|
|
|
|
## 回调式 API
|
|
|
|
`FaceModuleManager.Callback` 适合 Unity UI、按钮事件、旧项目回调风格或不方便使用 `await` 的业务。
|
|
|
|
回调规则：
|
|
|
|
- 成功时调用 `success`。
|
|
- 失败时调用 `error` 并传入错误信息。
|
|
- 照片注册和特征写入支持 `progress(current, total)`。
|
|
- 回调会通过 `FaceModuleMainThreadDispatcher` 回到 Unity 主线程。
|
|
|
|
### 生命周期与通信
|
|
|
|
| 方法 | 成功回调 | 说明 |
|
|
|---|---|---|
|
|
| `ConfigureTransport(IFaceModuleTransport transport, Action success, Action<string> error)` | `Action` | 注入自定义通信层 |
|
|
| `Configure(bool useMockInEditor, string portName, int baudRate, Action success, Action<string> error)` | `Action` | 配置默认通信参数 |
|
|
| `Open(Action success, Action<string> error)` | `Action` | 打开通信 |
|
|
| `Close(Action success, Action<string> error)` | `Action` | 关闭通信 |
|
|
| `SendRawBytes(byte[] bytes, Action success, Action<string> error)` | `Action` | 发送原始 bytes |
|
|
| `WaitReady(int timeoutMs, Action success, Action<string> error)` | `Action` | 等待 READY |
|
|
| `ProbeReadyByStatus(Action<FaceModuleStatus> success, Action<string> error)` | `Action<FaceModuleStatus>` | 主动探测状态并标记 READY |
|
|
|
|
### 基础命令
|
|
|
|
| 方法 | 成功回调 | 说明 |
|
|
|---|---|---|
|
|
| `Reset(Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 复位模组 |
|
|
| `FaceReset(Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 取消当前人脸流程 |
|
|
| `GetStatus(Action<FaceModuleStatus> success, Action<string> error)` | `Action<FaceModuleStatus>` | 获取模组状态 |
|
|
| `GetVersion(Action<string> success, Action<string> error)` | `Action<string>` | 获取固件版本 |
|
|
| `GetSn(Action<string> success, Action<string> error)` | `Action<string>` | 获取设备序列号 |
|
|
| `SetDemoMode(bool enable, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置 Demo Mode |
|
|
| `UpgradeFirmware(Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 启动固件升级 |
|
|
|
|
### 验证与录入
|
|
|
|
| 方法 | 成功回调 | 说明 |
|
|
|---|---|---|
|
|
| `Verify(byte timeout, Action<FaceVerifyResult> success, Action<string> error, byte maxRecognitionTimes = 30)` | `Action<FaceVerifyResult>` | 人脸验证 |
|
|
| `AutoVerify(bool enable, byte timeout, Action<FaceVerifyResult> success, Action<string> error)` | `Action<FaceVerifyResult>` | 启用或关闭自动验证 |
|
|
| `Enroll(bool admin, string userName, FaceDirection direction, byte timeout, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | 交互式录入 |
|
|
| `EnrollSingle(bool admin, string userName, byte timeout, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | 单帧录入 |
|
|
| `EnrollIntegrated(bool admin, string userName, FaceDirection direction, byte timeout, bool singleFrame, bool duplicateCheck, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | 集成式录入 |
|
|
| `EnrollSnapFaceImage(bool admin, string userName, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | 抓拍人脸后注册 |
|
|
|
|
### 用户管理
|
|
|
|
| 方法 | 成功回调 | 说明 |
|
|
|---|---|---|
|
|
| `DeleteUser(int userId, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 删除指定用户 |
|
|
| `DeleteAll(Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 删除全部用户 |
|
|
| `GetUserInfo(int userId, Action<FaceUserInfo> success, Action<string> error)` | `Action<FaceUserInfo>` | 查询指定用户 |
|
|
| `GetAllUserIds(Action<List<int>> success, Action<string> error)` | `Action<List<int>>` | 查询全部用户 ID |
|
|
| `GetAllUserIds2(Action<List<int>> success, Action<string> error)` | `Action<List<int>>` | 使用扩展命令查询全部用户 ID |
|
|
| `GetAllUserInfos(Action<List<FaceUserInfo>> success, Action<string> error)` | `Action<List<FaceUserInfo>>` | 查询全部用户信息 |
|
|
| `GetAllUserInfos2(Action<List<FaceUserInfo>> success, Action<string> error)` | `Action<List<FaceUserInfo>>` | 使用扩展命令查询全部用户信息 |
|
|
|
|
### 二维码、图片与特征
|
|
|
|
| 方法 | 成功回调 | 说明 |
|
|
|---|---|---|
|
|
| `ScanQrCode(byte timeout, Action<string> success, Action<string> error)` | `Action<string>` | 扫描二维码 |
|
|
| `SnapUploadImage(Action<FaceImageResult> success, Action<string> error)` | `Action<FaceImageResult>` | 抓拍普通图片 |
|
|
| `SnapUploadFaceImage(Action<FaceImageResult> success, Action<string> error)` | `Action<FaceImageResult>` | 抓拍人脸图片 |
|
|
| `SnapUploadLargeImage(ImageDpi dpi, Action<FaceImageResult> success, Action<string> error)` | `Action<FaceImageResult>` | 抓拍大图 |
|
|
| `EnrollWithPhoto(byte[] photoBytes, BioType type, string userName, bool duplicateCheck, Action<FaceEnrollResult> success, Action<string> error, Action<int, int> progress = null)` | `Action<FaceEnrollResult>` | 照片注册 |
|
|
| `EnrollWithPhotoAndId(int userId, byte[] photoBytes, BioType type, string userName, bool duplicateCheck, Action<FaceEnrollResult> success, Action<string> error, Action<int, int> progress = null)` | `Action<FaceEnrollResult>` | 指定用户 ID 照片注册 |
|
|
| `ReadFeature(int userId, FeatureType type, Action<byte[]> success, Action<string> error)` | `Action<byte[]>` | 读取用户特征 |
|
|
| `WriteFeature(byte[] featureBytes, FeatureType type, string userName, Action<FaceEnrollResult> success, Action<string> error, Action<int, int> progress = null)` | `Action<FaceEnrollResult>` | 写入特征并注册 |
|
|
|
|
### UVC 与加密
|
|
|
|
| 方法 | 成功回调 | 说明 |
|
|
|---|---|---|
|
|
| `ReadUsbUvcParameters(Action<UsbUvcParameters> success, Action<string> error)` | `Action<UsbUvcParameters>` | 读取 USB/UVC 参数 |
|
|
| `SetUsbUvcParameters(UsbUvcParameters parameters, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置 USB/UVC 参数 |
|
|
| `SetFaceLocationDisplay(bool visible, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置人脸框显示 |
|
|
| `SetRgbLevel(byte level, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置 RGB 等级 |
|
|
| `SetDuplicateCheck(bool enableCheck, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置查重 |
|
|
| `ReadDuplicateCheck(Action<bool> success, Action<string> error)` | `Action<bool>` | 读取查重状态 |
|
|
| `SetReleaseEncryptionKey(byte[] key16, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置 Release 加密密钥 |
|
|
| `SetDebugEncryptionKey(byte[] key16, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置 Debug 加密密钥 |
|
|
| `InitEncryption(byte[] seed4, byte mode, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 初始化加密 |
|
|
| `EnableEncryption(IFaceModuleCrypto crypto, Action success, Action<string> error)` | `Action` | 启用本地加密算法适配器 |
|
|
| `DisableEncryption(Action success, Action<string> error)` | `Action` | 关闭本地加密算法适配器 |
|
|
|
|
## 主要模型
|
|
|
|
| 类型 | 说明 |
|
|
|---|---|
|
|
| `FaceReply` | REPLY 包解析结果 |
|
|
| `FaceNote` | NOTE 包解析结果 |
|
|
| `FaceFaceStateNote` | 人脸状态 NOTE |
|
|
| `FaceUserInfo` | 用户 ID、姓名、管理员标记 |
|
|
| `FaceVerifyResult` | 验证结果、用户信息、开锁状态 |
|
|
| `FaceEnrollResult` | 录入结果、用户 ID、方向 |
|
|
| `FaceImageResult` | 图片 bytes、`Texture2D`、用户 ID |
|
|
| `UsbUvcParameters` | USB/UVC 参数 |
|
|
| `FaceCommandException` | 命令 REPLY 非成功时抛出的异常 |
|