1# @ohos.driver.deviceManager (Peripheral Management) 2 3The **deviceManager** module provides APIs for managing peripheral devices, including querying the peripheral device list and binding or unbinding a peripheral device. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```ts 12import { deviceManager } from '@kit.DriverDevelopmentKit'; 13``` 14 15## deviceManager.queryDevices 16 17queryDevices(busType?: number): Array<Readonly<Device>> 18 19Queries the list of peripheral devices. If the device has no peripheral device connected, an empty list is returned. 20 21**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 22 23**System capability**: SystemCapability.Driver.ExternalDevice 24 25**Parameters** 26 27| Name | Type | Mandatory| Description | 28| ------- | ------ | ---- | ------------------------------------ | 29| busType | number | No | Bus type of the peripheral device to query. If this parameter is left blank, all types of peripheral devices are queried.| 30 31**Return value** 32 33| Type | Description | 34| ---------------------------------------------- | -------------- | 35| Array<Readonly<[Device](#device)>> | List of peripheral devices obtained.| 36 37**Error codes** 38 39| ID| Error Message | 40| -------- | ---------------------------------------- | 41| 201 | The permission check failed. | 42| 22900001 | ExternalDeviceManager service exception or busType parameter error. | 43 44**Example** 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<sup>(deprecated)</sup> 61 62bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>, 63 callback: AsyncCallback<{deviceId: number; remote: rpc.IRemoteObject;}>): void 64 65Binds a peripheral device based on the device information returned by **queryDevices()**. This API uses an asynchronous callback to return the result. 66 67You can use [deviceManager.queryDevices](#devicemanagerquerydevices) to obtain the peripheral device information first. 68 69> **NOTE** 70> This API is supported since API version 10 and deprecated since API version 18. You are advised to use [deviceManager.bindDriverWithDeviceId](#devicemanagerbinddriverwithdeviceid18) instead. 71 72**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 73 74**System capability**: SystemCapability.Driver.ExternalDevice 75 76**Parameters** 77 78| Name | Type | Mandatory| Description | 79| ------------ | ---------------------------------------------------------------------------------------------------- | ---- | -------------------------------------- | 80| deviceId | number | Yes | ID of the device to unbind. It can be obtained by **queryDevices()**. | 81| onDisconnect | AsyncCallback<number> | Yes | Callback to be invoked when the bound peripheral device is disconnected. | 82| callback | AsyncCallback<{deviceId: number; remote: [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject);}> | Yes | Callback invoked to return the communication object of the peripheral device bound.| 83 84**Error codes** 85 86| ID| Error Message | 87| -------- | ---------------------------------------- | 88| 201 | The permission check failed. | 89| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 90| 22900001 | ExternalDeviceManager service exception. | 91 92**Example** 93 94```ts 95import { deviceManager } from '@kit.DriverDevelopmentKit'; 96import { BusinessError } from '@kit.BasicServicesKit'; 97import { rpc } from '@kit.IPCKit'; 98 99interface DataType { 100 deviceId : number; 101 remote : rpc.IRemoteObject; 102} 103 104try { 105 // For example, deviceId is 12345678. You can use queryDevices() to obtain the deviceId. 106 deviceManager.bindDevice(12345678, (error : BusinessError, data : number) => { 107 console.error(`Device is disconnected`); 108 }, (error : BusinessError, data : DataType) => { 109 if (error) { 110 console.error(`bindDevice async fail. Code is ${error.code}, message is ${error.message}`); 111 return; 112 } 113 console.info(`bindDevice success`); 114 }); 115} catch (error) { 116 console.error(`bindDevice fail. Code is ${error.code}, message is ${error.message}`); 117} 118``` 119 120## deviceManager.bindDeviceDriver<sup>(deprecated)</sup> 121bindDeviceDriver(deviceId: number, onDisconnect: AsyncCallback<number>, 122 callback: AsyncCallback<RemoteDeviceDriver>): void 123 124Binds a peripheral device based on the device information returned by **queryDevices()**. This API uses an asynchronous callback to return the result. 125 126You can use [deviceManager.queryDevices](#devicemanagerquerydevices) to obtain the peripheral device information first. 127 128> **Description** 129> This API is supported since API version 11 and deprecated since API version 18. You are advised to use [deviceManager.bindDriverWithDeviceId](#devicemanagerbinddriverwithdeviceid18) instead. 130 131**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 132 133**System capability**: SystemCapability.Driver.ExternalDevice 134 135**Parameters** 136 137| Name | Type | Mandatory| Description | 138| ------------ | --------------------------- | ---- | ---------------------------- | 139| deviceId | number | Yes | ID of the device to unbind. It can be obtained by **queryDevices()**.| 140| onDisconnect | AsyncCallback<number> | Yes | Callback to be invoked when the bound peripheral device is disconnected. | 141| callback | AsyncCallback<RemoteDeviceDriver>| Yes| Binding result, including the device ID and remote object.| 142 143**Error codes** 144 145| ID| Error Message | 146| -------- | ---------------------------------------- | 147| 201 | The permission check failed. | 148| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 149| 22900001 | ExternalDeviceManager service exception. | 150 151**Example** 152 153```ts 154import { deviceManager } from '@kit.DriverDevelopmentKit'; 155import { BusinessError } from '@kit.BasicServicesKit'; 156import { rpc } from '@kit.IPCKit'; 157 158try { 159 // For example, deviceId is 12345678. You can use queryDevices() to obtain the deviceId. 160 deviceManager.bindDeviceDriver(12345678, (error : BusinessError, data : number) => { 161 console.error(`Device is disconnected`); 162 }, (error : BusinessError, data : deviceManager.RemoteDeviceDriver) => { 163 if (error) { 164 console.error(`bindDeviceDriver async fail. Code is ${error.code}, message is ${error.message}`); 165 return; 166 } 167 console.info(`bindDeviceDriver success`); 168 }); 169} catch (error) { 170 console.error(`bindDeviceDriver fail. Code is ${error.code}, message is ${error.message}`); 171} 172``` 173 174## deviceManager.bindDevice<sup>(deprecated)</sup> 175 176bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<{deviceId: number; 177 remote: rpc.IRemoteObject;}>; 178 179Binds a peripheral device based on the device information returned by **queryDevices()**. This API uses an asynchronous callback to return the result. 180 181You need to use [deviceManager.queryDevices](#devicemanagerquerydevices) to obtain the peripheral device information first. 182 183> **NOTE** 184> This API is supported since API version 10 and deprecated since API version 18. You are advised to use [deviceManager.bindDriverWithDeviceId](#devicemanagerbinddriverwithdeviceid18) instead. 185 186**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 187 188**System capability**: SystemCapability.Driver.ExternalDevice 189 190**Parameters** 191 192| Name | Type | Mandatory| Description | 193| ------------ | --------------------------- | ---- | ---------------------------- | 194| deviceId | number | Yes | ID of the device to unbind. It can be obtained by **queryDevices()**.| 195| onDisconnect | AsyncCallback<number> | Yes | Callback to be invoked when the bound peripheral device is disconnected. | 196 197**Return value** 198 199| Type | Description | 200| ---------------------------------------------------------------------------------------------- | -------------------------------------------- | 201| Promise<{deviceId: number; remote: [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject);}> | Promise used to return the device ID and **IRemoteObject** object.| 202 203**Error codes** 204 205| ID| Error Message | 206| -------- | ---------------------------------------- | 207| 201 | The permission check failed. | 208| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 209| 22900001 | ExternalDeviceManager service exception. | 210 211**Example** 212 213```ts 214import { deviceManager } from '@kit.DriverDevelopmentKit'; 215import { BusinessError } from '@kit.BasicServicesKit'; 216 217try { 218 // For example, deviceId is 12345678. You can use queryDevices() to obtain the deviceId. 219 deviceManager.bindDevice(12345678, (error : BusinessError, data : number) => { 220 console.error(`Device is disconnected`); 221 }).then(data => { 222 console.info(`bindDevice success, Device_Id is ${data.deviceId}. 223 remote is ${data.remote != null ? data.remote.getDescriptor() : "null"}`); 224 }, (error: BusinessError) => { 225 console.error(`bindDevice async fail. Code is ${error.code}, message is ${error.message}`); 226 }); 227} catch (error) { 228 console.error(`bindDevice fail. Code is ${error.code}, message is ${error.message}`); 229} 230``` 231## deviceManager.bindDeviceDriver<sup>(deprecated)</sup> 232 233bindDeviceDriver(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<RemoteDeviceDriver>; 234 235Binds a peripheral device based on the device information returned by **queryDevices()**. This API uses a promise to return the result. 236 237You need to use [deviceManager.queryDevices](#devicemanagerquerydevices) to obtain the peripheral device information first. 238 239> **NOTE** 240> This API is supported since API version 11 and deprecated since API version 18. You are advised to use [deviceManager.bindDriverWithDeviceId](#devicemanagerbinddriverwithdeviceid18) instead. 241 242**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 243 244**System capability**: SystemCapability.Driver.ExternalDevice 245 246**Parameters** 247 248| Name | Type | Mandatory| Description | 249| ------------ | --------------------------- | ---- | ---------------------------- | 250| deviceId | number | Yes | ID of the device to unbind. It can be obtained by **queryDevices()**.| 251| onDisconnect | AsyncCallback<number> | Yes | Callback to be invoked when the bound peripheral device is disconnected. | 252 253**Return value** 254 255| Type | Description | 256| --------------------------------- | -----------------------------------------| 257| Promise<RemoteDeviceDriver> | Promise used to return a **RemoteDeviceDriver** object.| 258 259**Error codes** 260 261| ID| Error Message | 262| -------- | ---------------------------------------- | 263| 201 | The permission check failed. | 264| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 265| 22900001 | ExternalDeviceManager service exception. | 266 267**Example** 268 269```ts 270import { deviceManager } from '@kit.DriverDevelopmentKit'; 271import { BusinessError } from '@kit.BasicServicesKit'; 272 273try { 274 // For example, deviceId is 12345678. You can use queryDevices() to obtain the deviceId. 275 deviceManager.bindDeviceDriver(12345678, (error : BusinessError, data : number) => { 276 console.error(`Device is disconnected`); 277 }).then((data: deviceManager.RemoteDeviceDriver) => { 278 console.info(`bindDeviceDriver success, Device_Id is ${data.deviceId}. 279 remote is ${data.remote != null ? data.remote.getDescriptor() : "null"}`); 280 }, (error: BusinessError) => { 281 console.error(`bindDeviceDriver async fail. Code is ${error.code}, message is ${error.message}`); 282 }); 283} catch (error) { 284 console.error(`bindDeviceDriver fail. Code is ${error.code}, message is ${error.message}`); 285} 286``` 287 288## deviceManager.unbindDevice<sup>(deprecated)</sup> 289 290unbindDevice(deviceId: number, callback: AsyncCallback<number>): void 291 292Unbinds a peripheral device. This API uses an asynchronous callback to return the result. 293 294> **NOTE** 295> This API is supported since API version 10 and deprecated since API version 18. You are advised to use [deviceManager.unbindDriverWithDeviceId](#devicemanagerunbinddriverwithdeviceid18) instead. 296 297**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 298 299**System capability**: SystemCapability.Driver.ExternalDevice 300 301**Parameters** 302 303| Name | Type | Mandatory| Description | 304| -------- | --------------------------- | ---- | ------------------------------ | 305| deviceId | number | Yes | ID of the device to unbind. It can be obtained by **queryDevices()**.| 306| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. | 307 308**Error codes** 309 310| ID| Error Message | 311| -------- | ---------------------------------------- | 312| 201 | The permission check failed. | 313| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 314| 22900001 | ExternalDeviceManager service exception. | 315 316**Example** 317 318```ts 319import { deviceManager } from '@kit.DriverDevelopmentKit'; 320import { BusinessError } from '@kit.BasicServicesKit'; 321 322try { 323 // For example, deviceId is 12345678. You can use queryDevices() to obtain the deviceId. 324 deviceManager.unbindDevice(12345678, (error : BusinessError, data : number) => { 325 if (error) { 326 console.error(`unbindDevice async fail. Code is ${error.code}, message is ${error.message}`); 327 return; 328 } 329 console.info(`unbindDevice success`); 330 }); 331} catch (error) { 332 console.error(`unbindDevice fail. Code is ${error.code}, message is ${error.message}`); 333} 334``` 335## deviceManager.unbindDevice<sup>(deprecated)</sup> 336 337unbindDevice(deviceId: number): Promise<number> 338 339Unbinds a peripheral device. This API uses an asynchronous callback to return the result. 340 341> **NOTE** 342> This API is supported since API version 10 and deprecated since API version 18. You are advised to use [deviceManager.unbindDriverWithDeviceId](#devicemanagerunbinddriverwithdeviceid18) instead. 343 344**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 345 346**System capability**: SystemCapability.Driver.ExternalDevice 347 348**Parameters** 349 350| Name | Type | Mandatory| Description | 351| -------- | ------ | ---- | ------------------------------ | 352| deviceId | number | Yes | ID of the device to unbind. It can be obtained by **queryDevices()**.| 353 354**Error codes** 355 356| ID| Error Message | 357| -------- | ---------------------------------------- | 358| 201 | The permission check failed. | 359| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 360| 22900001 | ExternalDeviceManager service exception. | 361 362**Return value** 363 364| Type | Description | 365| --------------------- | ------------------------- | 366| Promise<number> | Promise used to return the device ID.| 367 368**Example** 369 370```ts 371import { deviceManager } from '@kit.DriverDevelopmentKit'; 372import { BusinessError } from '@kit.BasicServicesKit'; 373 374try { 375 // For example, deviceId is 12345678. You can use queryDevices() to obtain the deviceId. 376 deviceManager.unbindDevice(12345678).then((data : number) => { 377 console.info(`unbindDevice success, Device_Id is ${data}.`); 378 }, (error : BusinessError) => { 379 console.error(`unbindDevice async fail. Code is ${error.code}, message is ${error.message}`); 380 }); 381} catch (error) { 382 console.error(`unbindDevice fail. Code is ${error.code}, message is ${error.message}`); 383} 384``` 385## deviceManager.bindDriverWithDeviceId<sup>18+</sup> 386 387bindDriverWithDeviceId(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<RemoteDeviceDriver>; 388 389Binds a peripheral device based on the device information returned by **queryDevices()**. This API uses an asynchronous callback to return the result. 390 391You need to call [deviceManager.queryDevices](#devicemanagerquerydevices) to obtain the device list. 392 393**Required permissions**: ohos.permission.ACCESS_DDK_DRIVERS 394 395**System capability**: SystemCapability.Driver.ExternalDevice 396 397**Parameters** 398 399| Name | Type | Mandatory| Description | 400| ------------ | --------------------------- | ---- | ---------------------------- | 401| deviceId | number | Yes | ID of the device to unbind. It can be obtained by **queryDevices()**.| 402| onDisconnect | AsyncCallback<number> | Yes | Callback to be invoked when the bound peripheral device is disconnected. | 403 404**Return value** 405 406| Type | Description | 407| --------------------------------- | -----------------------------------------| 408| Promise<RemoteDeviceDriver> | Promise used to return the [RemoteDeviceDriver](#remotedevicedriver11) object.| 409 410**Error codes** 411 412| ID| Error Message | 413| -------- | ---------------------------------------- | 414| 201 | The permission check failed. | 415| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 416| 26300001 | ExternalDeviceManager service exception. | 417| 26300002 | Service not allowed. | 418 419**Example** 420 421```ts 422import { deviceManager } from '@kit.DriverDevelopmentKit'; 423import { BusinessError } from '@kit.BasicServicesKit'; 424 425try { 426 // For example, deviceId is 12345678. You can use queryDevices() to obtain the deviceId. 427 deviceManager.bindDriverWithDeviceId(12345678, (error : BusinessError, data : number) => { 428 console.error(`Device is disconnected`); 429 }).then((data: deviceManager.RemoteDeviceDriver) => { 430 console.info(`bindDriverWithDeviceId success, Device_Id is ${data.deviceId}. 431 remote is ${data.remote != null ? data.remote.getDescriptor() : "null"}`); 432 }, (error: BusinessError) => { 433 console.error(`bindDriverWithDeviceId async fail. Code is ${error.code}, message is ${error.message}`); 434 }); 435} catch (error) { 436 console.error(`bindDriverWithDeviceId fail. Code is ${error.code}, message is ${error.message}`); 437} 438``` 439 440## deviceManager.unbindDriverWithDeviceId<sup>18+</sup> 441 442unbindDriverWithDeviceId(deviceId: number): Promise<number> 443 444Unbinds a peripheral device. This API uses an asynchronous callback to return the result. 445 446**Required permissions**: ohos.permission.ACCESS_DDK_DRIVERS 447 448**System capability**: SystemCapability.Driver.ExternalDevice 449 450**Parameters** 451 452| Name | Type | Mandatory| Description | 453| -------- | ------ | ---- | ------------------------------ | 454| deviceId | number | Yes | ID of the device to unbind. It can be obtained by **queryDevices()**.| 455 456**Return value** 457 458| Type | Description | 459| --------------------- | ------------------------- | 460| Promise<number> | Promise used to return the device ID.| 461 462**Error codes** 463 464| ID| Error Message | 465| -------- | ---------------------------------------- | 466| 201 | The permission check failed. | 467| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 468| 26300001 | ExternalDeviceManager service exception. | 469| 26300003 | There is no binding relationship. | 470 471**Example** 472 473```ts 474import { deviceManager } from '@kit.DriverDevelopmentKit'; 475import { BusinessError } from '@kit.BasicServicesKit'; 476 477try { 478 // For example, deviceId is 12345678. You can use queryDevices() to obtain the deviceId. 479 deviceManager.unbindDriverWithDeviceId(12345678).then((data : number) => { 480 console.info(`unbindDriverWithDeviceId success, Device_Id is ${data}.`); 481 }, (error : BusinessError) => { 482 console.error(`unbindDriverWithDeviceId async fail. Code is ${error.code}, message is ${error.message}`); 483 }); 484} catch (error) { 485 console.error(`unbindDriverWithDeviceId fail. Code is ${error.code}, message is ${error.message}`); 486} 487``` 488 489## Device 490 491Represents the peripheral device information. 492 493**System capability**: SystemCapability.Driver.ExternalDevice 494 495| Name | Type | Mandatory| Description | 496| ----------- | ------------------- | ---- | ---------- | 497| busType | [BusType](#bustype) | Yes | Bus type.| 498| deviceId | number | Yes | ID of the peripheral device. | 499| description | string | Yes | Description of the peripheral device.| 500 501## USBDevice 502 503USB device information, which is inherited from [Device](#device). 504 505**System capability**: SystemCapability.Driver.ExternalDevice 506 507| Name | Type | Mandatory| Description | 508| --------- | ------ | ---- | ------------------- | 509| vendorId | number | Yes | Vendor ID of the USB device. | 510| productId | number | Yes | Product ID of the USB device.| 511 512## BusType 513 514Enumerates the device bus types. 515 516**System capability**: SystemCapability.Driver.ExternalDevice 517 518| Name| Value | Description | 519| ---- | --- | ------------- | 520| USB | 1 | USB bus.| 521 522## RemoteDeviceDriver<sup>11+</sup> 523 524Represents information about a remote device driver. 525 526**System capability**: SystemCapability.Driver.ExternalDevice 527 528| Name | Type | Mandatory| Description | 529| --------- | ------ | ---- | ------------------- | 530| deviceId<sup>11+</sup> | number | Yes | ID of the peripheral device. | 531| remote<sup>11+</sup> | [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject) | Yes | Remote driver object.| 532