ch934x_serial/lib/ch934x_serial_platform_interface.dart

import 'dart:typed_data';

import 'package:plugin_platform_interface/plugin_platform_interface.dart';

import 'ch934x_serial_method_channel.dart';
import 'src/models/models.dart';

/// CH934X 插件的平台无关抽象接口。
///
/// Dart 侧应面向此接口编程,具体实现由 Android 平台
/// (MethodChannel) 提供;`set mockMethodCallHandler` 的
/// 单元测试可以替换该实现以验证上层逻辑。
abstract class Ch934xSerialPlatform extends PlatformInterface {
  /// 构造 [Ch934xSerialPlatform]。
  Ch934xSerialPlatform() : super(token: _token);

  static final Object _token = Object();

  static Ch934xSerialPlatform _instance = MethodChannelCh934xSerial();

  /// 平台无关实现当前持有的具体后端。
  static Ch934xSerialPlatform get instance => _instance;

  /// 替换具体实现,常用于单元测试。
  static set instance(Ch934xSerialPlatform instance) {
    PlatformInterface.verifyToken(instance, _token);
    _instance = instance;
  }

  // ---------------------------------------------------------------------------
  // 设备查找
  // ---------------------------------------------------------------------------

  /// 获取所有已连接的 CH934X 设备信息(对应 4.1.4 `getCH934XDeviceList`)。
  Future<List<Ch934xDeviceInfo>> getDeviceList();

  /// 获取指定设备的 CH934X 序列号(对应 4.1.1 `CH934XSerialNum`)。
  Future<String?> getSerialNumber(int deviceId);

  /// 获取指定设备类型(对应 4.1.2 `CH934XDeviceType`)。
  Future<int> getDeviceType(int deviceId);

  /// 获取指定设备的串口列表(对应 4.1.3 `getCH934XSerialPortList`)。
  Future<List<Ch934xSerialPortInfo>> getSerialPortList(
    int deviceId, {
    required int interfaceNumber,
  });

  // ---------------------------------------------------------------------------
  // 设备打开 / 关闭
  // ---------------------------------------------------------------------------

  /// 初始化并打开指定串口(对应 5.1.1 `UsbSerial.init`)。
  Future<bool> openPort(Ch934xPortTarget target);

  /// 关闭当前线程/会话最近一次打开的串口(对应 5.2.1 `UsbSerial.close`)。
  Future<bool> closePort();

  /// 切换当前活跃串口。
  ///
  /// 同一 UsbDevice 在调用 [openPort] 之后,所有串口都已连
  /// 接;此方法仅切换后续读写/GPIO/Modem 操作的目标串口,
  /// 不重复打开设备。返回是否切换成功。
  Future<bool> setActivePort(int serialPortIndex);

  /// 主动向系统申请指定设备的 USB 使用权限。
  ///
  /// 在用户未授权时弹出系统对话框,等待用户选择后返回结果。
  /// [openPort] 内部已自动处理权限申请,业务方通常无需手动
  /// 调用;仅在希望提前引导用户授权时使用。
  Future<bool> requestUsbPermission(int deviceId);

  // ---------------------------------------------------------------------------
  // 串口读写
  // ---------------------------------------------------------------------------

  /// 从串口读取数据(对应 6.1.1 `UsbSerial.read`)。
  /// [serialPortIndex] 可选，指定读取哪个端口的缓冲区；不传则读上次 setActivePort 设置的端口。
  Future<Uint8List> read(int length, {int? serialPortIndex});

  /// 向串口写入数据(对应 6.2.1 `UsbSerial.write`)。
  Future<int> write(Uint8List data);

  // ---------------------------------------------------------------------------
  // GPIO
  // ---------------------------------------------------------------------------

  /// 设置 GPIO 输出(对应 7.1.1 `UsbSerial.setGpioOutput`)。
  Future<bool> setGpioOutput({required int gpioNumber, required int level});

  /// 读取 GPIO 输入(对应 7.1.2 `UsbSerial.getGpioInput`)。
  Future<int> getGpioInput(int gpioNumber);

  // ---------------------------------------------------------------------------
  // Modem
  // ---------------------------------------------------------------------------

  /// 设置 Modem 控制(对应 7.2.1 `UsbSerial.setModemControl`)。
  Future<bool> setModemControl({required int dtr, required int rts});

  /// 获取 Modem 状态(对应 7.2.2 `UsbSerial.getModemStatus`)。
  Future<int> getModemStatus();

  // ---------------------------------------------------------------------------
  // 异常回调
  // ---------------------------------------------------------------------------

  /// 注册异常回调(对应 7.3.1 `UsbSerial.setExceptionCallback`)。
  ///
  /// 当原生层触发异常(例如设备拔出)时,会通过
  /// [onException] 中传入的回调通知调用方。
  Future<void> setExceptionCallback(
    void Function(Ch934xException exception) onException,
  );
}