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