1# @ohos.driver.deviceManager (外设管理) 2<!--Kit: Driver Development Kit--> 3<!--Subsystem: Driver--> 4<!--Owner: @lixinsheng2--> 5<!--Designer: @w00373942--> 6<!--Tester: @dong-dongzhen--> 7<!--Adviser: @w_Machine_cc--> 8 9本模块主要提供管理外部设备的相关功能，包括查询设备列表、绑定设备和解除绑定设备。 10 11> **说明：** 12> 13> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```ts 18import { deviceManager } from '@kit.DriverDevelopmentKit'; 19``` 20 21## deviceManager.queryDevices 22 23queryDevices(busType?: number): Array<Readonly<Device>> 24 25获取接入主设备的外部设备列表。如果没有设备接入，那么将会返回一个空的列表。 26 27**需要权限：** ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 28 29**系统能力：** SystemCapability.Driver.ExternalDevice 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| ------- | ------ | ---- | ------------------------------------ | 35| busType | number | 否 | 设备总线类型，不填则查找所有类型设备。 | 36 37**返回值：** 38 39| 类型 | 说明 | 40| ---------------------------------------------- | -------------- | 41| Array<Readonly<[Device](#device)>> | 设备信息列表。 | 42 43**错误码：** 44 45以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[驱动错误码](errorcode-deviceManager.md)。 46 47| 错误码ID | 错误信息 | 48| -------- | ---------------------------------------- | 49| 201 | The permission check failed. | 50| 22900001 | ExternalDeviceManager service exception or busType parameter error. | 51 52**示例：** 53 54```ts 55import { deviceManager } from '@kit.DriverDevelopmentKit'; 56 57try { 58 let devices : Array<deviceManager.Device> = deviceManager.queryDevices(deviceManager.BusType.USB); 59 for (let item of devices) { 60 let device : deviceManager.USBDevice = item as deviceManager.USBDevice; 61 console.info(`Device id is ${device.deviceId}`); 62 } 63} catch (error) { 64 console.error(`Failed to query device. Code is ${error.code}, message is ${error.message}`); 65} 66``` 67 68## deviceManager.bindDevice<sup>(deprecated)</sup> 69 70bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>, 71 callback: AsyncCallback<{deviceId: number; remote: rpc.IRemoteObject;}>): void 72 73根据queryDevices()返回的设备信息绑定设备。 74 75需要调用[deviceManager.queryDevices()](#devicemanagerquerydevices)获取设备信息以及device。 76 77> **说明** 78> 从 API version 10开始支持，从API version 19开始废弃。建议使用[deviceManager.bindDriverWithDeviceId](#devicemanagerbinddriverwithdeviceid19)替代。 79 80**需要权限：** ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 81 82**系统能力：** SystemCapability.Driver.ExternalDevice 83 84**参数：** 85 86| 参数名 | 类型 | 必填 | 说明 | 87| ------------ | ---------------------------------------------------------------------------------------------------- | ---- | -------------------------------------- | 88| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 89| onDisconnect | AsyncCallback<number> | 是 | 绑定设备断开的回调。 | 90| callback | AsyncCallback<{deviceId: number; remote: [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject);}> | 是 | 绑定设备的回调，返回绑定设备的通信对象。 | 91 92**错误码：** 93 94以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[驱动错误码](errorcode-deviceManager.md)。 95 96| 错误码ID | 错误信息 | 97| -------- | ---------------------------------------- | 98| 201 | The permission check failed. | 99| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 100| 22900001 | ExternalDeviceManager service exception. | 101 102**示例：** 103 104```ts 105import { deviceManager } from '@kit.DriverDevelopmentKit'; 106import { BusinessError } from '@kit.BasicServicesKit'; 107import { rpc } from '@kit.IPCKit'; 108 109interface DataType { 110 deviceId : number; 111 remote : rpc.IRemoteObject; 112} 113 114try { 115 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 116 deviceManager.bindDevice(12345678, (error : BusinessError, data : number) => { 117 console.error(`Device is disconnected`); 118 }, (error : BusinessError, data : DataType) => { 119 if (error) { 120 console.error(`bindDevice async fail. Code is ${error.code}, message is ${error.message}`); 121 return; 122 } 123 console.info(`bindDevice success`); 124 }); 125} catch (error) { 126 console.error(`bindDevice fail. Code is ${error.code}, message is ${error.message}`); 127} 128``` 129 130## deviceManager.bindDeviceDriver<sup>(deprecated)</sup> 131bindDeviceDriver(deviceId: number, onDisconnect: AsyncCallback<number>, 132 callback: AsyncCallback<RemoteDeviceDriver>): void 133 134根据queryDevices()返回的设备信息绑定设备。 135 136需要调用[deviceManager.queryDevices()](#devicemanagerquerydevices)获取设备信息以及device。 137 138> **说明** 139> 从 API version 11开始支持，从API version 19开始废弃。建议使用[deviceManager.bindDriverWithDeviceId](#devicemanagerbinddriverwithdeviceid19)替代。 140 141**需要权限：** ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 142 143**系统能力：** SystemCapability.Driver.ExternalDevice 144 145**参数：** 146 147| 参数名 | 类型 | 必填 | 说明 | 148| ------------ | --------------------------- | ---- | ---------------------------- | 149| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 150| onDisconnect | AsyncCallback<number> | 是 | 绑定设备断开的回调。 | 151| callback | AsyncCallback<RemoteDeviceDriver>| 是 | 指示绑定结果，包括设备 ID 和远程对象。 | 152 153**错误码：** 154 155以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[驱动错误码](errorcode-deviceManager.md)。 156 157| 错误码ID | 错误信息 | 158| -------- | ---------------------------------------- | 159| 201 | The permission check failed. | 160| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 161| 22900001 | ExternalDeviceManager service exception. | 162 163**示例：** 164 165```ts 166import { deviceManager } from '@kit.DriverDevelopmentKit'; 167import { BusinessError } from '@kit.BasicServicesKit'; 168import { rpc } from '@kit.IPCKit'; 169 170try { 171 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 172 deviceManager.bindDeviceDriver(12345678, (error : BusinessError, data : number) => { 173 console.error(`Device is disconnected`); 174 }, (error : BusinessError, data : deviceManager.RemoteDeviceDriver) => { 175 if (error) { 176 console.error(`bindDeviceDriver async fail. Code is ${error.code}, message is ${error.message}`); 177 return; 178 } 179 console.info(`bindDeviceDriver success`); 180 }); 181} catch (error) { 182 console.error(`bindDeviceDriver fail. Code is ${error.code}, message is ${error.message}`); 183} 184``` 185 186## deviceManager.bindDevice<sup>(deprecated)</sup> 187 188bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<{deviceId: number; 189 remote: rpc.IRemoteObject;}>; 190 191根据queryDevices()返回的设备信息绑定设备。 192 193需要调用[deviceManager.queryDevices](#devicemanagerquerydevices)获取设备信息以及device。 194 195> **说明** 196> 从 API version 10开始支持，从API version 19开始废弃。建议使用[deviceManager.bindDriverWithDeviceId](#devicemanagerbinddriverwithdeviceid19)替代。 197 198**需要权限：** ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 199 200**系统能力：** SystemCapability.Driver.ExternalDevice 201 202**参数：** 203 204| 参数名 | 类型 | 必填 | 说明 | 205| ------------ | --------------------------- | ---- | ---------------------------- | 206| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 207| onDisconnect | AsyncCallback<number> | 是 | 绑定设备断开的回调。 | 208 209**返回值：** 210 211| 类型 | 说明 | 212| ---------------------------------------------------------------------------------------------- | -------------------------------------------- | 213| Promise<{deviceId: number; remote: [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject);}> | Promise对象，返回设备ID和IRemoteObject对象。 | 214 215**错误码：** 216 217以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[驱动错误码](errorcode-deviceManager.md)。 218 219| 错误码ID | 错误信息 | 220| -------- | ---------------------------------------- | 221| 201 | The permission check failed. | 222| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 223| 22900001 | ExternalDeviceManager service exception. | 224 225**示例：** 226 227```ts 228import { deviceManager } from '@kit.DriverDevelopmentKit'; 229import { BusinessError } from '@kit.BasicServicesKit'; 230 231try { 232 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 233 deviceManager.bindDevice(12345678, (error : BusinessError, data : number) => { 234 console.error(`Device is disconnected`); 235 }).then(data => { 236 console.info(`bindDevice success, Device_Id is ${data.deviceId}. 237 remote is ${data.remote != null ? data.remote.getDescriptor() : "null"}`); 238 }, (error: BusinessError) => { 239 console.error(`bindDevice async fail. Code is ${error.code}, message is ${error.message}`); 240 }); 241} catch (error) { 242 console.error(`bindDevice fail. Code is ${error.code}, message is ${error.message}`); 243} 244``` 245## deviceManager.bindDeviceDriver<sup>(deprecated)</sup> 246 247bindDeviceDriver(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<RemoteDeviceDriver>; 248 249根据queryDevices()返回的设备信息绑定设备。 250 251需要调用[deviceManager.queryDevices](#devicemanagerquerydevices)获取设备信息以及device。 252 253> **说明** 254> 从 API version 11开始支持，从API version 19开始废弃。建议使用[deviceManager.bindDriverWithDeviceId](#devicemanagerbinddriverwithdeviceid19)替代。 255 256**需要权限：** ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 257 258**系统能力：** SystemCapability.Driver.ExternalDevice 259 260**参数：** 261 262| 参数名 | 类型 | 必填 | 说明 | 263| ------------ | --------------------------- | ---- | ---------------------------- | 264| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 265| onDisconnect | AsyncCallback<number> | 是 | 绑定设备断开的回调。 | 266 267**返回值：** 268 269| 类型 | 说明 | 270| --------------------------------- | -----------------------------------------| 271| Promise<RemoteDeviceDriver> | Promise对象，返回RemoteDeviceDriver对象。 | 272 273**错误码：** 274 275以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[驱动错误码](errorcode-deviceManager.md)。 276 277| 错误码ID | 错误信息 | 278| -------- | ---------------------------------------- | 279| 201 | The permission check failed. | 280| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 281| 22900001 | ExternalDeviceManager service exception. | 282 283**示例：** 284 285```ts 286import { deviceManager } from '@kit.DriverDevelopmentKit'; 287import { BusinessError } from '@kit.BasicServicesKit'; 288 289try { 290 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 291 deviceManager.bindDeviceDriver(12345678, (error : BusinessError, data : number) => { 292 console.error(`Device is disconnected`); 293 }).then((data: deviceManager.RemoteDeviceDriver) => { 294 console.info(`bindDeviceDriver success, Device_Id is ${data.deviceId}. 295 remote is ${data.remote != null ? data.remote.getDescriptor() : "null"}`); 296 }, (error: BusinessError) => { 297 console.error(`bindDeviceDriver async fail. Code is ${error.code}, message is ${error.message}`); 298 }); 299} catch (error) { 300 console.error(`bindDeviceDriver fail. Code is ${error.code}, message is ${error.message}`); 301} 302``` 303 304## deviceManager.unbindDevice<sup>(deprecated)</sup> 305 306unbindDevice(deviceId: number, callback: AsyncCallback<number>): void 307 308解除设备绑定。 309 310> **说明** 311> 从 API version 10开始支持，从API version 19开始废弃。建议使用[deviceManager.unbindDriverWithDeviceId](#devicemanagerunbinddriverwithdeviceid19)替代。 312 313**需要权限**：ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 314 315**系统能力：** SystemCapability.Driver.ExternalDevice 316 317**参数：** 318 319| 参数名 | 类型 | 必填 | 说明 | 320| -------- | --------------------------- | ---- | ------------------------------ | 321| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 322| callback | AsyncCallback<number> | 是 | 解绑完成的回调。 | 323 324**错误码：** 325 326以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[驱动错误码](errorcode-deviceManager.md)。 327 328| 错误码ID | 错误信息 | 329| -------- | ---------------------------------------- | 330| 201 | The permission check failed. | 331| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 332| 22900001 | ExternalDeviceManager service exception. | 333 334**示例：** 335 336```ts 337import { deviceManager } from '@kit.DriverDevelopmentKit'; 338import { BusinessError } from '@kit.BasicServicesKit'; 339 340try { 341 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 342 deviceManager.unbindDevice(12345678, (error : BusinessError, data : number) => { 343 if (error) { 344 console.error(`unbindDevice async fail. Code is ${error.code}, message is ${error.message}`); 345 return; 346 } 347 console.info(`unbindDevice success`); 348 }); 349} catch (error) { 350 console.error(`unbindDevice fail. Code is ${error.code}, message is ${error.message}`); 351} 352``` 353## deviceManager.unbindDevice<sup>(deprecated)</sup> 354 355unbindDevice(deviceId: number): Promise<number> 356 357解除设备绑定。 358 359> **说明** 360> 从 API version 10开始支持，从API version 19开始废弃。建议使用[deviceManager.unbindDriverWithDeviceId](#devicemanagerunbinddriverwithdeviceid19)替代。 361 362**需要权限**：ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 363 364**系统能力：** SystemCapability.Driver.ExternalDevice 365 366**参数：** 367 368| 参数名 | 类型 | 必填 | 说明 | 369| -------- | ------ | ---- | ------------------------------ | 370| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 371 372**错误码：** 373 374以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[驱动错误码](errorcode-deviceManager.md)。 375 376| 错误码ID | 错误信息 | 377| -------- | ---------------------------------------- | 378| 201 | The permission check failed. | 379| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 380| 22900001 | ExternalDeviceManager service exception. | 381 382**返回值：** 383 384| 类型 | 说明 | 385| --------------------- | ------------------------- | 386| Promise<number> | Promise对象，返回设备ID。 | 387 388**示例：** 389 390```ts 391import { deviceManager } from '@kit.DriverDevelopmentKit'; 392import { BusinessError } from '@kit.BasicServicesKit'; 393 394try { 395 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 396 deviceManager.unbindDevice(12345678).then((data : number) => { 397 console.info(`unbindDevice success, Device_Id is ${data}.`); 398 }, (error : BusinessError) => { 399 console.error(`unbindDevice async fail. Code is ${error.code}, message is ${error.message}`); 400 }); 401} catch (error) { 402 console.error(`unbindDevice fail. Code is ${error.code}, message is ${error.message}`); 403} 404``` 405## deviceManager.bindDriverWithDeviceId<sup>19+</sup> 406 407bindDriverWithDeviceId(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<RemoteDeviceDriver>; 408 409根据queryDevices()返回的设备信息绑定设备。 410 411需要调用[deviceManager.queryDevices](#devicemanagerquerydevices)获取设备信息列表。 412 413**需要权限：** ohos.permission.ACCESS_DDK_DRIVERS 414 415**系统能力：** SystemCapability.Driver.ExternalDevice 416 417**参数：** 418 419| 参数名 | 类型 | 必填 | 说明 | 420| ------------ | --------------------------- | ---- | ---------------------------- | 421| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 422| onDisconnect | AsyncCallback<number> | 是 | 绑定设备断开的回调。 | 423 424**返回值：** 425 426| 类型 | 说明 | 427| --------------------------------- | -----------------------------------------| 428| Promise<RemoteDeviceDriver> | Promise对象，返回[RemoteDeviceDriver](#remotedevicedriver11)对象。 | 429 430**错误码：** 431 432以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[驱动错误码](errorcode-deviceManager.md)。 433 434| 错误码ID | 错误信息 | 435| -------- | ---------------------------------------- | 436| 201 | The permission check failed. | 437| 26300001 | ExternalDeviceManager service exception. | 438| 26300002 | The driver service does not allow any client to bind. | 439 440**示例：** 441 442```ts 443import { deviceManager } from '@kit.DriverDevelopmentKit'; 444import { BusinessError } from '@kit.BasicServicesKit'; 445 446try { 447 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 448 deviceManager.bindDriverWithDeviceId(12345678, (error : BusinessError, data : number) => { 449 console.error(`Device is disconnected`); 450 }).then((data: deviceManager.RemoteDeviceDriver) => { 451 console.info(`bindDriverWithDeviceId success, Device_Id is ${data.deviceId}. 452 remote is ${data.remote != null ? data.remote.getDescriptor() : "null"}`); 453 }, (error: BusinessError) => { 454 console.error(`bindDriverWithDeviceId async fail. Code is ${error.code}, message is ${error.message}`); 455 }); 456} catch (error) { 457 console.error(`bindDriverWithDeviceId fail. Code is ${error.code}, message is ${error.message}`); 458} 459``` 460 461## deviceManager.unbindDriverWithDeviceId<sup>19+</sup> 462 463unbindDriverWithDeviceId(deviceId: number): Promise<number> 464 465解除设备绑定。 466 467**需要权限**：ohos.permission.ACCESS_DDK_DRIVERS 468 469**系统能力：** SystemCapability.Driver.ExternalDevice 470 471**参数：** 472 473| 参数名 | 类型 | 必填 | 说明 | 474| -------- | ------ | ---- | ------------------------------ | 475| deviceId | number | 是 | 设备ID，通过queryDevices获得。 | 476 477**返回值：** 478 479| 类型 | 说明 | 480| --------------------- | ------------------------- | 481| Promise<number> | Promise对象，返回设备ID。 | 482 483**错误码：** 484 485以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[驱动错误码](errorcode-deviceManager.md)。 486 487| 错误码ID | 错误信息 | 488| -------- | ---------------------------------------- | 489| 201 | The permission check failed. | 490| 26300001 | ExternalDeviceManager service exception. | 491| 26300003 | There is no binding relationship. | 492 493**示例：** 494 495```ts 496import { deviceManager } from '@kit.DriverDevelopmentKit'; 497import { BusinessError } from '@kit.BasicServicesKit'; 498 499try { 500 // 12345678为示例deviceId，应用开发时可通过queryDevices查询到相应设备的deviceId作为入参 501 deviceManager.unbindDriverWithDeviceId(12345678).then((data : number) => { 502 console.info(`unbindDriverWithDeviceId success, Device_Id is ${data}.`); 503 }, (error : BusinessError) => { 504 console.error(`unbindDriverWithDeviceId async fail. Code is ${error.code}, message is ${error.message}`); 505 }); 506} catch (error) { 507 console.error(`unbindDriverWithDeviceId fail. Code is ${error.code}, message is ${error.message}`); 508} 509``` 510 511## Device 512 513外设信息。 514 515**系统能力：** SystemCapability.Driver.ExternalDevice 516 517| 名称 | 类型 | 只读 | 可选 | 说明 | 518| ----------- | ------------------- | ---- | ---- | ---------- | 519| busType | [BusType](#bustype) | 否 | 否 | 总线类型。 | 520| deviceId | number | 否 | 否 | 设备ID。 | 521| description | string | 否 | 否 | 设备描述。 | 522 523## USBDevice 524 525USB设备信息，继承自[Device](#device)。 526 527**系统能力：** SystemCapability.Driver.ExternalDevice 528 529| 名称 | 类型 | 只读 | 可选 | 说明 | 530| --------- | ------ | ---- | ---- | ------------------- | 531| vendorId | number | 否 | 否 | USB设备Vendor ID。 | 532| productId | number | 否 | 否 | USB设备Product ID。 | 533 534## BusType 535 536设备总线类型。 537 538**系统能力：** SystemCapability.Driver.ExternalDevice 539 540| 名称 | 值 | 说明 | 541| ---- | --- | ------------- | 542| USB | 1 | USB总线类型。 | 543 544## RemoteDeviceDriver<sup>11+</sup> 545 546远程设备驱动。 547 548**系统能力：** SystemCapability.Driver.ExternalDevice 549 550| 名称 | 类型 | 只读 | 可选 | 说明 | 551| --------- | ------ | ---- | ---- | ------------------- | 552| deviceId<sup>11+</sup> | number | 否 | 否 | 设备ID。 | 553| remote<sup>11+</sup> | [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject) | 否 | 否 | 远程驱动程序对象。 |