idcard/lib/idcard.dart

import 'idcard_platform_interface.dart';

/// 身份证读卡器插件主类
/// 基于神思标准化接口规范实现的Flutter插件
class Idcard {
  /// 获取平台版本
  Future<String?> getPlatformVersion() {
    return IdcardPlatform.instance.getPlatformVersion();
  }

  /// 获取USB权限
  /// [vid] - USB设备的厂商ID，默认为0x261A（神思USB读卡器厂商ID）
  /// [pid] - USB设备的产品ID，默认为0x0011
  Future<int> getUsbPermission({int vid = 0x261A, int pid = 0x0011}) {
    return IdcardPlatform.instance.getUsbPermission(vid, pid);
  }

  /// 打开设备连接
  /// [portType] - 端口类型，支持"USB"、"COM"、"SKT"、"BTH"、"AUTO"
  /// [portPara] - 端口参数，根据端口类型不同而不同
  /// [extendPara] - 扩展参数
  /// 返回值：大于0表示成功（设备句柄），其他为失败
  Future<int> openDevice({String portType = 'USB', String portPara = '', String extendPara = ''}) {
    return IdcardPlatform.instance.openDevice(
      portType: portType,
      portPara: portPara,
      extendPara: extendPara,
    );
  }

  /// 设置当前设备（多设备操作）
  /// [devHandle] - 设备句柄
  /// 返回值：0表示成功；非0表示失败
  Future<int> setCurrentDevice(int devHandle) {
    return IdcardPlatform.instance.setCurrentDevice(devHandle);
  }

  /// 获取当前设备（多设备操作）
  /// 返回值：返回当前设备的句柄
  Future<int> getCurrentDevice() {
    return IdcardPlatform.instance.getCurrentDevice();
  }

  /// 获取接口库信息
  /// 返回值：包含version和description的Map
  Future<Map<String, String>> getLibraryInfo() {
    return IdcardPlatform.instance.getLibraryInfo();
  }

  /// 获取设备型号
  /// 返回值：设备型号字符串
  Future<String> getTerminalModel() {
    return IdcardPlatform.instance.getTerminalModel();
  }

  /// 设备轮询心跳
  /// 用于检测与读卡器是否已建立连接并且通讯正常
  /// 返回值：0表示成功；非0表示失败
  Future<int> terminalHeartBeat() {
    return IdcardPlatform.instance.terminalHeartBeat();
  }

  /// 获取接收数据
  /// 获取最后一次通讯收到的数据，一般用于获取读卡器协议层错误信息
  /// 返回值：最后一次通讯收到的数据
  Future<List<int>> getLastRecvData() {
    return IdcardPlatform.instance.getLastRecvData();
  }

  /// 获取设备固件版本
  /// 返回值：包含firmVersion和hardwareVersion的Map
  Future<Map<String, String>> getTerminalFirmVersion() {
    return IdcardPlatform.instance.getTerminalFirmVersion();
  }

  /// 获取设备序列号
  /// 返回值：设备序列号字符串
  Future<String> getTerminalSn() {
    return IdcardPlatform.instance.getTerminalSn();
  }

  /// 关闭设备连接
  /// 返回值：0表示成功；非0表示失败
  Future<int> closeDevice() {
    return IdcardPlatform.instance.closeDevice();
  }

  /// 寻找身份证卡片
  /// 返回值：大于0表示成功找到卡片，小于等于0表示错误码
  Future<int> findCard() {
    return IdcardPlatform.instance.findCard();
  }

  /// 选择身份证卡片
  /// 返回值：大于0表示成功选择卡片，小于等于0表示错误码
  Future<int> selectCard() {
    return IdcardPlatform.instance.selectCard();
  }

  /// 读取身份证（新版接口，支持多种证件类型）
  /// [cardType] - 读取卡类型：
  ///   0x00：读取二代证或外国人或港澳台
  ///   0x01：只读二代证
  ///   0x02：只读外国人
  ///   0x03：只读港澳台
  ///   0x10-0x13：对应上述类型但包含指纹信息
  /// [infoEncoding] - 返回信息的编码方式：
  ///   0x01：GB18030编码（GBK）
  ///   0x02：UTF16-LE编码
  ///   0x03：UTF-8编码
  /// [timeOut] - 读卡超时时间（毫秒），0表示不等待，>0表示等待放卡
  /// 返回值：包含result（错误码）和data（冒号分隔的身份证信息字符串）的Map
  Future<Map<String, dynamic>> idReadCard({int cardType = 0x00, int infoEncoding = 0x01, int timeOut = 30000}) {
    return IdcardPlatform.instance.idReadCard(
      cardType: cardType,
      infoEncoding: infoEncoding,
      timeOut: timeOut,
    );
  }

  /// 读取身份证原始数据（兼容旧版接口）
  /// [cardType] - 卡片类型，1表示身份证
  /// [infoEncoding] - 信息编码，0表示默认编码
  /// [timeOut] - 超时时间（毫秒），默认30秒
  /// 返回值：包含result（错误码）和data（原始数据）的Map
  Future<Map<String, dynamic>> readCard({int cardType = 1, int infoEncoding = 0, int timeOut = 30000}) {
    return IdcardPlatform.instance.readCard(
      cardType: cardType,
      infoEncoding: infoEncoding,
      timeOut: timeOut,
    );
  }

  /// 读取身份证详细信息
  /// 返回值：IdCardInfo对象，包含姓名、性别、民族等详细信息
  /// 抛出异常：如果读取失败会抛出Exception
  Future<IdCardInfo> readCardInfo() {
    return IdcardPlatform.instance.readCardInfo();
  }

  /// 读取追加住址
  /// 返回值：追加住址信息字符串
  Future<String> readNewAddress() {
    return IdcardPlatform.instance.readNewAddress();
  }

  /// 获取SAM模块状态
  /// 返回值：0表示成功；非0表示失败
  Future<int> getSamStatus() {
    return IdcardPlatform.instance.getSamStatus();
  }

  /// 获取SAM模块编号字符串
  /// 返回值：SAM模块编号字符串
  Future<String> getSamIdStr() {
    return IdcardPlatform.instance.getSamIdStr();
  }

  /// 完整的身份证读取流程
  /// 自动执行寻卡、选卡、读取信息的完整流程
  /// [timeOut] - 超时时间（毫秒），默认30秒
  /// [retryInterval] - 重试间隔时间（毫秒），默认500毫秒
  /// 返回值：IdCardInfo对象
  /// 抛出异常：如果超时或读取失败会抛出Exception
  Future<IdCardInfo> readCardComplete({int timeOut = 30000, int retryInterval = 500}) async {
    final startTime = DateTime.now().millisecondsSinceEpoch;
    
    while (true) {
      try {
        // 1. 寻卡
        int findResult = await findCard();
        print("寻卡结果：$findResult");
        
        if (findResult == 0) {
          // 2. 选卡
          int selectResult = await selectCard();
          print("选卡结果：$selectResult");
          
          if (selectResult == 0) {
            // 3. 读取信息
            return await readCardInfo();
          } else {
            print('选卡失败，错误码：$selectResult，继续重试...');
          }
        } else {
          print('寻卡失败，错误码：$findResult，继续重试...');
        }
      } catch (e) {
        print('读卡过程中发生异常：$e，继续重试...');
      }
      
      // 检查是否超时
      final currentTime = DateTime.now().millisecondsSinceEpoch;
      if (currentTime - startTime >= timeOut) {
        throw Exception('读卡超时，超时时间：$timeOut毫秒');
      }
      
      // 等待重试间隔
      await Future.delayed(Duration(milliseconds: retryInterval));
    }
  }

  /// 检查设备是否已连接
  /// 通过尝试获取平台版本来检查设备连接状态
  Future<bool> isDeviceConnected() async {
    try {
      final version = await getPlatformVersion();
      return version != null;
    } catch (e) {
      return false;
    }
  }
}