湖州网站建设网站建设策划

USB Manager 模块

目录

1. 模块概述
   • 1.1 功能与目标
   • 1.2 系统位置
   • 1.3 设计思路与模式
   • 1.4 系统框图
2. 模块结构
   • 2.1 源文件与头文件
   • 2.2 类、结构体、函数与方法
   • 2.3 类图
   • 2.4 模块内部依赖框图
3. 模块间交互
   • 3.1 交互描述
   • 3.2 外部依赖框图
4. 状态机转换图
   • 4.1 状态机模型
   • 4.2 状态机树图
   • 4.3 状态机切换规则
   • 4.4 状态机转换图
5. 接口设计
   • 5.1 公共接口
   • 5.2 数据交换接口
   • 5.3 接口调用时序图

1. 模块概述

源码：https://gitee.com/openharmony/usb_usb_manager

1.1 功能与目标

主要功能

USB Manager 是 OpenHarmony 系统中的 USB 服务管理模块，提供完整的 USB 设备管理能力，主要功能包括：

设计目标

1. 统一管理: 提供统一的USB设备管理接口，屏蔽底层HAL差异
2. 权限控制: 实现细粒度的USB设备访问权限控制
3. 事件驱动: 支持USB设备热插拔事件的实时通知
4. 多模式支持: 同时支持Host模式和Device模式
5. 可扩展性: 模块化设计，便于功能扩展

使用场景

• 移动设备连接USB外设（键盘、鼠标、U盘等）
• 设备作为USB从设备连接PC进行数据传输
• USB调试模式（HDC）
• 串口通信应用
• 配件模式连接

1.2 系统位置

USB Manager 在 OpenHarmony 系统中的位置如下：

┌─────────────────────────────────────────────────────────────┐ │ 应用层 (Application) │ │ JS/TS/ETS 应用程序 │ ├─────────────────────────────────────────────────────────────┤ │ 框架层 (Framework) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ USB API (NAPI) │ │ │ │ @ohos.usbManager 接口 │ │ │ └─────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 服务层 (Service) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ ★ USB Manager Service ★ │ │ │ │ ┌──────────┬──────────┬──────────┬──────────────┐ │ │ │ │ │ Host │ Device │ Port │ Serial │ │ │ │ │ │ Manager │ Manager │ Manager │ Manager │ │ │ │ │ └──────────┴──────────┴──────────┴──────────────┘ │ │ │ │ ┌──────────────────┬──────────────────────────┐ │ │ │ │ │ Right Manager │ Accessory Manager │ │ │ │ │ └──────────────────┴──────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ HAL层 (Hardware Abstraction) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ USB HAL │ │ │ │ IUsbInterface / ISerialInterface │ │ │ └─────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 内核层 (Kernel) │ │ Linux USB Driver │ └─────────────────────────────────────────────────────────────┘

模块性质

• 类型: 核心系统服务模块
• SA ID: 4201 (USB_SYSTEM_ABILITY_ID)
• 运行方式: 系统能力（SystemAbility）
• 进程模型: 独立进程运行

与其他模块的关系

1.3 设计思路与模式

设计思路

1. 分层架构设计

   • API层：提供NAPI接口供JS/TS应用调用
   • Service层：实现核心业务逻辑
   • HAL层：封装硬件抽象层接口

2. 模块化设计

   • 按功能划分为Host、Device、Port、Serial等子管理器
   • 各子模块职责单一，便于维护和扩展

3. 事件驱动机制

   • 通过订阅者模式接收HAL层的设备事件
   • 使用公共事件服务广播设备状态变化

4. 权限控制机制

   • 基于数据库的权限持久化存储
   • 支持临时权限和永久权限
   • 集成系统权限框架

设计模式

1.4 系统框图

┌────────────────────────────────────────────────────────────────────────┐ │ USB API │ │ ┌────────────────────────┬─────────────────────┬──────────────────┐ │ │ │ USB FUNCTION │ USB INTERFACE │ USB ENUM │ │ │ │ • getDevices │ • USBEndpoint │ • PowerRoleType │ │ │ │ • connectDevice │ • USBInterface │ • DataRoleType │ │ │ │ • hasRight │ • USBConfig │ • PortModeType │ │ │ │ • requestRight │ • USBDevice │ • USBPortStatus │ │ │ │ • claimInterface │ • USBDevicePipe │ • FunctionType │ │ │ │ • bulkTransfer │ • USBPort │ │ │ │ │ • controlTransfer │ • USBControlParams │ │ │ │ └────────────────────────┴─────────────────────┴──────────────────┘ │ └────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ USB SERVICE │ │ ┌──────────────────┬──────────────────┬──────────────────────────┐ │ │ │ HOST │ DEVICE │ PORT │ │ │ │ ┌────────────┐ │ ┌────────────┐ │ ┌──────────────────┐ │ │ │ │ │ Right │ │ │ Function │ │ │ Status │ │ │ │ │ │ Manager │ │ │ Manager │ │ │ Manager │ │ │ │ │ └────────────┘ │ └────────────┘ │ └──────────────────┘ │ │ │ │ ┌────────────┐ │ ┌────────────┐ │ ┌──────────────────┐ │ │ │ │ │ Device │ │ │ Device │ │ │ Role │ │ │ │ │ │ Manager │ │ │ Manager │ │ │ Manager │ │ │ │ │ └────────────┘ │ └────────────┘ │ └──────────────────┘ │ │ │ └──────────────────┴──────────────────┴──────────────────────────┘ │ └────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ USB HAL │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ HAL (INTERFACE IUsbInterface) │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ ┌──────────────────────────┬─────────────────────────────────────┐ │ │ │ HOST DDK │ DEVICE DDK │ │ │ └──────────────────────────┴─────────────────────────────────────┘ │ └────────────────────────────────────────────────────────────────────────┘

2. 模块结构

2.1 源文件与头文件

2.1.1 服务层核心文件 (services/native/)

2.1.2 接口层文件 (interfaces/innerkits/native/)

2.1.3 IDL接口文件 (interfaces/innerkits/)

2.1.4 工具类文件 (utils/native/)

2.2 类、结构体、函数与方法

2.2.1 核心类

UsbService 类

classUsbService:publicSystemAbility,publicUsbServerStub{DECLARE_SYSTEM_ABILITY(UsbService)DECLARE_DELAYED_SP_SINGLETON(UsbService);public:// 生命周期管理voidOnStart()override;voidOnStop()override;// Host功能接口int32_tOpenDevice(uint8_tbusNum,uint8_tdevAddr);int32_tClose(uint8_tbusNum,uint8_tdevAddr);int32_tGetDevices(std::vector<UsbDevice>&deviceList);int32_tClaimInterface(uint8_tbusNum,uint8_tdevAddr,uint8_tinterfaceid,uint8_tforce);int32_tReleaseInterface(uint8_tbusNum,uint8_tdevAddr,uint8_tinterfaceid);int32_tBulkTransferRead(...);int32_tBulkTransferWrite(...);int32_tControlTransfer(...);// Device功能接口int32_tGetCurrentFunctions(int32_t&funcs);int32_tSetCurrentFunctions(int32_tfuncs);// Port功能接口int32_tGetPorts(std::vector<UsbPort>&ports);int32_tSetPortRole(int32_tportId,int32_tpowerRole,int32_tdataRole);// 权限管理接口boolHasRight(conststd::string&deviceName);int32_tRequestRight(conststd::string&deviceName);int32_tRemoveRight(conststd::string&deviceName);// Serial功能接口int32_tSerialOpen(int32_tportId,constsptr<IRemoteObject>&serialRemote);int32_tSerialClose(int32_tportId);int32_tSerialRead(...);int32_tSerialWrite(...);private:std::shared_ptr<UsbHostManager>usbHostManager_;std::shared_ptr<UsbDeviceManager>usbDeviceManager_;std::shared_ptr<UsbPortManager>usbPortManager_;std::shared_ptr<UsbRightManager>usbRightManager_;std::shared_ptr<UsbAccessoryManager>usbAccessoryManager_;std::shared_ptr<SERIAL::SerialManager>usbSerialManager_;sptr<HDI::Usb::V1_2::IUsbInterface>usbd_;};

UsbHostManager 类

classUsbHostManager{public:explicitUsbHostManager(SystemAbility*systemAbility);~UsbHostManager();// 设备管理voidGetDevices(MAP_STR_DEVICE&devices);boolAddDevice(UsbDevice*dev);boolDelDevice(uint8_tbusNum,uint8_tdevNum);// 设备操作int32_tOpenDevice(uint8_tbusNum,uint8_tdevAddr);int32_tClose(uint8_tbusNum,uint8_tdevAddr);int32_tResetDevice(uint8_tbusNum,uint8_tdevAddr);// 接口操作int32_tClaimInterface(uint8_tbusNum,uint8_tdevAddr,uint8_tinterfaceid,uint8_tforce);int32_tReleaseInterface(uint8_tbusNum,uint8_tdevAddr,uint8_tinterface);int32_tSetInterface(uint8_tbusNum,uint8_tdevAddr,uint8_tinterfaceid,uint8_taltIndex);// 数据传输int32_tBulkTransferRead(...);int32_tBulkTransferWrite(...);int32_tControlTransfer(...);int32_tRequestQueue(...);int32_tRequestWait(...);// 策略执行voidExecuteStrategy(UsbDevice*devInfo);int32_tManageGlobalInterface(booldisable);int32_tManageDevice(int32_tvendorId,int32_tproductId,booldisable);private:MAP_STR_DEVICE devices_;SystemAbility*systemAbility_;std::mutex mutex_;sptr<HDI::Usb::V1_2::IUsbInterface>usbd_;};

UsbDeviceManager 类

classUsbDeviceManager{public:UsbDeviceManager();int32_tInit();// Function管理staticuint32_tConvertFromString(std::string_view funcs);staticstd::stringConvertToString(uint32_tfunc);staticboolIsSettableFunctions(int32_tfuncs);voidUpdateFunctions(int32_tfunc);int32_tGetCurrentFunctions();int32_tGetCurrentFunctions(int32_t&funcs);int32_tSetCurrentFunctions(int32_tfuncs);// 事件处理voidHandleEvent(int32_tstatus);voidSetPhyConnectState(boolphyConnect);boolIsGadgetConnected(void);// 调试接口voidDump(int32_tfd,conststd::vector<std::string>&args);private:int32_tcurrentFunctions_;boolconnected_;boolgadgetConnected_;sptr<HDI::Usb::V1_0::IUsbInterface>usbd_;std::mutex functionMutex_;};

UsbPortManager 类

classUsbPortManager{public:UsbPortManager();~UsbPortManager();voidInit();// 端口查询int32_tGetPorts(std::vector<UsbPort>&ports);int32_tGetSupportedModes(int32_tportId,int32_t&supportedModes);int32_tQueryPort();// 端口设置int32_tSetPortRole(int32_tportId,int32_tpowerRole,int32_tdataRole);voidUpdatePort(int32_tportId,int32_tpowerRole,int32_tdataRole,int32_tmode);voidAddPort(UsbPort&port);voidRemovePort(int32_tportId);private:std::mutex mutex_;std::map<int32_t,UsbPort>portMap_;std::map<int32_t,int32_t>supportedModeMap_;sptr<HDI::Usb::V1_0::IUsbInterface>usbd_;};

UsbRightManager 类

classUsbRightManager{public:int32_tInit();// 权限查询boolHasRight(conststd::string&deviceName,conststd::string&bundleName,conststd::string&tokenId,constint32_t&userId);// 权限申请int32_tRequestRight(conststd::string&busDev,conststd::string&deviceName,conststd::string&bundleName,conststd::string&tokenId,constint32_t&userId);// 权限管理boolAddDeviceRight(conststd::string&deviceName,conststd::string&bundleName,conststd::string&tokenId,constint32_t&userId);boolRemoveDeviceRight(conststd::string&deviceName,conststd::string&bundleName,conststd::string&tokenId,constint32_t&userId);int32_tCancelDeviceRight(...);boolRemoveDeviceAllRight(conststd::string&deviceName);// 权限清理int32_tCleanUpRightExpired(std::vector<std::string>&devices);staticint32_tCleanUpRightUserDeleted(int32_t&totalUsers,int32_t&deleteUsers);staticint32_tCleanUpRightAppUninstalled(int32_tuid,conststd::string&bundleName);// 权限校验boolIsSystemAppOrSa();boolVerifyPermission();int32_tHasSetFuncRight(int32_tfunctions);private:std::mutex dialogRunning_;sptr<UsbAbilityConn>usbAbilityConn_;};

2.2.2 核心数据结构

UsbDevice 结构

classUsbDevice:publicParcelable{public:// 构造函数UsbDevice(std::string name,std::string manufacturerName,std::string productName,std::string version,uint8_tdevAddr,uint8_tbusNum,int32_tvendorId,int32_tproductId,int32_tbaseClass,int32_tsubClass,int32_tprotocol,std::vector<USBConfig>configs);// 序列化接口boolMarshalling(Parcel&parcel)constoverride;staticUsbDevice*Unmarshalling(Parcel&data);// 属性访问器conststd::string&GetName()const;conststd::string&GetManufacturerName()const;conststd::string&GetProductName()const;int32_tGetVendorId()const;int32_tGetProductId()const;int32_tGetClass()const;uint8_tGetBusNum()const;uint8_tGetDevAddr()const;std::vector<USBConfig>&GetConfigs();private:std::string name_;std::string manufacturerName_;std::string productName_;std::string version_;std::string serial_;uint8_tdevAddr_;uint8_tbusNum_;int32_tvendorId_;int32_tproductId_;int32_tbaseClass_;int32_tsubClass_;int32_tprotocol_;std::vector<USBConfig>configs_;};

UsbPort 结构

structUsbPortStatus{int32_tcurrentMode;// 当前模式int32_tcurrentPowerRole;// 当前电源角色int32_tcurrentDataRole;// 当前数据角色};structUsbPort:publicParcelable{int32_tid;// 端口IDint32_tsupportedModes;// 支持的模式UsbPortStatus usbPortStatus;// 端口状态boolMarshalling(Parcel&parcel)constoverride;staticUsbPort*Unmarshalling(Parcel&data);};

错误码枚举

enumUsbErrCode{UEC_OK=0,// 接口层错误UEC_INTERFACE_NO_MEMORY,UEC_INTERFACE_INVALID_OPERATION,UEC_INTERFACE_INVALID_VALUE,UEC_INTERFACE_PERMISSION_DENIED,// 服务层错误UEC_SERVICE_NO_MEMORY,UEC_SERVICE_INVALID_OPERATION,UEC_SERVICE_INVALID_VALUE,UEC_SERVICE_PERMISSION_DENIED,UEC_SERVICE_PERMISSION_DENIED_SYSAPI,// 串口错误UEC_SERIAL_PORT_REPEAT_OPEN,UEC_SERIAL_PORT_REPEAT_CLOSE,UEC_SERIAL_PORT_NOT_OPEN,UEC_SERIAL_IO_EXCEPTION,};

2.3 类图

2.4 模块内部依赖框图