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| 401 | The parameter check failed. | 43| 22900001 | ExternalDeviceManager service exception. | 44 45**Example** 46 47```ts 48import { deviceManager } from '@kit.DriverDevelopmentKit'; 49 50try { 51 let devices : Array<deviceManager.Device> = deviceManager.queryDevices(deviceManager.BusType.USB); 52 for (let item of devices) { 53 let device : deviceManager.USBDevice = item as deviceManager.USBDevice; 54 console.info(`Device id is ${device.deviceId}`) 55 } 56} catch (error) { 57 console.error(`Failed to query device. Code is ${error.code}, message is ${error.message}`); 58} 59``` 60 61## deviceManager.bindDevice 62 63bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>, 64 callback: AsyncCallback<{deviceId: number; remote: rpc.IRemoteObject;}>): void; 65 66Binds a peripheral device based on the device information returned by **queryDevices()**. This API uses an asynchronous callback to return the result. 67 68You can use [deviceManager.queryDevices](#devicemanagerquerydevices) to obtain the peripheral device information first. 69 70**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 71 72**System capability**: SystemCapability.Driver.ExternalDevice 73 74**Parameters** 75 76| Name | Type | Mandatory| Description | 77| ------------ | ---------------------------------------------------------------------------------------------------- | ---- | -------------------------------------- | 78| deviceId | number | Yes | Device ID, which can be obtained by **queryDevices**. | 79| onDisconnect | AsyncCallback<number> | Yes | Callback to be invoked when the bound peripheral device is disconnected. | 80| 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.| 81 82**Error codes** 83 84| ID| Error Message | 85| -------- | ---------------------------------------- | 86| 201 | The permission check failed. | 87| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 88| 22900001 | ExternalDeviceManager service exception. | 89 90**Example** 91 92```ts 93import { deviceManager } from '@kit.DriverDevelopmentKit'; 94import { BusinessError } from '@kit.BasicServicesKit'; 95import { rpc } from '@kit.IPCKit'; 96 97interface DataType { 98 deviceId : number; 99 remote : rpc.IRemoteObject; 100} 101 102try { 103 // For example, deviceId is 12345678. You can use queryDevices() to obtain the deviceId. 104 deviceManager.bindDevice(12345678, (error : BusinessError, data : number) => { 105 console.error(`Device is disconnected`); 106 }, (error : BusinessError, data : DataType) => { 107 if (error) { 108 console.error(`bindDevice async fail. Code is ${error.code}, message is ${error.message}`); 109 return; 110 } 111 console.info(`bindDevice success`); 112 }); 113} catch (error) { 114 console.error(`bindDevice fail. Code is ${error.code}, message is ${error.message}`); 115} 116``` 117 118## deviceManager.bindDeviceDriver<sup>11+</sup> 119bindDeviceDriver(deviceId: number, onDisconnect: AsyncCallback<number>, 120 callback: AsyncCallback<RemoteDeviceDriver>): void; 121 122Binds a peripheral device based on the device information returned by **queryDevices()**. This API uses an asynchronous callback to return the result. 123 124You can use [deviceManager.queryDevices](#devicemanagerquerydevices) to obtain the peripheral device information first. 125 126**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 127 128**System capability**: SystemCapability.Driver.ExternalDevice 129 130**Parameters** 131 132| Name | Type | Mandatory| Description | 133| ------------ | --------------------------- | ---- | ---------------------------- | 134| deviceId | number | Yes | Device ID, which can be obtained by **queryDevices**.| 135| onDisconnect | AsyncCallback<number> | Yes | Callback to be invoked when the bound peripheral device is disconnected. | 136| callback | AsyncCallback<RemoteDeviceDriver>| Yes| Binding result, including the device ID and remote object.| 137 138**Error codes** 139 140| ID| Error Message | 141| -------- | ---------------------------------------- | 142| 201 | The permission check failed. | 143| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 144| 22900001 | ExternalDeviceManager service exception. | 145 146**Example** 147 148```ts 149import { deviceManager } from '@kit.DriverDevelopmentKit'; 150import { BusinessError } from '@kit.BasicServicesKit'; 151import { rpc } from '@kit.IPCKit'; 152 153try { 154 // For example, deviceId is 12345678. You can use queryDevices() to obtain the deviceId. 155 deviceManager.bindDeviceDriver(12345678, (error : BusinessError, data : number) => { 156 console.error(`Device is disconnected`); 157 }, (error : BusinessError, data : deviceManager.RemoteDeviceDriver) => { 158 if (error) { 159 console.error(`bindDeviceDriver async fail. Code is ${error.code}, message is ${error.message}`); 160 return; 161 } 162 console.info(`bindDeviceDriver success`); 163 }); 164} catch (error) { 165 console.error(`bindDeviceDriver fail. Code is ${error.code}, message is ${error.message}`); 166} 167``` 168 169## deviceManager.bindDevice 170 171bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<{deviceId: number; 172 remote: rpc.IRemoteObject;}>; 173 174Binds a peripheral device based on the device information returned by **queryDevices()**. This API uses an asynchronous callback to return the result. 175 176You need to use [deviceManager.queryDevices](#devicemanagerquerydevices) to obtain the peripheral device information first. 177 178**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 179 180**System capability**: SystemCapability.Driver.ExternalDevice 181 182**Parameters** 183 184| Name | Type | Mandatory| Description | 185| ------------ | --------------------------- | ---- | ---------------------------- | 186| deviceId | number | Yes | Device ID, which can be obtained by **queryDevices**.| 187| onDisconnect | AsyncCallback<number> | Yes | Callback to be invoked when the bound peripheral device is disconnected. | 188 189**Return value** 190 191| Type | Description | 192| ---------------------------------------------------------------------------------------------- | -------------------------------------------- | 193| Promise<{deviceId: number; remote: [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject);}> | Promise used to return the device ID and **IRemoteObject** object.| 194 195**Error codes** 196 197| ID| Error Message | 198| -------- | ---------------------------------------- | 199| 201 | The permission check failed. | 200| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 201| 22900001 | ExternalDeviceManager service exception. | 202 203**Example** 204 205```ts 206import { deviceManager } from '@kit.DriverDevelopmentKit'; 207import { BusinessError } from '@kit.BasicServicesKit'; 208 209try { 210 // For example, deviceId is 12345678. You can use queryDevices() to obtain the deviceId. 211 deviceManager.bindDevice(12345678, (error : BusinessError, data : number) => { 212 console.error(`Device is disconnected`); 213 }).then(data => { 214 console.info(`bindDevice success, Device_Id is ${data.deviceId}. 215 remote is ${data.remote != null ? data.remote.getDescriptor() : "null"}`); 216 }, (error: BusinessError) => { 217 console.error(`bindDevice async fail. Code is ${error.code}, message is ${error.message}`); 218 }); 219} catch (error) { 220 console.error(`bindDevice fail. Code is ${error.code}, message is ${error.message}`); 221} 222``` 223## deviceManager.bindDeviceDriver<sup>11+</sup> 224 225bindDeviceDriver(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<RemoteDeviceDriver>; 226 227Binds a peripheral device based on the device information returned by **queryDevices()**. This API uses an asynchronous callback to return the result. 228 229You need to use [deviceManager.queryDevices](#devicemanagerquerydevices) to obtain the peripheral device information first. 230 231**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 232 233**System capability**: SystemCapability.Driver.ExternalDevice 234 235**Parameters** 236 237| Name | Type | Mandatory| Description | 238| ------------ | --------------------------- | ---- | ---------------------------- | 239| deviceId | number | Yes | Device ID, which can be obtained by **queryDevices**.| 240| onDisconnect | AsyncCallback<number> | Yes | Callback to be invoked when the bound peripheral device is disconnected. | 241 242**Return value** 243 244| Type | Description | 245| --------------------------------- | -----------------------------------------| 246| Promise<RemoteDeviceDriver> | Promise used to return a **RemoteDeviceDriver** object.| 247 248**Error codes** 249 250| ID| Error Message | 251| -------- | ---------------------------------------- | 252| 201 | The permission check failed. | 253| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 254| 22900001 | ExternalDeviceManager service exception. | 255 256**Example** 257 258```ts 259import { deviceManager } from '@kit.DriverDevelopmentKit'; 260import { BusinessError } from '@kit.BasicServicesKit'; 261 262try { 263 // For example, deviceId is 12345678. You can use queryDevices() to obtain the deviceId. 264 deviceManager.bindDeviceDriver(12345678, (error : BusinessError, data : number) => { 265 console.error(`Device is disconnected`); 266 }).then((data: deviceManager.RemoteDeviceDriver) => { 267 console.info(`bindDeviceDriver success, Device_Id is ${data.deviceId}. 268 remote is ${data.remote != null ? data.remote.getDescriptor() : "null"}`); 269 }, (error: BusinessError) => { 270 console.error(`bindDeviceDriver async fail. Code is ${error.code}, message is ${error.message}`); 271 }); 272} catch (error) { 273 console.error(`bindDeviceDriver fail. Code is ${error.code}, message is ${error.message}`); 274} 275``` 276 277## deviceManager.unbindDevice 278 279unbindDevice(deviceId: number, callback: AsyncCallback<number>): void 280 281Unbinds a peripheral device. This API uses an asynchronous callback to return the result. 282 283**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 284 285**System capability**: SystemCapability.Driver.ExternalDevice 286 287**Parameters** 288 289| Name | Type | Mandatory| Description | 290| -------- | --------------------------- | ---- | ------------------------------ | 291| deviceId | number | Yes | Device ID, which can be obtained by **queryDevices**.| 292| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. | 293 294**Error codes** 295 296| ID| Error Message | 297| -------- | ---------------------------------------- | 298| 201 | The permission check failed. | 299| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 300| 22900001 | ExternalDeviceManager service exception. | 301 302**Example** 303 304```ts 305import { deviceManager } from '@kit.DriverDevelopmentKit'; 306 307try { 308 // For example, deviceId is 12345678. You can use queryDevices() to obtain the 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 324Unbinds a peripheral device. This API uses an asynchronous callback to return the result. 325 326**Required permissions**: ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 327 328**System capability**: SystemCapability.Driver.ExternalDevice 329 330**Parameters** 331 332| Name | Type | Mandatory| Description | 333| -------- | ------ | ---- | ------------------------------ | 334| deviceId | number | Yes | Device ID, which can be obtained by **queryDevices**.| 335 336**Error codes** 337 338| ID| Error Message | 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**Return value** 345 346| Type | Description | 347| --------------------- | ------------------------- | 348| Promise<number> | Promise used to return the device ID.| 349 350**Example** 351 352```ts 353import { deviceManager } from '@kit.DriverDevelopmentKit'; 354import { BusinessError } from '@kit.BasicServicesKit'; 355 356try { 357 // For example, deviceId is 12345678. You can use queryDevices() to obtain the 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 370Represents the peripheral device information. 371 372**System capability**: SystemCapability.Driver.ExternalDevice 373 374| Name | Type | Mandatory| Description | 375| ----------- | ------------------- | ---- | ---------- | 376| busType | [BusType](#bustype) | Yes | Bus type.| 377| deviceId | number | Yes | Device ID. | 378| description | string | Yes | Description of the peripheral device.| 379 380## USBDevice 381 382USB device information, which is inherited from [Device](#device). 383 384**System capability**: SystemCapability.Driver.ExternalDevice 385 386| Name | Type | Mandatory| Description | 387| --------- | ------ | ---- | ------------------- | 388| vendorId | number | Yes | Vendor ID of the USB device. | 389| productId | number | Yes | Product ID of the USB device.| 390 391## BusType 392 393Enumerates the device bus types. 394 395**System capability**: SystemCapability.Driver.ExternalDevice 396 397| Name| Value | Description | 398| ---- | --- | ------------- | 399| USB | 1 | USB bus.| 400 401## RemoteDeviceDriver<sup>11+</sup> 402 403Represents information about a remote device driver. 404 405**System capability**: SystemCapability.Driver.ExternalDevice 406 407| Name | Type | Mandatory| Description | 408| --------- | ------ | ---- | ------------------- | 409| deviceId<sup>11+</sup> | number | Yes | Device ID. | 410| remote<sup>11+</sup> | [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject) | Yes | Remote driver object.| 411