1/* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit DriverDevelopmentKit 19 */ 20 21import type { AsyncCallback } from './@ohos.base'; 22import type rpc from './@ohos.rpc'; 23 24/** 25 * This module provides the capability of manage external device. 26 * 27 * @namespace deviceManager 28 * @syscap SystemCapability.Driver.ExternalDevice 29 * @since arkts {'1.1':'10', '1.2':'20'} 30 * @arkts 1.1&1.2 31 */ 32declare namespace deviceManager { 33 /** 34 * Query the external device list. 35 * 36 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 37 * @param { int } busType - The bus type of device to be queried. 38 * @returns { Array<Readonly<Device>> } External device list. 39 * @throws { BusinessError } 201 - The permission check failed. 40 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception or busType parameter error. 41 * @syscap SystemCapability.Driver.ExternalDevice 42 * @since arkts {'1.1':'10', '1.2':'20'} 43 * @arkts 1.1&1.2 44 */ 45 function queryDevices(busType?: int): Array<Readonly<Device>>; 46 47 /** 48 * Bind the device based on the device information returned by queryDevices(). 49 * 50 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 51 * @param { number } deviceId - Device id on the device list returned by queryDevices(). 52 * @param { AsyncCallback<number> } onDisconnect - Callback is invoked when device is disconnected after bind 53 * success. 54 * @param { AsyncCallback<{deviceId: number; remote: rpc.IRemoteObject;}> } callback - Indicates the bind result 55 * including device ID and remote object. 56 * @throws { BusinessError } 201 - The permission check failed. 57 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 58 * 3.Parameter verification failed. 59 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception. 60 * @syscap SystemCapability.Driver.ExternalDevice 61 * @since 10 62 * @deprecated since 18 63 * @useinstead ohos.driver.deviceManager/deviceManager#bindDriverWithDeviceId 64 */ 65 function bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>, 66 callback: AsyncCallback<{deviceId: number; remote: rpc.IRemoteObject;}>): void; 67 68 /** 69 * Bind the device based on the device information returned by queryDevices(). 70 * 71 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 72 * @param { number } deviceId - Device id on the device list returned by queryDevices(). 73 * @param { AsyncCallback<number> } onDisconnect - Callback is invoked when device is disconnected after bind 74 * success. 75 * @param { AsyncCallback<RemoteDeviceDriver> } callback - Indicates the bind result including device ID and 76 * remote object. 77 * @throws { BusinessError } 201 - The permission check failed. 78 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 79 * 3.Parameter verification failed. 80 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception. 81 * @syscap SystemCapability.Driver.ExternalDevice 82 * @since 11 83 * @deprecated since 18 84 * @useinstead ohos.driver.deviceManager/deviceManager#bindDriverWithDeviceId 85 */ 86 function bindDeviceDriver(deviceId: number, onDisconnect: AsyncCallback<number>, 87 callback: AsyncCallback<RemoteDeviceDriver>): void; 88 89 /** 90 * Bind the device based on the device information returned by queryDevices(). 91 * 92 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 93 * @param { number } deviceId - Device id on the device list returned by queryDevices(). 94 * @param { AsyncCallback<number> } onDisconnect - Callback is invoked when device is disconnected after bind 95 * success. 96 * @returns { Promise<{deviceId: number; remote: rpc.IRemoteObject;}> } Indicates the bind result including device 97 * ID and remote object. 98 * @throws { BusinessError } 201 - The permission check failed. 99 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 100 * 3.Parameter verification failed. 101 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception. 102 * @syscap SystemCapability.Driver.ExternalDevice 103 * @since 10 104 * @deprecated since 18 105 * @useinstead ohos.driver.deviceManager/deviceManager#bindDriverWithDeviceId 106 */ 107 function bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<{deviceId: number; 108 remote: rpc.IRemoteObject;}>; 109 110 /** 111 * Bind the device based on the device information returned by queryDevices(). 112 * 113 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 114 * @param { number } deviceId - Device id on the device list returned by queryDevices(). 115 * @param { AsyncCallback<number> } onDisconnect - Callback is invoked when device is disconnected after bind 116 * success. 117 * @returns { Promise<RemoteDeviceDriver> } Indicates the bind result including device ID and remote object. 118 * @throws { BusinessError } 201 - The permission check failed. 119 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 120 * 3.Parameter verification failed. 121 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception. 122 * @syscap SystemCapability.Driver.ExternalDevice 123 * @since 11 124 * @deprecated since 18 125 * @useinstead ohos.driver.deviceManager/deviceManager#bindDriverWithDeviceId 126 */ 127 function bindDeviceDriver(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<RemoteDeviceDriver>; 128 129 /** 130 * Unbind the device based on the device information returned by queryDevices(). 131 * 132 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 133 * @param { number } deviceId - Device id on the device list returned by queryDevices(). 134 * @param { AsyncCallback<number> } callback - Indicates the unbind result invoked when unbind is finished. 135 * @throws { BusinessError } 201 - The permission check failed. 136 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 137 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception. 138 * @syscap SystemCapability.Driver.ExternalDevice 139 * @since 10 140 * @deprecated since 18 141 * @useinstead ohos.driver.deviceManager/deviceManager#unbindDriverWithDeviceId 142 */ 143 function unbindDevice(deviceId: number, callback: AsyncCallback<number>): void; 144 145 /** 146 * Unbind the device based on the device information returned by queryDevices(). 147 * 148 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 149 * @param { number } deviceId - Device id on the device list returned by queryDevices(). 150 * @returns { Promise<number> } - Indicates the unbind result invoked when unbind is finished. 151 * @throws { BusinessError } 201 - The permission check failed. 152 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 153 * 3.Parameter verification failed. 154 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception. 155 * @syscap SystemCapability.Driver.ExternalDevice 156 * @since 10 157 * @deprecated since 18 158 * @useinstead ohos.driver.deviceManager/deviceManager#unbindDriverWithDeviceId 159 */ 160 function unbindDevice(deviceId: number): Promise<number>; 161 162 /** 163 * Queries external device information. 164 * 165 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 166 * @param { long } deviceId - ID of device to query. 167 * @returns { Array<Readonly<DeviceInfo>> } Device information obtained. 168 * @throws { BusinessError } 201 - The permission check failed. 169 * @throws { BusinessError } 202 - Permission denied. A non-system application cannot call a system API. 170 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types. 171 * @throws { BusinessError } 26300001 - ExternalDeviceManager service exception. 172 * @syscap SystemCapability.Driver.ExternalDevice 173 * @systemapi 174 * @since arkts {'1.1':'12', '1.2':'20'} 175 * @arkts 1.1&1.2 176 */ 177 function queryDeviceInfo(deviceId?: long): Array<Readonly<DeviceInfo>>; 178 179 /** 180 * Queries driver information. 181 * 182 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 183 * @param { string } driverUid - Unique identifier of driver query. 184 * @returns { Array<Readonly<DriverInfo>> } Driver information obtained. 185 * @throws { BusinessError } 201 - The permission check failed. 186 * @throws { BusinessError } 202 - Permission denied. A non-system application cannot call a system API. 187 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types. 188 * @throws { BusinessError } 26300001 - ExternalDeviceManager service exception. 189 * @syscap SystemCapability.Driver.ExternalDevice 190 * @systemapi 191 * @since arkts {'1.1':'12', '1.2':'20'} 192 * @arkts 1.1&1.2 193 */ 194 function queryDriverInfo(driverUid?: string): Array<Readonly<DriverInfo>>; 195 196/** 197* Bind the device based on the device information returned by queryDevices(). 198* 199* @permission ohos.permission.ACCESS_DDK_DRIVERS 200* @param { long } deviceId - Device id on the device list returned by queryDevices(). 201* @param { AsyncCallback<long> } onDisconnect - Callback is invoked when device is disconnected after bind 202* success. 203* @returns { Promise<RemoteDeviceDriver> } Indicates the bind result including device ID and remote object. 204* @throws { BusinessError } 201 - The permission check failed. 205* @throws { BusinessError } 26300001 - ExternalDeviceManager service exception. 206* @throws { BusinessError } 26300002 - The driver service does not allow any client to bind. 207* @syscap SystemCapability.Driver.ExternalDevice 208* @since arkts{ '1.1':'19','1.2':'20'} 209* @arkts 1.1&1.2 210*/ 211 function bindDriverWithDeviceId(deviceId: long, onDisconnect: AsyncCallback<long>): Promise<RemoteDeviceDriver>; 212 213/** 214* Unbind the device based on the device information returned by queryDevices(). 215* 216* @permission ohos.permission.ACCESS_DDK_DRIVERS 217* @param { long } deviceId - Device id on the device list returned by queryDevices(). 218* @returns { Promise<int> } - Indicates the unbind result invoked when unbind is finished. 219* @throws { BusinessError } 201 - The permission check failed. 220* @throws { BusinessError } 26300001 - ExternalDeviceManager service exception. 221* @throws { BusinessError } 26300003 - There is no binding relationship. 222* @syscap SystemCapability.Driver.ExternalDevice 223* @since arkts{ '1.1':'19','1.2':'20'} 224* @arkts 1.1&1.2 225*/ 226 function unbindDriverWithDeviceId(deviceId: long): Promise<int>; 227 228 /** 229 * Enumerates the bus types. 230 * 231 * @enum { int } 232 * @syscap SystemCapability.Driver.ExternalDevice 233 * @since arkts {'1.1':'10', '1.2':'20'} 234 * @arkts 1.1&1.2 235 */ 236 export enum BusType { 237 /** 238 * USB device type 239 * 240 * @syscap SystemCapability.Driver.ExternalDevice 241 * @since arkts {'1.1':'10', '1.2':'20'} 242 * @arkts 1.1&1.2 243 */ 244 USB = 1, 245 } 246 247 /** 248 * Represents a device. 249 * 250 * @typedef Device 251 * @syscap SystemCapability.Driver.ExternalDevice 252 * @since arkts {'1.1':'10', '1.2':'20'} 253 * @arkts 1.1&1.2 254 */ 255 interface Device { 256 /** 257 * Bus type of the device. 258 * 259 * @type { BusType } 260 * @syscap SystemCapability.Driver.ExternalDevice 261 * @since arkts {'1.1':'10', '1.2':'20'} 262 * @arkts 1.1&1.2 263 */ 264 busType: BusType; 265 266 /** 267 * Device ID. 268 * 269 * @type { long } 270 * @syscap SystemCapability.Driver.ExternalDevice 271 * @since arkts {'1.1':'10', '1.2':'20'} 272 * @arkts 1.1&1.2 273 */ 274 deviceId: long; 275 276 /** 277 * Description of the device. 278 * 279 * @type { string } 280 * @syscap SystemCapability.Driver.ExternalDevice 281 * @since arkts {'1.1':'10', '1.2':'20'} 282 * @arkts 1.1&1.2 283 */ 284 description: string; 285 } 286 287 /** 288 * Represents a USB device. 289 * 290 * @typedef USBDevice 291 * @extends Device 292 * @syscap SystemCapability.Driver.ExternalDevice 293 * @since arkts {'1.1':'10', '1.2':'20'} 294 * @arkts 1.1&1.2 295 */ 296 interface USBDevice extends Device { 297 /** 298 * Vendor ID. 299 * 300 * @type { int } 301 * @syscap SystemCapability.Driver.ExternalDevice 302 * @since arkts {'1.1':'10', '1.2':'20'} 303 * @arkts 1.1&1.2 304 */ 305 vendorId: int; 306 307 /** 308 * Product ID. 309 * 310 * @type { int } 311 * @syscap SystemCapability.Driver.ExternalDevice 312 * @since arkts {'1.1':'10', '1.2':'20'} 313 * @arkts 1.1&1.2 314 */ 315 productId: int; 316 } 317 318 /** 319 * Driver of the remote device bound with <b>deviceId</b>. 320 * 321 * @typedef RemoteDeviceDriver 322 * @syscap SystemCapability.Driver.ExternalDevice 323 * @since arkts {'1.1':'11', '1.2':'20'} 324 * @arkts 1.1&1.2 325 */ 326 interface RemoteDeviceDriver { 327 /** 328 * Device ID. 329 * 330 * @type { long } 331 * @syscap SystemCapability.Driver.ExternalDevice 332 * @since arkts {'1.1':'11', '1.2':'20'} 333 * @arkts 1.1&1.2 334 */ 335 deviceId: long; 336 337 /** 338 * Remote driver object. 339 * 340 * @type { rpc.IRemoteObject } 341 * @syscap SystemCapability.Driver.ExternalDevice 342 * @since arkts {'1.1':'11', '1.2':'20'} 343 * @arkts 1.1&1.2 344 */ 345 remote: rpc.IRemoteObject; 346 } 347 348 /** 349 * Represents information about a device interface descriptor. 350 * 351 * @typedef USBInterfaceDesc 352 * @syscap SystemCapability.Driver.ExternalDevice 353 * @systemapi 354 * @since arkts {'1.1':'12', '1.2':'20'} 355 * @arkts 1.1&1.2 356 */ 357 interface USBInterfaceDesc { 358 /** 359 * Interface number. 360 * 361 * @type { int } 362 * @syscap SystemCapability.Driver.ExternalDevice 363 * @systemapi 364 * @since arkts {'1.1':'12', '1.2':'20'} 365 * @arkts 1.1&1.2 366 */ 367 bInterfaceNumber: int; 368 369 /** 370 * Interface class code. 371 * 372 * @type { int } 373 * @syscap SystemCapability.Driver.ExternalDevice 374 * @systemapi 375 * @since arkts {'1.1':'12', '1.2':'20'} 376 * @arkts 1.1&1.2 377 */ 378 bClass: int; 379 380 /** 381 * Interface subclass code. 382 * 383 * @type { int } 384 * @syscap SystemCapability.Driver.ExternalDevice 385 * @systemapi 386 * @since arkts {'1.1':'12', '1.2':'20'} 387 * @arkts 1.1&1.2 388 */ 389 bSubClass: int; 390 391 /** 392 * Interface protocol. 393 * 394 * @type { int } 395 * @syscap SystemCapability.Driver.ExternalDevice 396 * @systemapi 397 * @since arkts {'1.1':'12', '1.2':'20'} 398 * @arkts 1.1&1.2 399 */ 400 bProtocol: int; 401 } 402 403 404 /** 405 * Represents the device information. 406 * 407 * @typedef DeviceInfo 408 * @syscap SystemCapability.Driver.ExternalDevice 409 * @systemapi 410 * @since arkts {'1.1':'12', '1.2':'20'} 411 * @arkts 1.1&1.2 412 */ 413 interface DeviceInfo { 414 /** 415 * Device ID. 416 * 417 * @type { long } 418 * @syscap SystemCapability.Driver.ExternalDevice 419 * @systemapi 420 * @since arkts {'1.1':'12', '1.2':'20'} 421 * @arkts 1.1&1.2 422 */ 423 deviceId: long; 424 425 /** 426 * Whether the device has a matched driver. 427 * 428 * @type { boolean } 429 * @syscap SystemCapability.Driver.ExternalDevice 430 * @systemapi 431 * @since arkts {'1.1':'12', '1.2':'20'} 432 * @arkts 1.1&1.2 433 */ 434 isDriverMatched: boolean; 435 436 /** 437 * Unique identifier of the driver. 438 * 439 * @type { ?string } 440 * @syscap SystemCapability.Driver.ExternalDevice 441 * @systemapi 442 * @since arkts {'1.1':'12', '1.2':'20'} 443 * @arkts 1.1&1.2 444 */ 445 driverUid?: string; 446 } 447 448 /** 449 * Represents the USB device information. 450 * 451 * @typedef USBDeviceInfo 452 * @extends DeviceInfo 453 * @syscap SystemCapability.Driver.ExternalDevice 454 * @systemapi 455 * @since arkts {'1.1':'12', '1.2':'20'} 456 * @arkts 1.1&1.2 457 */ 458 interface USBDeviceInfo extends DeviceInfo { 459 /** 460 * Vendor ID. 461 * 462 * @type { int } 463 * @syscap SystemCapability.Driver.ExternalDevice 464 * @systemapi 465 * @since arkts {'1.1':'12', '1.2':'20'} 466 * @arkts 1.1&1.2 467 */ 468 vendorId: int; 469 470 /** 471 * Product ID. 472 * 473 * @type { int } 474 * @syscap SystemCapability.Driver.ExternalDevice 475 * @systemapi 476 * @since arkts {'1.1':'12', '1.2':'20'} 477 * @arkts 1.1&1.2 478 */ 479 productId: int; 480 481 /** 482 * List of USB interface descriptors. 483 * 484 * @type { Array<Readonly<USBInterfaceDesc>> } 485 * @syscap SystemCapability.Driver.ExternalDevice 486 * @systemapi 487 * @since arkts {'1.1':'12', '1.2':'20'} 488 * @arkts 1.1&1.2 489 */ 490 interfaceDescList: Array<Readonly<USBInterfaceDesc>>; 491 } 492 493 /** 494 * Represents the driver information. 495 * 496 * @typedef DriverInfo 497 * @syscap SystemCapability.Driver.ExternalDevice 498 * @systemapi 499 * @since arkts {'1.1':'12', '1.2':'20'} 500 * @arkts 1.1&1.2 501 */ 502 interface DriverInfo { 503 /** 504 * Bus type of the device. 505 * 506 * @type { BusType } 507 * @syscap SystemCapability.Driver.ExternalDevice 508 * @systemapi 509 * @since arkts {'1.1':'12', '1.2':'20'} 510 * @arkts 1.1&1.2 511 */ 512 busType: BusType; 513 514 /** 515 * Unique identifier of the driver. 516 * 517 * @type { string } 518 * @syscap SystemCapability.Driver.ExternalDevice 519 * @systemapi 520 * @since arkts {'1.1':'12', '1.2':'20'} 521 * @arkts 1.1&1.2 522 */ 523 driverUid: string; 524 525 /** 526 * Driver name. 527 * 528 * @type { string } 529 * @syscap SystemCapability.Driver.ExternalDevice 530 * @systemapi 531 * @since arkts {'1.1':'12', '1.2':'20'} 532 * @arkts 1.1&1.2 533 */ 534 driverName: string; 535 536 /** 537 * Driver version. 538 * 539 * @type { string } 540 * @syscap SystemCapability.Driver.ExternalDevice 541 * @systemapi 542 * @since arkts {'1.1':'12', '1.2':'20'} 543 * @arkts 1.1&1.2 544 */ 545 driverVersion: string; 546 547 /** 548 * Driver size. 549 * 550 * @type { string } 551 * @syscap SystemCapability.Driver.ExternalDevice 552 * @systemapi 553 * @since arkts {'1.1':'12', '1.2':'20'} 554 * @arkts 1.1&1.2 555 */ 556 driverSize: string; 557 558 /** 559 * Driver description. 560 * 561 * @type { string } 562 * @syscap SystemCapability.Driver.ExternalDevice 563 * @systemapi 564 * @since arkts {'1.1':'12', '1.2':'20'} 565 * @arkts 1.1&1.2 566 */ 567 description: string; 568 } 569 570 /** 571 * Represents the USB driver information. 572 * 573 * @typedef USBDriverInfo 574 * @extends DriverInfo 575 * @syscap SystemCapability.Driver.ExternalDevice 576 * @systemapi 577 * @since arkts {'1.1':'12', '1.2':'20'} 578 * @arkts 1.1&1.2 579 */ 580 interface USBDriverInfo extends DriverInfo { 581 /** 582 * IDs of supported products. 583 * 584 * @type { Array<int> } 585 * @syscap SystemCapability.Driver.ExternalDevice 586 * @systemapi 587 * @since arkts {'1.1':'12', '1.2':'20'} 588 * @arkts 1.1&1.2 589 */ 590 productIdList: Array<int>; 591 592 /** 593 * IDs of supported vendors. 594 * 595 * @type { Array<int> } 596 * @syscap SystemCapability.Driver.ExternalDevice 597 * @systemapi 598 * @since arkts {'1.1':'12', '1.2':'20'} 599 * @arkts 1.1&1.2 600 */ 601 vendorIdList: Array<int>; 602 } 603} 604 605export default deviceManager; 606