HarmonyOS鸿蒙Next中串口工具类错误码封装？

HarmonyOS串口通信实现方案详解

一、效果描述

USBManager 类是 HarmonyOS 企业版中用于管理 USB 设备的核心工具类。它封装了完整的 USB 设备管理功能，包括：

a. 获取系统连接的所有 USB 设备列表 b. 管理 USB 设备操作权限（检查、申请、移除权限） c. 连接和断开 USB 设备 d. 配置 USB 设备参数（配置、接口等） e. 占用和释放 USB 接口 f. 获取设备相关信息（文件描述符、原始描述符）

通过该类，开发者可以方便地在应用中实现对 USB 设备的完整控制，无需直接调用底层 API，大大简化了 USB 设备管理的复杂度。

二、问题抛出

在 HarmonyOS 企业版应用开发中，直接使用原生 USB 管理 API 存在以下问题：

a. API 调用复杂：原生 API 分散在多个模块中，需要处理大量细节，增加了开发难度和出错概率。 b. 异常处理繁琐：每个 USB 操作都可能抛出多种类型的异常，需要针对不同错误码进行处理，代码冗长且容易遗漏。 c. 权限管理困难：USB 设备操作涉及复杂的权限检查和申请流程，手动处理容易出现逻辑漏洞。 d. 资源泄漏风险：USB 设备连接后需要正确关闭管道和释放接口，否则可能导致资源泄漏。 e. 缺乏统一接口：原生 API 功能分散，没有统一的调用入口，不利于代码维护和复用。 f. 调试困难：缺少详细的日志记录，出现问题时难以定位原因。

三、解决方案

为了解决上述问题，我们设计并实现了 USBManager 工具类，具体方案如下（具体方法实现官方文档都有现成实现代码（本代码涉及到隐私代码不一一展示全了））：

1. 封装统一接口

将所有 USB 相关操作封装在一个类中，提供简洁的方法签名：

export class USBManager {

  constructor(context: common.UIAbilityContext)

  // 设备发现
  getDevices(): Array<usbManager.USBDevice>

  // 权限管理
  hasRight(deviceName: string): boolean
  async requestRight(deviceName: string): Promise<boolean>
  removeRight(deviceName: string): boolean

  // 设备连接管理
  connectDevice(device: usbManager.USBDevice): usbManager.USBDevicePipe | null
  closePipe(pipe: usbManager.USBDevicePipe): number

  // 设备配置管理
  setConfiguration(pipe: usbManager.USBDevicePipe, config: usbManager.USBConfiguration): number
  setInterface(pipe: usbManager.USBDevicePipe, iface: usbManager.USBInterface): number

  // 接口管理
  claimInterface(pipe: usbManager.USBDevicePipe, iface: usbManager.USBInterface, force?: boolean): number
  releaseInterface(pipe: usbManager.USBDevicePipe, iface: usbManager.USBInterface): number

  // 信息获取
  getFileDescriptor(pipe: usbManager.USBDevicePipe): number
  getRawDescriptor(pipe: usbManager.USBDevicePipe): Uint8Array

}
//具体方法实现官方文档都有现成实现代码（本代码涉及到隐私代码不一一展示全了）

2. 统一异常处理机制

为每个方法添加完善的异常处理逻辑，自动识别并处理各种错误码：

try {
  // USB 操作
} catch (error) {
  if (error as BusinessError) {
    switch(error.code) {
      case 1001:
        // 权限错误处理
        break;
      case 1002:
        // 功能未启用错误处理
        break;
      // 其他错误码处理
      default:
        // 默认错误处理
    }
  } else {
    // 非业务错误处理
  }
}

常见的错误码及含义：

• 1001: 无权限访问
• 1002: USB功能未启用
• 1003: 设备不存在
• 1004: 设备忙
• 1005: 无效参数
• 1006: 接口已被占用

3. 自动权限检查

在需要权限的操作前自动检查权限状态，避免因权限不足导致操作失败：

connectDevice(device: usbManager.USBDevice): usbManager.USBDevicePipe | null {
  try {
    console.log(`尝试连接设备: ${device.name}`);
    // 自动检查权限
    if (!this.hasRight(device.name)) {
      console.warn(`没有设备${device.name}的访问权限`);
      return null;
    }
    // 执行连接操作
    const pipe = usbManager.connectDevice(device);
    return pipe;
  } catch (error) {
    // 异常处理
  }
}

4. 详尽的日志记录

为每个重要操作添加详细日志，便于调试和问题追踪：

console.log("正在获取USB设备列表");
console.log(`成功获取到 ${devices.length} 个USB设备`);
console.log(`设备 ${deviceName} 权限状态: ${result ? '已授权' : '未授权'}`);

5. 规范的返回值处理

统一返回值格式，明确成功/失败状态：

• 布尔值方法：true 表示成功，false 表示失败
• 数值方法：0 表示成功，其他值表示失败
• 对象方法：成功返回对象实例，失败返回 null 或空数组

6. 完善的文档注释

为每个方法添加详细的 JSDoc 注释，包含：

• 方法功能描述
• 参数说明
• 返回值说明
• 使用示例
• 可能的异常情况

/**
 * 获取系统所有连接的USB设备列表
 * @returns {Array<usbManager.USBDevice>} USB设备数组
 *
 * @example
 * const usbManager = new USBManager(context);
 * const devices = usbManager.getDevices();
 * if(devices.length > 0) {
 *   console.log(`找到${devices.length}个USB设备`);
 * }
 */
getDevices(): Array<usbManager.USBDevice> {
  // 实现代码
}

7. 使用示例

完整的使用示例如下：

// 初始化USB管理器
private usbManagerInstance: USBManager = new USBManager(this.context);

// 获取设备列表
const devices = this.usbManagerInstance.getDevices();

// 检查权限
const hasPermission = this.usbManagerInstance.hasRight(device.name);

// 请求权限
const granted = await this.usbManagerInstance.requestRight(device.name);

// 连接设备
const pipe = this.usbManagerInstance.connectDevice(device);

// 设置配置
const configResult = this.usbManagerInstance.setConfiguration(pipe, config);

// 声明接口
const interfaceResult = this.usbManagerInstance.claimInterface(pipe, interface);

// 释放接口
const releaseResult = this.usbManagerInstance.releaseInterface(pipe, interface);

// 关闭连接
const closeResult = this.usbManagerInstance.closePipe(pipe);

8. 完整的操作流程

推荐的USB设备操作流程如下：

a. 获取设备列表：[getDevices()] b. 检查权限：[hasRight()] c. 请求权限（如需要）：[requestRight()] d. 连接设备：[connectDevice()] e. 设置配置（如需要）：[setConfiguration()] f. 声明接口（如需要）：[claimInterface()] g. 进行数据传输或其他操作 h. 释放接口：[releaseInterface()] i. 关闭连接：[closePipe()]

通过以上方案，USBManager 类有效解决了原生 USB API 使用中的各种问题，提供了简洁、安全、可靠的 USB 设备管理接口，显著提升了开发效率和代码质量。

目前是已经支持Phone设备