@ohos.usbManager (USB管理)(系统接口)
本模块主要提供管理USB设备的相关功能,包括主设备上查询USB设备列表、批量数据传输、控制命令传输、权限控制等;从设备上端口管理、功能切换及查询等。
说明:
本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 当前页面仅包含本模块的系统接口,其他公开接口参见@ohos.usbManager (USB管理)。
导入模块
import usb from "@ohos.usbManager";
usb.addRight
addRight(bundleName: string, deviceName: string): boolean
添加软件包访问设备的权限。系统应用默认拥有访问设备权限,调用此接口不会产生影响。
usb.requestRight (#usbrequestright)会触发弹框请求用户授权;addRight不会触发弹框,而是直接添加软件包访问设备的权限。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
deviceName | string | 是 | 设备名称。 |
bundleName | string | 是 | 软件包名称。 |
返回值:
类型 | 说明 |
---|---|
boolean | 返回权限添加结果。返回true表示权限添加成功;返回false则表示权限添加失败。 |
示例:
let devicesName: string = "1-1";
let bundleName: string = "com.example.hello";
if (usb.addRight(bundleName, devicesName)) {
console.log(`Succeed in adding right`);
}
usb.usbFunctionsFromString
usbFunctionsFromString(funcs: string): number
在设备模式下,将字符串形式的USB功能列表转化为数字掩码。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
funcs | string | 是 | 字符串形式的功能列表。 |
返回值:
类型 | 说明 |
---|---|
number | 转化后的数字掩码。 |
示例:
let funcs: string = "acm";
let ret: number = usb.usbFunctionsFromString(funcs);
usb.usbFunctionsToString
usbFunctionsToString(funcs: FunctionType): string
在设备模式下,将数字掩码形式的USB功能列表转化为字符串。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
funcs | FunctionType | 是 | USB功能数字掩码。 |
返回值:
类型 | 说明 |
---|---|
string | 转化后的字符串形式的功能列表。 |
示例:
let funcs: number = usb.FunctionType.ACM | usb.FunctionType.ECM;
let ret: string = usb.usbFunctionsToString(funcs);
usb.setCurrentFunctions
setCurrentFunctions(funcs: FunctionType): Promise<void>
在设备模式下,设置当前的USB功能列表。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
funcs | FunctionType | 是 | USB功能数字掩码。 |
错误码:
以下错误码的详细介绍请参见USB服务错误码。
错误码ID | 错误信息 |
---|---|
14400002 | Permission denied.The HDC is disabled by the system. |
返回值:
类型 | 说明 |
---|---|
Promise<void> | Promise对象。 |
示例:
import {BusinessError} from '@ohos.base';
let funcs: number = usb.FunctionType.HDC;
usb.setCurrentFunctions(funcs).then(() => {
console.info('usb setCurrentFunctions successfully.');
}).catch((err: BusinessError) => {
console.error('usb setCurrentFunctions failed: ' + err.code + ' message: ' + err.message);
});
usb.getCurrentFunctions
getCurrentFunctions(): FunctionType
在设备模式下,获取当前的USB功能列表的数字组合掩码。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
返回值:
类型 | 说明 |
---|---|
FunctionType | 当前的USB功能列表的数字组合掩码。 |
示例:
let ret: number = usb.getCurrentFunctions();
usb.getPorts
getPorts(): Array<USBPort>
获取所有物理USB端口描述信息。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
返回值:
类型 | 说明 |
---|---|
Array<USBPort> | USB端口描述信息列表。 |
示例:
let ret: Array<usb.USBPort> = usb.getPorts();
usb.getSupportedModes
getSupportedModes(portId: number): PortModeType
获取指定的端口支持的模式列表的组合掩码。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
portId | number | 是 | 端口号。 |
返回值:
类型 | 说明 |
---|---|
PortModeType | 支持的模式列表的组合掩码。 |
示例:
let ret: number = usb.getSupportedModes(0);
usb.setPortRoles
setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise<void>
设置指定的端口支持的角色模式,包含充电角色、数据传输角色。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
portId | number | 是 | 端口号。 |
powerRole | PowerRoleType | 是 | 充电的角色。 |
dataRole | DataRoleType | 是 | 数据传输的角色。 |
返回值:
类型 | 说明 |
---|---|
Promise<void> | Promise对象。 |
示例:
import {BusinessError} from '@ohos.base';
let portId: number = 1;
usb.setPortRoles(portId, usb.PowerRoleType.SOURCE, usb.DataRoleType.HOST).then(() => {
console.info('usb setPortRoles successfully.');
}).catch((err: BusinessError) => {
console.error('usb setPortRoles failed: ' + err.code + ' message: ' + err.message);
});
USBPort
USB设备端口。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
id | number | 是 | USB端口唯一标识。 |
supportedModes | PortModeType | 是 | USB端口所支持的模式的数字组合掩码。 |
status | USBPortStatus | 是 | USB端口角色。 |
USBPortStatus
USB设备端口角色信息。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
currentMode | number | 是 | 当前的USB模式。 |
currentPowerRole | number | 是 | 当前设备充电模式。 |
currentDataRole | number | 是 | 当前设备数据传输模式。 |
FunctionType
USB设备侧功能。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
名称 | 值 | 说明 |
---|---|---|
NONE | 0 | 没有功能。 |
ACM | 1 | acm功能。 |
ECM | 2 | ecm功能。 |
HDC | 4 | hdc功能。 |
MTP | 8 | 暂不支持。 |
PTP | 16 | 暂不支持。 |
RNDIS | 32 | 暂不支持。 |
MIDI | 64 | 暂不支持。 |
AUDIO_SOURCE | 128 | 暂不支持。 |
NCM | 256 | 暂不支持。 |
PortModeType
USB端口模式类型。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
名称 | 值 | 说明 |
---|---|---|
NONE | 0 | 无。 |
UFP | 1 | 数据上行,需要外部供电。 |
DFP | 2 | 数据下行,对外提供电源。 |
DRP | 3 | 既可以做DFP(Host),也可以做UFP(Device),当前不支持。 |
NUM_MODES | 4 | 当前不支持。 |
PowerRoleType
电源角色类型。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
名称 | 值 | 说明 |
---|---|---|
NONE | 0 | 无。 |
SOURCE | 1 | 外部供电。 |
SINK | 2 | 内部供电。 |
DataRoleType
数据角色类型。
系统接口: 此接口为系统接口。
系统能力: SystemCapability.USB.USBManager
名称 | 值 | 说明 |
---|---|---|
NONE | 0 | 无。 |
HOST | 1 | 主设备角色。 |
DEVICE | 2 | 从设备角色。 |