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 10 30 */ 31declare namespace deviceManager { 32 /** 33 * Query the external device list. 34 * 35 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 36 * @param { number } busType - The bus type of device to be queried. 37 * @returns { Array<Readonly<Device>> } External device list. 38 * @throws { BusinessError } 201 - The permission check failed. 39 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception or busType parameter error. 40 * @syscap SystemCapability.Driver.ExternalDevice 41 * @since 10 42 */ 43 function queryDevices(busType?: number): Array<Readonly<Device>>; 44 45 /** 46 * Bind the device based on the device information returned by queryDevices(). 47 * 48 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 49 * @param { number } deviceId - Device id on the device list returned by queryDevices(). 50 * @param { AsyncCallback<number> } onDisconnect - Callback is invoked when device is disconnected after bind 51 * success. 52 * @param { AsyncCallback<{deviceId: number; remote: rpc.IRemoteObject;}> } callback - Indicates the bind result 53 * including device ID and remote object. 54 * @throws { BusinessError } 201 - The permission check failed. 55 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 56 * 3.Parameter verification failed. 57 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception. 58 * @syscap SystemCapability.Driver.ExternalDevice 59 * @since 10 60 */ 61 function bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>, 62 callback: AsyncCallback<{deviceId: number; remote: rpc.IRemoteObject;}>): void; 63 64 /** 65 * Bind the device based on the device information returned by queryDevices(). 66 * 67 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 68 * @param { number } deviceId - Device id on the device list returned by queryDevices(). 69 * @param { AsyncCallback<number> } onDisconnect - Callback is invoked when device is disconnected after bind 70 * success. 71 * @param { AsyncCallback<RemoteDeviceDriver> } callback - Indicates the bind result including device ID and 72 * remote object. 73 * @throws { BusinessError } 201 - The permission check failed. 74 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 75 * 3.Parameter verification failed. 76 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception. 77 * @syscap SystemCapability.Driver.ExternalDevice 78 * @since 11 79 */ 80 function bindDeviceDriver(deviceId: number, onDisconnect: AsyncCallback<number>, 81 callback: AsyncCallback<RemoteDeviceDriver>): void; 82 83 /** 84 * Bind the device based on the device information returned by queryDevices(). 85 * 86 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 87 * @param { number } deviceId - Device id on the device list returned by queryDevices(). 88 * @param { AsyncCallback<number> } onDisconnect - Callback is invoked when device is disconnected after bind 89 * success. 90 * @returns { Promise<{deviceId: number; remote: rpc.IRemoteObject;}> } Indicates the bind result including device 91 * ID and remote object. 92 * @throws { BusinessError } 201 - The permission check failed. 93 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 94 * 3.Parameter verification failed. 95 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception. 96 * @syscap SystemCapability.Driver.ExternalDevice 97 * @since 10 98 */ 99 function bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<{deviceId: number; 100 remote: rpc.IRemoteObject;}>; 101 102 /** 103 * Bind the device based on the device information returned by queryDevices(). 104 * 105 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 106 * @param { number } deviceId - Device id on the device list returned by queryDevices(). 107 * @param { AsyncCallback<number> } onDisconnect - Callback is invoked when device is disconnected after bind 108 * success. 109 * @returns { Promise<RemoteDeviceDriver> } Indicates the bind result including device ID and remote object. 110 * @throws { BusinessError } 201 - The permission check failed. 111 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 112 * 3.Parameter verification failed. 113 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception. 114 * @syscap SystemCapability.Driver.ExternalDevice 115 * @since 11 116 */ 117 function bindDeviceDriver(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<RemoteDeviceDriver>; 118 119 /** 120 * Unbind the device based on the device information returned by queryDevices(). 121 * 122 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 123 * @param { number } deviceId - Device id on the device list returned by queryDevices(). 124 * @param { AsyncCallback<number> } callback - Indicates the unbind result invoked when unbind is finished. 125 * @throws { BusinessError } 201 - The permission check failed. 126 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 127 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception. 128 * @syscap SystemCapability.Driver.ExternalDevice 129 * @since 10 130 */ 131 function unbindDevice(deviceId: number, callback: AsyncCallback<number>): void; 132 133 /** 134 * Unbind the device based on the device information returned by queryDevices(). 135 * 136 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 137 * @param { number } deviceId - Device id on the device list returned by queryDevices(). 138 * @returns { Promise<number> } - Indicates the unbind result invoked when unbind is finished. 139 * @throws { BusinessError } 201 - The permission check failed. 140 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 141 * 3.Parameter verification failed. 142 * @throws { BusinessError } 22900001 - ExternalDeviceManager service exception. 143 * @syscap SystemCapability.Driver.ExternalDevice 144 * @since 10 145 */ 146 function unbindDevice(deviceId: number): Promise<number>; 147 148 /** 149 * Queries external device information. 150 * 151 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 152 * @param { number } deviceId - ID of device to query. 153 * @returns { Array<Readonly<DeviceInfo>> } Device information obtained. 154 * @throws { BusinessError } 201 - The permission check failed. 155 * @throws { BusinessError } 202 - Permission denied. A non-system application cannot call a system API. 156 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types. 157 * @throws { BusinessError } 26300001 - ExternalDeviceManager service exception. 158 * @syscap SystemCapability.Driver.ExternalDevice 159 * @systemapi 160 * @since 12 161 */ 162 function queryDeviceInfo(deviceId?: number): Array<Readonly<DeviceInfo>>; 163 164 /** 165 * Queries driver information. 166 * 167 * @permission ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER 168 * @param { string } driverUid - Unique identifier of driver query. 169 * @returns { Array<Readonly<DriverInfo>> } Driver information obtained. 170 * @throws { BusinessError } 201 - The permission check failed. 171 * @throws { BusinessError } 202 - Permission denied. A non-system application cannot call a system API. 172 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types. 173 * @throws { BusinessError } 26300001 - ExternalDeviceManager service exception. 174 * @syscap SystemCapability.Driver.ExternalDevice 175 * @systemapi 176 * @since 12 177 */ 178 function queryDriverInfo(driverUid?: string): Array<Readonly<DriverInfo>>; 179 180 /** 181 * Enumerates the bus types. 182 * 183 * @enum { number } 184 * @syscap SystemCapability.Driver.ExternalDevice 185 * @since 10 186 */ 187 export enum BusType { 188 /** 189 * USB device type 190 * 191 * @syscap SystemCapability.Driver.ExternalDevice 192 * @since 10 193 */ 194 USB = 1, 195 } 196 197 /** 198 * Represents a device. 199 * 200 * @typedef Device 201 * @syscap SystemCapability.Driver.ExternalDevice 202 * @since 10 203 */ 204 interface Device { 205 /** 206 * Bus type of the device. 207 * 208 * @type { BusType } 209 * @syscap SystemCapability.Driver.ExternalDevice 210 * @since 10 211 */ 212 busType: BusType; 213 214 /** 215 * Device ID. 216 * 217 * @type { number } 218 * @syscap SystemCapability.Driver.ExternalDevice 219 * @since 10 220 */ 221 deviceId: number; 222 223 /** 224 * Description of the device. 225 * 226 * @type { string } 227 * @syscap SystemCapability.Driver.ExternalDevice 228 * @since 10 229 */ 230 description: string; 231 } 232 233 /** 234 * Represents a USB device. 235 * 236 * @typedef USBDevice 237 * @extends Device 238 * @syscap SystemCapability.Driver.ExternalDevice 239 * @since 10 240 */ 241 interface USBDevice extends Device { 242 /** 243 * Vendor ID. 244 * 245 * @type { number } 246 * @syscap SystemCapability.Driver.ExternalDevice 247 * @since 10 248 */ 249 vendorId: number; 250 251 /** 252 * Product ID. 253 * 254 * @type { number } 255 * @syscap SystemCapability.Driver.ExternalDevice 256 * @since 10 257 */ 258 productId: number; 259 } 260 261 /** 262 * Driver of the remote device bound with <b>deviceId</b>. 263 * 264 * @typedef RemoteDeviceDriver 265 * @syscap SystemCapability.Driver.ExternalDevice 266 * @since 11 267 */ 268 interface RemoteDeviceDriver { 269 /** 270 * Device ID. 271 * 272 * @type { number } 273 * @syscap SystemCapability.Driver.ExternalDevice 274 * @since 11 275 */ 276 deviceId: number; 277 278 /** 279 * Remote driver object. 280 * 281 * @type { rpc.IRemoteObject } 282 * @syscap SystemCapability.Driver.ExternalDevice 283 * @since 11 284 */ 285 remote: rpc.IRemoteObject; 286 } 287 288 /** 289 * Represents information about a device interface descriptor. 290 * 291 * @typedef USBInterfaceDesc 292 * @syscap SystemCapability.Driver.ExternalDevice 293 * @systemapi 294 * @since 12 295 */ 296 interface USBInterfaceDesc { 297 /** 298 * Interface number. 299 * 300 * @type { number } 301 * @syscap SystemCapability.Driver.ExternalDevice 302 * @systemapi 303 * @since 12 304 */ 305 bInterfaceNumber: number; 306 307 /** 308 * Interface class code. 309 * 310 * @type { number } 311 * @syscap SystemCapability.Driver.ExternalDevice 312 * @systemapi 313 * @since 12 314 */ 315 bClass: number; 316 317 /** 318 * Interface subclass code. 319 * 320 * @type { number } 321 * @syscap SystemCapability.Driver.ExternalDevice 322 * @systemapi 323 * @since 12 324 */ 325 bSubClass: number; 326 327 /** 328 * Interface protocol. 329 * 330 * @type { number } 331 * @syscap SystemCapability.Driver.ExternalDevice 332 * @systemapi 333 * @since 12 334 */ 335 bProtocol: number; 336 } 337 338 339 /** 340 * Represents the device information. 341 * 342 * @typedef DeviceInfo 343 * @syscap SystemCapability.Driver.ExternalDevice 344 * @systemapi 345 * @since 12 346 */ 347 interface DeviceInfo { 348 /** 349 * Device ID. 350 * 351 * @type { number } 352 * @syscap SystemCapability.Driver.ExternalDevice 353 * @systemapi 354 * @since 12 355 */ 356 deviceId: number; 357 358 /** 359 * Whether the device has a matched driver. 360 * 361 * @type { boolean } 362 * @syscap SystemCapability.Driver.ExternalDevice 363 * @systemapi 364 * @since 12 365 */ 366 isDriverMatched: boolean; 367 368 /** 369 * Unique identifier of the driver. 370 * 371 * @type { ?string } 372 * @syscap SystemCapability.Driver.ExternalDevice 373 * @systemapi 374 * @since 12 375 */ 376 driverUid?: string; 377 } 378 379 /** 380 * Represents the USB device information. 381 * 382 * @typedef USBDeviceInfo 383 * @extends DeviceInfo 384 * @syscap SystemCapability.Driver.ExternalDevice 385 * @systemapi 386 * @since 12 387 */ 388 interface USBDeviceInfo extends DeviceInfo { 389 /** 390 * Vendor ID. 391 * 392 * @type { number } 393 * @syscap SystemCapability.Driver.ExternalDevice 394 * @systemapi 395 * @since 12 396 */ 397 vendorId: number; 398 399 /** 400 * Product ID. 401 * 402 * @type { number } 403 * @syscap SystemCapability.Driver.ExternalDevice 404 * @systemapi 405 * @since 12 406 */ 407 productId: number; 408 409 /** 410 * List of USB interface descriptors. 411 * 412 * @type { Array<Readonly<USBInterfaceDesc>> } 413 * @syscap SystemCapability.Driver.ExternalDevice 414 * @systemapi 415 * @since 12 416 */ 417 interfaceDescList: Array<Readonly<USBInterfaceDesc>>; 418 } 419 420 /** 421 * Represents the driver information. 422 * 423 * @typedef DriverInfo 424 * @syscap SystemCapability.Driver.ExternalDevice 425 * @systemapi 426 * @since 12 427 */ 428 interface DriverInfo { 429 /** 430 * Bus type of the device. 431 * 432 * @type { BusType } 433 * @syscap SystemCapability.Driver.ExternalDevice 434 * @systemapi 435 * @since 12 436 */ 437 busType: BusType; 438 439 /** 440 * Unique identifier of the driver. 441 * 442 * @type { string } 443 * @syscap SystemCapability.Driver.ExternalDevice 444 * @systemapi 445 * @since 12 446 */ 447 driverUid: string; 448 449 /** 450 * Driver name. 451 * 452 * @type { string } 453 * @syscap SystemCapability.Driver.ExternalDevice 454 * @systemapi 455 * @since 12 456 */ 457 driverName: string; 458 459 /** 460 * Driver version. 461 * 462 * @type { string } 463 * @syscap SystemCapability.Driver.ExternalDevice 464 * @systemapi 465 * @since 12 466 */ 467 driverVersion: string; 468 469 /** 470 * Driver size. 471 * 472 * @type { string } 473 * @syscap SystemCapability.Driver.ExternalDevice 474 * @systemapi 475 * @since 12 476 */ 477 driverSize: string; 478 479 /** 480 * Driver description. 481 * 482 * @type { string } 483 * @syscap SystemCapability.Driver.ExternalDevice 484 * @systemapi 485 * @since 12 486 */ 487 description: string; 488 } 489 490 /** 491 * Represents the USB driver information. 492 * 493 * @typedef USBDriverInfo 494 * @extends DriverInfo 495 * @syscap SystemCapability.Driver.ExternalDevice 496 * @systemapi 497 * @since 12 498 */ 499 interface USBDriverInfo extends DriverInfo { 500 /** 501 * IDs of supported products. 502 * 503 * @type { Array<number> } 504 * @syscap SystemCapability.Driver.ExternalDevice 505 * @systemapi 506 * @since 12 507 */ 508 productIdList: Array<number>; 509 510 /** 511 * IDs of supported vendors. 512 * 513 * @type { Array<number> } 514 * @syscap SystemCapability.Driver.ExternalDevice 515 * @systemapi 516 * @since 12 517 */ 518 vendorIdList: Array<number>; 519 } 520} 521 522export default deviceManager; 523