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 16import type { AsyncCallback } from './@ohos.base'; 17import type { Callback } from './@ohos.base'; 18 19/** 20 * Providers interfaces to create a {@link deviceManager} instances. 21 * 22 * @namespace distributedDeviceManager 23 * @syscap SystemCapability.DistributedHardware.DeviceManager 24 * @since 10 25 */ 26 27declare namespace distributedDeviceManager { 28 29 /** 30 * Basic description information of a distributed device. 31 * @interface DeviceBasicInfo 32 * @syscap SystemCapability.DistributedHardware.DeviceManager 33 * @since 10 34 */ 35 interface DeviceBasicInfo { 36 /** 37 * Device unique identifier, The actual value is the udid-hash confused with the appid based on sha256. 38 * @syscap SystemCapability.DistributedHardware.DeviceManager 39 * @since 10 40 */ 41 deviceId: string; 42 43 /** 44 * Device name. 45 * @syscap SystemCapability.DistributedHardware.DeviceManager 46 * @since 10 47 */ 48 deviceName: string; 49 50 /** 51 * Device type. Currently, only support the following device types: 52 * 12 - Indicates a smart pc. 53 * 14 - Indicates a smart phone. 54 * 17 - Indicates a smart pad. 55 * @syscap SystemCapability.DistributedHardware.DeviceManager 56 * @since 10 57 */ 58 deviceType: number; 59 60 /** 61 * Device network id. 62 * @syscap SystemCapability.DistributedHardware.DeviceManager 63 * @since 10 64 */ 65 networkId?: string; 66 } 67 68 /** 69 * The state of the nearby devices. 70 * @enum { DeviceStateChange } 71 * @syscap SystemCapability.DistributedHardware.DeviceManager 72 * @since 10 73 */ 74 enum DeviceStateChange { 75 /** 76 * This state indicates the device is online but the state is unknown,The distributed function cannot used until 77 * state changes to AVAILABLE. 78 * @syscap SystemCapability.DistributedHardware.DeviceManager 79 * @since 10 80 */ 81 UNKNOWN = 0, 82 83 /** 84 * This state indicates the device has been synchronized to the database, Now the distributed function can be used. 85 * @syscap SystemCapability.DistributedHardware.DeviceManager 86 * @since 10 87 */ 88 AVAILABLE = 1, 89 90 /** 91 * This state indicates the device is offline. 92 * @syscap SystemCapability.DistributedHardware.DeviceManager 93 * @since 10 94 */ 95 UNAVAILABLE = 2, 96 } 97 98 /** 99 * Creates an {@code DeviceManager} instance. 100 * 101 * To manage devices, you must first call this method to obtain a {@code DeviceManager} instance and then 102 * use this instance to call other device management methods. 103 * 104 * @param { string } bundleName - Indicates the bundle name of the application. 105 * @returns { DeviceManager } - Return the DeviceManager object. 106 * @throws { BusinessError } 401 - Input parameter error. 107 * @syscap SystemCapability.DistributedHardware.DeviceManager 108 * @since 10 109 */ 110 function createDeviceManager(bundleName: string): DeviceManager; 111 112 /** 113 * Releases the {@code DeviceManager} instance that is no longer used. 114 * 115 * @permission ohos.permission.DISTRIBUTED_DATASYNC 116 * @param { DeviceManager } deviceManager - Indicates the {@code DeviceManager} instance. 117 * @throws { BusinessError } 201 - User permission verify failed. 118 * @throws { BusinessError } 401 - Input parameter error. 119 * @throws { BusinessError } 11600101 - Failed to execute the function. 120 * @syscap SystemCapability.DistributedHardware.DeviceManager 121 * @since 10 122 */ 123 function releaseDeviceManager(deviceManager: DeviceManager): void; 124 125 /** 126 * Provides methods for managing devices. 127 * 128 * @interface DeviceManager 129 * @syscap SystemCapability.DistributedHardware.DeviceManager 130 * @since 10 131 */ 132 interface DeviceManager { 133 134 /** 135 * Get a list of available devices. This interface query all authorized and connectable devices. 136 * 137 * @permission ohos.permission.DISTRIBUTED_DATASYNC 138 * @returns { Array<DeviceBasicInfo> } - Returns a list of available devices. 139 * @throws { BusinessError } 201 - User permission verify failed. 140 * @throws { BusinessError } 401 - Input parameter error. 141 * @throws { BusinessError } 11600101 - Failed to execute the function. 142 * @syscap SystemCapability.DistributedHardware.DeviceManager 143 * @since 10 144 */ 145 getAvailableDeviceListSync(): Array<DeviceBasicInfo>; 146 147 /** 148 * Get a list of available devices. This interface query all authorized and connectable devices. 149 * 150 * @permission ohos.permission.DISTRIBUTED_DATASYNC 151 * @param { AsyncCallback<Array<DeviceBasicInfo>> } callback - Indicates the callback to be 152 * invoked upon getAvailableDeviceList. 153 * @returns Returns a list of available devices. 154 * @throws { BusinessError } 201 - User permission verify failed. 155 * @throws { BusinessError } 11600101 - Failed to execute the function. 156 * @syscap SystemCapability.DistributedHardware.DeviceManager 157 * @since 10 158 */ 159 getAvailableDeviceList(callback: AsyncCallback<Array<DeviceBasicInfo>>): void; 160 161 /** 162 * Get a list of available devices. This interface query all authorized and connectable devices. 163 * 164 * @permission ohos.permission.DISTRIBUTED_DATASYNC 165 * @returns { Promise<Array<DeviceBasicInfo>> } - Returns a list of available devices. 166 * @throws { BusinessError } 201 - User permission verify failed. 167 * @throws { BusinessError } 11600101 - Failed to execute the function. 168 * @syscap SystemCapability.DistributedHardware.DeviceManager 169 * @since 10 170 */ 171 getAvailableDeviceList(): Promise<Array<DeviceBasicInfo>>; 172 173 /** 174 * Get the network id of the local device. 175 * 176 * @permission ohos.permission.DISTRIBUTED_DATASYNC 177 * @returns { string } - Returns local device network id. 178 * @throws { BusinessError } 201 - User permission verify failed. 179 * @throws { BusinessError } 11600101 - Failed to execute the function. 180 * @syscap SystemCapability.DistributedHardware.DeviceManager 181 * @since 10 182 */ 183 getLocalDeviceNetworkId(): string; 184 185 /** 186 * Get the device name of the local device. 187 * 188 * @permission ohos.permission.DISTRIBUTED_DATASYNC 189 * @returns { string } - Returns local device name. 190 * @throws { BusinessError } 201 - User permission verify failed. 191 * @throws { BusinessError } 11600101 - Failed to execute the function. 192 * @syscap SystemCapability.DistributedHardware.DeviceManager 193 * @since 10 194 */ 195 getLocalDeviceName(): string; 196 197 /** 198 * Get the device type of the local device. 199 * 200 * @permission ohos.permission.DISTRIBUTED_DATASYNC 201 * @returns { number } - Returns local device type. 202 * @throws { BusinessError } 201 - User permission verify failed. 203 * @throws { BusinessError } 11600101 - Failed to execute the function. 204 * @syscap SystemCapability.DistributedHardware.DeviceManager 205 * @since 10 206 */ 207 getLocalDeviceType(): number; 208 209 /** 210 * Get the device id of the local device. 211 * 212 * @permission ohos.permission.DISTRIBUTED_DATASYNC 213 * @returns { string } - Returns local device type. 214 * @throws { BusinessError } 201 - User permission verify failed. 215 * @throws { BusinessError } 11600101 - Failed to execute the function. 216 * @syscap SystemCapability.DistributedHardware.DeviceManager 217 * @since 10 218 */ 219 getLocalDeviceId(): string; 220 221 /** 222 * Get the device name by network id. 223 * 224 * @permission ohos.permission.DISTRIBUTED_DATASYNC 225 * @param { string } networkId - Device network id. 226 * @returns { string } - Returns device name. 227 * @throws { BusinessError } 201 - User permission verify failed. 228 * @throws { BusinessError } 401 - Input parameter error. 229 * @throws { BusinessError } 11600101 - Failed to execute the function. 230 * @syscap SystemCapability.DistributedHardware.DeviceManager 231 * @since 10 232 */ 233 getDeviceName(networkId: string): string; 234 235 /** 236 * Get the device type by network id. 237 * 238 * @permission ohos.permission.DISTRIBUTED_DATASYNC 239 * @param { string } networkId - Device network id. 240 * @returns { number } - Returns device type. 241 * @throws { BusinessError } 201 - User permission verify failed. 242 * @throws { BusinessError } 401 - Input parameter error. 243 * @throws { BusinessError } 11600101 - Failed to execute the function. 244 * @syscap SystemCapability.DistributedHardware.DeviceManager 245 * @since 10 246 */ 247 getDeviceType(networkId: string): number; 248 249 /** 250 * Start to discover nearby devices. 251 * 252 * @permission ohos.permission.DISTRIBUTED_DATASYNC 253 * @param { { [key: string]: Object } } discoverParam - Identifies the type of target discovered: 254 * discoverTargetType : 1 - Discovery target as a device by default, the value is 1. 255 * @param { { [key: string]: Object } } filterOptions - FilterOptions to filter discovery device. 256 * The type of filterOptions is map. The map are as follows: 257 * availableStatus: 0-1 - Discover devices only are credible, The value is 0 indicates device isn't credible; 258 * 0: Devices are offline, client need to bind the device by calling bindTarget() and then connect to it. 259 * 1: Devices already online, client can make connection. 260 * discoverDistance: 0-100 - Discover devices within a certain distance from the local, the unit is cm. 261 * authenticationStatus: 0-1 - Discover devices based on different authentication status: 262 * 0: Devices not authenticated. 263 1: Devices already authenticated. 264 * The value is 1 indicates device is trust. 265 * authorizationType: 0-2 - Discover devices based on different authorization type: 266 * 0: Devices authenticated based on temporary negotiated session key. 267 * 1: Devices authenticated based on the same account credential key. 268 * 2: Devices authenticated based on different account credential keys. 269 * @throws { BusinessError } 401 - Input parameter error. 270 * @throws { BusinessError } 201 - Permission verify failed. 271 * @throws { BusinessError } 11600104 - Discovery repeats. 272 * @throws { BusinessError } 11600101 - Failed to execute the function. 273 * @syscap SystemCapability.DistributedHardware.DeviceManager 274 * @since 10 275 */ 276 startDiscovering(discoverParam: { [key: string]: Object }, filterOptions?: { [key: string]: Object }): void; 277 278 /** 279 * Stop discovering nearby devices. 280 * 281 * @permission ohos.permission.DISTRIBUTED_DATASYNC 282 * @throws { BusinessError } 401 - Input parameter error. 283 * @throws { BusinessError } 201 - Permission verify failed. 284 * @throws { BusinessError } 11600104 - Stop discovery repeats. 285 * @throws { BusinessError } 11600101 - Failed to execute the function. 286 * @syscap SystemCapability.DistributedHardware.DeviceManager 287 * @since 10 288 */ 289 stopDiscovering(): void; 290 291 /** 292 * Bind the specified target. 293 * 294 * @permission ohos.permission.DISTRIBUTED_DATASYNC 295 * @param { string } deviceId - id of device to bind. 296 * @param { { [key: string]: Object } } bindParam - parameters of device to bind, The parameter type is map,such as: 297 * "bindType" : 1-4, - This value is type of bind, the values are as follows: 298 * 1 - The bind type is pin code . 299 * 2 - The bind type is QR code. 300 * 3 - The bind type is nfc. 301 * 4 - The bind type is no_interaction. 302 303 * "targetPkgName" : "xxxx", - The package name of binding target. 304 * "appName" : "xxxx", - The app name that try to bind the target. 305 * "appOperation" : "xxxx" - The reason why the app want to bind the target package. 306 * "customDescription" : "xxxx" - The detail description of the operation. 307 * @param { AsyncCallback<{deviceId: string}> } callback - indicates the callback to be invoked upon bindDevice. 308 * @throws { BusinessError } 401 - Input parameter error. 309 * @throws { BusinessError } 201 - Permission verify failed. 310 * @throws { BusinessError } 11600101 - Failed to execute the function. 311 * @throws { BusinessError } 11600103 - Bind invalid. 312 * @syscap SystemCapability.DistributedHardware.DeviceManager 313 * @since 10 314 */ 315 bindTarget(deviceId: string, bindParam: { [key: string]: Object }, callback: AsyncCallback<{deviceId: string}>): void; 316 317 /** 318 * Unbind the specified target. 319 * 320 * @permission ohos.permission.DISTRIBUTED_DATASYNC 321 * @param { string } deviceId - id of device to unbind 322 * @throws { BusinessError } 401 - Input parameter error. 323 * @throws { BusinessError } 201 - Permission verify failed. 324 * @throws { BusinessError } 11600101 - Failed to execute the function. 325 * @syscap SystemCapability.DistributedHardware.DeviceManager 326 * @since 10 327 */ 328 unbindTarget(deviceId: string): void; 329 330 /** 331 * The reply of ui operation from pin-code window, this interface can only be used by pin-code-hap of devicemanager. 332 * 333 * @permission ohos.permission.ACCESS_SERVICE_DM 334 * @param { number } action - The reply action of user operation. 335 * @param { string } actionResult - Indicates the user operation result. 336 * @throws { BusinessError } 201 - Permission verify failed. 337 * @throws { BusinessError } 202 - The caller is not a system application. 338 * @throws { BusinessError } 401 - Input parameter error. 339 * @syscap SystemCapability.DistributedHardware.DeviceManager 340 * @systemapi this method can be used only by system applications. 341 * @since 10 342 */ 343 replyUiAction(action: number, actionResult: string): void; 344 345 /** 346 * Register a device state callback so that the application can be notified upon device state changes based on 347 * the application bundle name. 348 * 349 * @permission ohos.permission.DISTRIBUTED_DATASYNC 350 * @param { 'deviceStateChange' } type - Device state change. 351 * @param { Callback<{ action: DeviceStateChange, device: DeviceBasicInfo }> } callback 352 * Indicates the device state callback to register. 353 * @throws { BusinessError } 201 - Permission verify failed. 354 * @throws { BusinessError } 401 - Input parameter error. 355 * @syscap SystemCapability.DistributedHardware.DeviceManager 356 * @since 10 357 */ 358 on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChange, device: DeviceBasicInfo }>): void; 359 360 /** 361 * UnRegister device state callback based on the application bundle name. 362 * 363 * @permission ohos.permission.DISTRIBUTED_DATASYNC 364 * @param { 'deviceStateChange' } type - Device state change. 365 * @param { Callback<{ action: DeviceStateChange, device: DeviceBasicInfo }> } callback 366 * Indicates the device state callback to unregister. 367 * @throws { BusinessError } 201 - Permission verify failed. 368 * @throws { BusinessError } 401 - Input parameter error. 369 * @syscap SystemCapability.DistributedHardware.DeviceManager 370 * @since 10 371 */ 372 off(type: 'deviceStateChange', callback?: Callback<{ action: DeviceStateChange, device: DeviceBasicInfo }>): void; 373 374 /** 375 * Register a device discovery result callback so that the application can be notified when discovery success. 376 * 377 * @permission ohos.permission.DISTRIBUTED_DATASYNC 378 * @param { 'discoverSuccess' } type - Successfully discovered device. 379 * @param { Callback<{ subscribeId: number, device: DeviceBasicInfo }> } callback 380 * Indicates the device discovery callback to register. 381 * @throws { BusinessError } 201 - Permission verify failed. 382 * @throws { BusinessError } 401 - Input parameter error. 383 * @syscap SystemCapability.DistributedHardware.DeviceManager 384 * @since 10 385 */ 386 on(type: 'discoverSuccess', callback: Callback<{ device: DeviceBasicInfo }>): void; 387 388 /** 389 * UnRegister the device discovery result callback. 390 * 391 * @permission ohos.permission.DISTRIBUTED_DATASYNC 392 * @param { 'discoverSuccess' } type - Successfully discovered device. 393 * @param { Callback<{ subscribeId: number, device: DeviceBasicInfo }> } callback 394 * Indicates the device discovery callback to unregister. 395 * @throws { BusinessError } 201 - Permission verify failed. 396 * @throws { BusinessError } 401 - Input parameter error. 397 * @syscap SystemCapability.DistributedHardware.DeviceManager 398 * @since 10 399 */ 400 off(type: 'discoverSuccess', callback?: Callback<{ device: DeviceBasicInfo }>): void; 401 402 /** 403 * Register a device name change callback so that the application can be notified when discovery success. 404 * 405 * @permission ohos.permission.DISTRIBUTED_DATASYNC 406 * @param { 'deviceNameChange' } type - Changed device name. 407 * @param { Callback<{ deviceName: string }> } callback - Indicates the device name change callback to register. 408 * @throws { BusinessError } 201 - Permission verify failed. 409 * @throws { BusinessError } 401 - Input parameter error. 410 * @syscap SystemCapability.DistributedHardware.DeviceManager 411 * @since 10 412 */ 413 on(type: 'deviceNameChange', callback: Callback<{ deviceName: string }>): void; 414 415 /** 416 * UnRegister the device name change result callback. 417 * 418 * @permission ohos.permission.DISTRIBUTED_DATASYNC 419 * @param { 'deviceNameChange' } type - Changed device name. 420 * @param { Callback<{ deviceName: string }> } callback - Indicates the device name change callback to unregister. 421 * @throws { BusinessError } 201 - Permission verify failed. 422 * @throws { BusinessError } 401 - Input parameter error. 423 * @syscap SystemCapability.DistributedHardware.DeviceManager 424 * @since 10 425 */ 426 off(type: 'deviceNameChange', callback?: Callback<{ deviceName: string }>): void; 427 428 /** 429 * Register a device discovery result callback so that the application can be notified when discover failed. 430 * 431 * @permission ohos.permission.DISTRIBUTED_DATASYNC 432 * @param { 'discoverFailure' } type - Discovery Device Failure. 433 * @param { Callback<{ subscribeId: number, reason: number }> } callback 434 * Indicates the device found result callback to register. 435 * @throws { BusinessError } 201 - Permission verify failed. 436 * @throws { BusinessError } 401 - Input parameter error. 437 * @syscap SystemCapability.DistributedHardware.DeviceManager 438 * @since 10 439 */ 440 on(type: 'discoverFailure', callback: Callback<{ reason: number }>): void; 441 442 /** 443 * UnRegister the device discovery result callback. 444 * 445 * @permission ohos.permission.DISTRIBUTED_DATASYNC 446 * @param { 'discoverFailure' } type - Discovery Device Failure. 447 * @param { Callback<{ subscribeId: number, reason: number }> } callback 448 * Indicates the device found result callback to unregister. 449 * @throws { BusinessError } 201 - Permission verify failed. 450 * @throws { BusinessError } 401 - Input parameter error. 451 * @syscap SystemCapability.DistributedHardware.DeviceManager 452 * @since 10 453 */ 454 off(type: 'discoverFailure', callback?: Callback<{ reason: number }>): void; 455 456 /** 457 * Register a serviceError callback so that the application can be notified when devicemanager service died 458 * 459 * @permission ohos.permission.DISTRIBUTED_DATASYNC 460 * @param { 'serviceDie' } type - Service death. 461 * @param { Callback<{}> } callback - Indicates the service error callback to register. 462 * @throws { BusinessError } 201 - Permission verify failed. 463 * @throws { BusinessError } 401 - Input parameter error. 464 * @syscap SystemCapability.DistributedHardware.DeviceManager 465 * @since 10 466 */ 467 on(type: 'serviceDie', callback?: Callback<{}>): void; 468 469 /** 470 * UnRegister the service error callback. 471 * 472 * @permission ohos.permission.DISTRIBUTED_DATASYNC 473 * @param { 'serviceDie' } type - Service death. 474 * @param { Callback<{}> } callback - Indicates the service error callback to unregister. 475 * @throws { BusinessError } 201 - Permission verify failed. 476 * @throws { BusinessError } 401 - Input parameter error. 477 * @syscap SystemCapability.DistributedHardware.DeviceManager 478 * @since 10 479 */ 480 off(type: 'serviceDie', callback?: Callback<{}>): void; 481 482 /** 483 * Register a callback from deviceManager service so that the devicemanager ui can be notified when uiStateChanges. 484 * 485 * @permission ohos.permission.ACCESS_SERVICE_DM 486 * @param { 'replyResult' } type - Ui reply result to register. 487 * @param { Callback<{ param: string }> } callback - Indicates the devicemanager ui state to register. 488 * @throws { BusinessError } 401 - Input parameter error. 489 * @throws { BusinessError } 202 - The caller is not a system application. 490 * @syscap SystemCapability.DistributedHardware.DeviceManager 491 * @systemapi this method can be used only by system applications. 492 * @since 10 493 */ 494 on(type: 'replyResult', callback: Callback<{ param: string }>): void; 495 496 /** 497 * Unregister uiStateChange, this interface can only be used by devicemanager ui. 498 * 499 * @permission ohos.permission.ACCESS_SERVICE_DM 500 * @param { 'replyResult' } type - Ui reply result to unregister. 501 * @param { Callback<{ param: string }> } callback - Indicates the devicemanager ui state to unregister. 502 * @throws { BusinessError } 401 - Input parameter error. 503 * @throws { BusinessError } 202 - The caller is not a system application. 504 * @syscap SystemCapability.DistributedHardware.DeviceManager 505 * @systemapi this method can be used only by system applications. 506 * @since 10 507 */ 508 off(type: 'replyResult', callback?: Callback<{ param: string }>): void; 509 } 510} 511 512export default distributedDeviceManager;