1# @ohos.driver.deviceManager (外设管理) 2 3本模块主要提供管理外部设备的相关功能，包括查询设备列表、绑定设备和解除绑定设备。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import { deviceManager } from '@kit.DriverDevelopmentKit'; 13``` 14 15## deviceManager.queryDevices 16 17queryDevices(busType?: number): Array<Readonly<Device>> 18 19获取接入主设备的外部设备列表。如果没有设备接入，那么将会返回一个空的列表。 20 21**需要权限：** ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 22 23**系统能力：** SystemCapability.Driver.ExternalDevice 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ------- | ------ | ---- | ------------------------------------ | 29| busType | number | 否 | 设备总线类型，不填则查找所有类型设备。 | 30 31**返回值：** 32 33| 类型 | 说明 | 34| ---------------------------------------------- | -------------- | 35| Array<Readonly<[Device](#device)>> | 设备信息列表。 | 36 37**错误码：** 38 39| 错误码ID | 错误信息 | 40| -------- | ---------------------------------------- | 41| 201 | The permission check failed. | 42| 22900001 | ExternalDeviceManager service exception or busType parameter error. | 43 44**示例：** 45 46```ts 47import { deviceManager } from '@kit.DriverDevelopmentKit'; 48 49try { 50 let devices : Array<deviceManager.Device> = deviceManager.queryDevices(deviceManager.BusType.USB); 51 for (let item of devices) { 52 let device : deviceManager.USBDevice = item as deviceManager.USBDevice; 53 console.info(`Device id is ${device.deviceId}`) 54 } 55} catch (error) { 56 console.error(`Failed to query device. Code is ${error.code}, message is ${error.message}`); 57} 58``` 59 60## deviceManager.bindDevice 61 62bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>, 63 callback: AsyncCallback<{deviceId: number; remote: rpc.IRemoteObject;}>): void 64 65根据queryDevices()返回的设备信息绑定设备。 66 67需要调用[deviceManager.queryDevices()](#devicemanagerquerydevices)获取设备信息以及device。 68 69**需要权限：** ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 70 71**系统能力：** SystemCapability.Driver.ExternalDevice 72 73**参数：** 74 75| 参数名 | 类型 | 必填 | 说明 | 76| ------------ | ---------------------------------------------------------------------------------------------------- | ---- | -------------------------------------- | 77| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 78| onDisconnect | AsyncCallback<number> | 是 | 绑定设备断开的回调。 | 79| callback | AsyncCallback<{deviceId: number; remote: [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject);}> | 是 | 绑定设备的回调，返回绑定设备的通信对象。 | 80 81**错误码：** 82 83| 错误码ID | 错误信息 | 84| -------- | ---------------------------------------- | 85| 201 | The permission check failed. | 86| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 87| 22900001 | ExternalDeviceManager service exception. | 88 89**示例：** 90 91```ts 92import { deviceManager } from '@kit.DriverDevelopmentKit'; 93import { BusinessError } from '@kit.BasicServicesKit'; 94import { rpc } from '@kit.IPCKit'; 95 96interface DataType { 97 deviceId : number; 98 remote : rpc.IRemoteObject; 99} 100 101try { 102 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 103 deviceManager.bindDevice(12345678, (error : BusinessError, data : number) => { 104 console.error(`Device is disconnected`); 105 }, (error : BusinessError, data : DataType) => { 106 if (error) { 107 console.error(`bindDevice async fail. Code is ${error.code}, message is ${error.message}`); 108 return; 109 } 110 console.info(`bindDevice success`); 111 }); 112} catch (error) { 113 console.error(`bindDevice fail. Code is ${error.code}, message is ${error.message}`); 114} 115``` 116 117## deviceManager.bindDeviceDriver<sup>11+</sup> 118bindDeviceDriver(deviceId: number, onDisconnect: AsyncCallback<number>, 119 callback: AsyncCallback<RemoteDeviceDriver>): void 120 121根据queryDevices()返回的设备信息绑定设备。 122 123需要调用[deviceManager.queryDevices()](#devicemanagerquerydevices)获取设备信息以及device。 124 125**需要权限：** ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 126 127**系统能力：** SystemCapability.Driver.ExternalDevice 128 129**参数：** 130 131| 参数名 | 类型 | 必填 | 说明 | 132| ------------ | --------------------------- | ---- | ---------------------------- | 133| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 134| onDisconnect | AsyncCallback<number> | 是 | 绑定设备断开的回调。 | 135| callback | AsyncCallback<RemoteDeviceDriver>| 是 | 指示绑定结果，包括设备 ID 和远程对象。 | 136 137**错误码：** 138 139| 错误码ID | 错误信息 | 140| -------- | ---------------------------------------- | 141| 201 | The permission check failed. | 142| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 143| 22900001 | ExternalDeviceManager service exception. | 144 145**示例：** 146 147```ts 148import { deviceManager } from '@kit.DriverDevelopmentKit'; 149import { BusinessError } from '@kit.BasicServicesKit'; 150import { rpc } from '@kit.IPCKit'; 151 152try { 153 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 154 deviceManager.bindDeviceDriver(12345678, (error : BusinessError, data : number) => { 155 console.error(`Device is disconnected`); 156 }, (error : BusinessError, data : deviceManager.RemoteDeviceDriver) => { 157 if (error) { 158 console.error(`bindDeviceDriver async fail. Code is ${error.code}, message is ${error.message}`); 159 return; 160 } 161 console.info(`bindDeviceDriver success`); 162 }); 163} catch (error) { 164 console.error(`bindDeviceDriver fail. Code is ${error.code}, message is ${error.message}`); 165} 166``` 167 168## deviceManager.bindDevice 169 170bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<{deviceId: number; 171 remote: rpc.IRemoteObject;}>; 172 173根据queryDevices()返回的设备信息绑定设备。 174 175需要调用[deviceManager.queryDevices](#devicemanagerquerydevices)获取设备信息以及device。 176 177**需要权限：** ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 178 179**系统能力：** SystemCapability.Driver.ExternalDevice 180 181**参数：** 182 183| 参数名 | 类型 | 必填 | 说明 | 184| ------------ | --------------------------- | ---- | ---------------------------- | 185| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 186| onDisconnect | AsyncCallback<number> | 是 | 绑定设备断开的回调。 | 187 188**返回值：** 189 190| 类型 | 说明 | 191| ---------------------------------------------------------------------------------------------- | -------------------------------------------- | 192| Promise<{deviceId: number; remote: [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject);}> | Promise对象，返回设备ID和IRemoteObject对象。 | 193 194**错误码：** 195 196| 错误码ID | 错误信息 | 197| -------- | ---------------------------------------- | 198| 201 | The permission check failed. | 199| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 200| 22900001 | ExternalDeviceManager service exception. | 201 202**示例：** 203 204```ts 205import { deviceManager } from '@kit.DriverDevelopmentKit'; 206import { BusinessError } from '@kit.BasicServicesKit'; 207 208try { 209 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 210 deviceManager.bindDevice(12345678, (error : BusinessError, data : number) => { 211 console.error(`Device is disconnected`); 212 }).then(data => { 213 console.info(`bindDevice success, Device_Id is ${data.deviceId}. 214 remote is ${data.remote != null ? data.remote.getDescriptor() : "null"}`); 215 }, (error: BusinessError) => { 216 console.error(`bindDevice async fail. Code is ${error.code}, message is ${error.message}`); 217 }); 218} catch (error) { 219 console.error(`bindDevice fail. Code is ${error.code}, message is ${error.message}`); 220} 221``` 222## deviceManager.bindDeviceDriver<sup>11+</sup> 223 224bindDeviceDriver(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<RemoteDeviceDriver>; 225 226根据queryDevices()返回的设备信息绑定设备。 227 228需要调用[deviceManager.queryDevices](#devicemanagerquerydevices)获取设备信息以及device。 229 230**需要权限：** ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 231 232**系统能力：** SystemCapability.Driver.ExternalDevice 233 234**参数：** 235 236| 参数名 | 类型 | 必填 | 说明 | 237| ------------ | --------------------------- | ---- | ---------------------------- | 238| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 239| onDisconnect | AsyncCallback<number> | 是 | 绑定设备断开的回调。 | 240 241**返回值：** 242 243| 类型 | 说明 | 244| --------------------------------- | -----------------------------------------| 245| Promise<RemoteDeviceDriver> | Promise对象，返回RemoteDeviceDriver对象。 | 246 247**错误码：** 248 249| 错误码ID | 错误信息 | 250| -------- | ---------------------------------------- | 251| 201 | The permission check failed. | 252| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 253| 22900001 | ExternalDeviceManager service exception. | 254 255**示例：** 256 257```ts 258import { deviceManager } from '@kit.DriverDevelopmentKit'; 259import { BusinessError } from '@kit.BasicServicesKit'; 260 261try { 262 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 263 deviceManager.bindDeviceDriver(12345678, (error : BusinessError, data : number) => { 264 console.error(`Device is disconnected`); 265 }).then((data: deviceManager.RemoteDeviceDriver) => { 266 console.info(`bindDeviceDriver success, Device_Id is ${data.deviceId}. 267 remote is ${data.remote != null ? data.remote.getDescriptor() : "null"}`); 268 }, (error: BusinessError) => { 269 console.error(`bindDeviceDriver async fail. Code is ${error.code}, message is ${error.message}`); 270 }); 271} catch (error) { 272 console.error(`bindDeviceDriver fail. Code is ${error.code}, message is ${error.message}`); 273} 274``` 275 276## deviceManager.unbindDevice 277 278unbindDevice(deviceId: number, callback: AsyncCallback<number>): void 279 280解除设备绑定。 281 282**需要权限**：ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 283 284**系统能力：** SystemCapability.Driver.ExternalDevice 285 286**参数：** 287 288| 参数名 | 类型 | 必填 | 说明 | 289| -------- | --------------------------- | ---- | ------------------------------ | 290| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 291| callback | AsyncCallback<number> | 是 | 解绑完成的回调。 | 292 293**错误码：** 294 295| 错误码ID | 错误信息 | 296| -------- | ---------------------------------------- | 297| 201 | The permission check failed. | 298| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 299| 22900001 | ExternalDeviceManager service exception. | 300 301**示例：** 302 303```ts 304import { deviceManager } from '@kit.DriverDevelopmentKit'; 305import { BusinessError } from '@kit.BasicServicesKit'; 306 307try { 308 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 309 deviceManager.unbindDevice(12345678, (error : BusinessError, data : number) => { 310 if (error) { 311 console.error(`unbindDevice async fail. Code is ${error.code}, message is ${error.message}`); 312 return; 313 } 314 console.info(`unbindDevice success`); 315 }); 316} catch (error) { 317 console.error(`unbindDevice fail. Code is ${error.code}, message is ${error.message}`); 318} 319``` 320## deviceManager.unbindDevice 321 322unbindDevice(deviceId: number): Promise<number> 323 324解除设备绑定。 325 326**需要权限**：ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 327 328**系统能力：** SystemCapability.Driver.ExternalDevice 329 330**参数：** 331 332| 参数名 | 类型 | 必填 | 说明 | 333| -------- | ------ | ---- | ------------------------------ | 334| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 335 336**错误码：** 337 338| 错误码ID | 错误信息 | 339| -------- | ---------------------------------------- | 340| 201 | The permission check failed. | 341| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 342| 22900001 | ExternalDeviceManager service exception. | 343 344**返回值：** 345 346| 类型 | 说明 | 347| --------------------- | ------------------------- | 348| Promise<number> | Promise对象，返回设备ID。 | 349 350**示例：** 351 352```ts 353import { deviceManager } from '@kit.DriverDevelopmentKit'; 354import { BusinessError } from '@kit.BasicServicesKit'; 355 356try { 357 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 358 deviceManager.unbindDevice(12345678).then((data : number) => { 359 console.info(`unbindDevice success, Device_Id is ${data}.`); 360 }, (error : BusinessError) => { 361 console.error(`unbindDevice async fail. Code is ${error.code}, message is ${error.message}`); 362 }); 363} catch (error) { 364 console.error(`unbindDevice fail. Code is ${error.code}, message is ${error.message}`); 365} 366``` 367 368## Device 369 370外设信息。 371 372**系统能力：** SystemCapability.Driver.ExternalDevice 373 374| 名称 | 类型 | 必填 | 说明 | 375| ----------- | ------------------- | ---- | ---------- | 376| busType | [BusType](#bustype) | 是 | 总线类型。 | 377| deviceId | number | 是 | 设备ID。 | 378| description | string | 是 | 设备描述。 | 379 380## USBDevice 381 382USB设备信息，继承自[Device](#device)。 383 384**系统能力：** SystemCapability.Driver.ExternalDevice 385 386| 名称 | 类型 | 必填 | 说明 | 387| --------- | ------ | ---- | ------------------- | 388| vendorId | number | 是 | USB设备Vendor ID。 | 389| productId | number | 是 | USB设备Product ID。 | 390 391## BusType 392 393设备总线类型。 394 395**系统能力：** SystemCapability.Driver.ExternalDevice 396 397| 名称 | 值 | 说明 | 398| ---- | --- | ------------- | 399| USB | 1 | USB总线类型。 | 400 401## RemoteDeviceDriver<sup>11+</sup> 402 403远程设备驱动。 404 405**系统能力：** SystemCapability.Driver.ExternalDevice 406 407| 名称 | 类型 | 必填 | 说明 | 408| --------- | ------ | ---- | ------------------- | 409| deviceId<sup>11+</sup> | number | 是 | 设备ID。 | 410| remote<sup>11+</sup> | [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject) | 是 | 远程驱动程序对象。 |