1/* 2 * Copyright (c) 2022-2024 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 AbilityKit 19 */ 20 21import { AbilityResult } from './ability/abilityResult'; 22import { AsyncCallback } from './@ohos.base'; 23import { Configuration } from './@ohos.app.ability.Configuration'; 24import Context from './application/Context'; 25import { AbilityRunningInfo as _AbilityRunningInfo } from './application/AbilityRunningInfo'; 26import { ExtensionRunningInfo as _ExtensionRunningInfo } from './application/ExtensionRunningInfo'; 27import { ElementName } from './bundleManager/ElementName'; 28import * as _AbilityForegroundStateObserver from './application/AbilityForegroundStateObserver'; 29import * as _AbilityStateData from './application/AbilityStateData'; 30 31/** 32 * The class of an ability manager. 33 * 34 * @namespace abilityManager 35 * @syscap SystemCapability.Ability.AbilityRuntime.Core 36 * @since 9 37 */ 38declare namespace abilityManager { 39 /** 40 * Enum for the ability state. 41 * 42 * @enum { number } 43 * @syscap SystemCapability.Ability.AbilityRuntime.Core 44 * @since 14 45 */ 46 export enum AbilityState { 47 /** 48 * Ability is initialized. 49 * 50 * @syscap SystemCapability.Ability.AbilityRuntime.Core 51 * @since 14 52 */ 53 INITIAL = 0, 54 55 /** 56 * Ability is in the state of getting focus. 57 * 58 * @syscap SystemCapability.Ability.AbilityRuntime.Core 59 * @since 14 60 */ 61 FOCUS = 2, 62 63 /** 64 * Ability is in the foreground state. 65 * 66 * @syscap SystemCapability.Ability.AbilityRuntime.Core 67 * @since 14 68 */ 69 FOREGROUND = 9, 70 71 /** 72 * Ability is in the background state. 73 * 74 * @syscap SystemCapability.Ability.AbilityRuntime.Core 75 * @since 14 76 */ 77 BACKGROUND = 10, 78 79 /** 80 * Ability is in the process of scheduling at the foreground. 81 * 82 * @syscap SystemCapability.Ability.AbilityRuntime.Core 83 * @since 14 84 */ 85 FOREGROUNDING = 11, 86 87 /** 88 * Ability is in the process of scheduling in the background. 89 * 90 * @syscap SystemCapability.Ability.AbilityRuntime.Core 91 * @since 14 92 */ 93 BACKGROUNDING = 12 94 } 95 96 /** 97 * Enum for the user status. 98 * 99 * @enum { number } 100 * @syscap SystemCapability.Ability.AbilityRuntime.Core 101 * @systemapi 102 * @stagemodelonly 103 * @since 12 104 */ 105 export enum UserStatus { 106 /** 107 * Indicates the status of the operation that the user clicks to terminate. 108 * 109 * @syscap SystemCapability.Ability.AbilityRuntime.Core 110 * @systemapi 111 * @stagemodelonly 112 * @since 12 113 */ 114 ASSERT_TERMINATE = 0, 115 116 /** 117 * Indicates the status of the operation that the user clicks to continue. 118 * 119 * @syscap SystemCapability.Ability.AbilityRuntime.Core 120 * @systemapi 121 * @stagemodelonly 122 * @since 12 123 */ 124 ASSERT_CONTINUE = 1, 125 126 /** 127 * Indicates the status of the operation that the user clicks to retry. 128 * 129 * @syscap SystemCapability.Ability.AbilityRuntime.Core 130 * @systemapi 131 * @stagemodelonly 132 * @since 12 133 */ 134 ASSERT_RETRY = 2 135 } 136 137 /** 138 * The class of an embedded atomic service open rule. 139 * 140 * @typedef AtomicServiceStartupRule 141 * @syscap SystemCapability.Ability.AbilityRuntime.Core 142 * @systemapi 143 * @stagemodelonly 144 * @since 18 145 */ 146 export interface AtomicServiceStartupRule { 147 /** 148 * the flag indicated whether openning atomic service is allowed. 149 * 150 * @type { boolean } 151 * @syscap SystemCapability.Ability.AbilityRuntime.Core 152 * @systemapi 153 * @since 18 154 */ 155 isOpenAllowed: boolean; 156 157 /** 158 * the flag indicated whether embedded atomic service is allowed. 159 * 160 * @type { boolean } 161 * @syscap SystemCapability.Ability.AbilityRuntime.Core 162 * @systemapi 163 * @since 18 164 */ 165 isEmbeddedAllowed: boolean; 166 } 167 168 /** 169 * Register Ability foreground or background state observer. 170 * 171 * @permission ohos.permission.RUNNING_STATE_OBSERVER 172 * @param { 'abilityForegroundState' } type - ability foreground or background state. 173 * @param { AbilityForegroundStateObserver } observer - The ability foreground state observer. 174 * @throws { BusinessError } 201 - Permission denied. 175 * @throws { BusinessError } 202 - Not system application. 176 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 177 * 2. Incorrect parameter types; 3. Parameter verification failed. 178 * @throws { BusinessError } 16000050 - Internal error. 179 * @syscap SystemCapability.Ability.AbilityRuntime.Core 180 * @systemapi 181 * @since 11 182 */ 183 function on(type: 'abilityForegroundState', observer: AbilityForegroundStateObserver): void; 184 185 /** 186 * Unregister Ability foreground or background state observer. 187 * 188 * @permission ohos.permission.RUNNING_STATE_OBSERVER 189 * @param { 'abilityForegroundState' } type - ability foreground or background state. 190 * @param { AbilityForegroundStateObserver } [observer] - The ability foreground state observer. 191 * @throws { BusinessError } 201 - Permission denied. 192 * @throws { BusinessError } 202 - Not system application. 193 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 194 * 2. Incorrect parameter types; 3. Parameter verification failed. 195 * @throws { BusinessError } 16000050 - Internal error. 196 * @syscap SystemCapability.Ability.AbilityRuntime.Core 197 * @systemapi 198 * @since 11 199 */ 200 function off(type: 'abilityForegroundState', observer?: AbilityForegroundStateObserver): void; 201 202 /** 203 * Updates the configuration by modifying the configuration. 204 * 205 * @permission ohos.permission.UPDATE_CONFIGURATION 206 * @param { Configuration } config - Indicates the new configuration. 207 * @param { AsyncCallback<void> } callback - The callback of updateConfiguration. 208 * @throws { BusinessError } 201 - Permission denied. 209 * @throws { BusinessError } 202 - Not system application. 210 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 211 * 2. Incorrect parameter types; 3. Parameter verification failed. 212 * @throws { BusinessError } 16000050 - Internal error. 213 * @syscap SystemCapability.Ability.AbilityRuntime.Core 214 * @systemapi 215 * @since 9 216 */ 217 function updateConfiguration(config: Configuration, callback: AsyncCallback<void>): void; 218 219 /** 220 * Updates the configuration by modifying the configuration. 221 * 222 * @permission ohos.permission.UPDATE_CONFIGURATION 223 * @param { Configuration } config - Indicates the new configuration. 224 * @returns { Promise<void> } The promise returned by the function. 225 * @throws { BusinessError } 201 - Permission denied. 226 * @throws { BusinessError } 202 - Not system application. 227 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 228 * 2. Incorrect parameter types; 3. Parameter verification failed. 229 * @throws { BusinessError } 16000050 - Internal error. 230 * @syscap SystemCapability.Ability.AbilityRuntime.Core 231 * @systemapi 232 * @since 9 233 */ 234 function updateConfiguration(config: Configuration): Promise<void>; 235 236 /** 237 * If you apply for permission, you can obtain information about all abilities. If you do not apply, you can only 238 * obtain information about the current ability. 239 * 240 * @permission ohos.permission.GET_RUNNING_INFO 241 * @returns { Promise<Array<AbilityRunningInfo>> } Returns the array of AbilityRunningInfo. 242 * @throws { BusinessError } 16000050 - Internal error. 243 * @syscap SystemCapability.Ability.AbilityRuntime.Core 244 * @since 14 245 */ 246 function getAbilityRunningInfos(): Promise<Array<AbilityRunningInfo>>; 247 248 /** 249 * If you apply for permission, you can obtain information about all abilities. If you do not apply, you can only 250 * obtain information about the current ability. 251 * 252 * @permission ohos.permission.GET_RUNNING_INFO 253 * @param { AsyncCallback<Array<AbilityRunningInfo>> } callback - The callback is used to return the array of 254 * AbilityRunningInfo. 255 * @throws { BusinessError } 202 - Not system application. 256 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 257 * 2. Incorrect parameter types; 3. Parameter verification failed. 258 * @throws { BusinessError } 16000050 - Internal error. 259 * @syscap SystemCapability.Ability.AbilityRuntime.Core 260 * @systemapi 261 * @since 9 262 */ 263 function getAbilityRunningInfos(callback: AsyncCallback<Array<AbilityRunningInfo>>): void; 264 265 /** 266 * If you apply for permission, you can obtain information about all extensions. If you do not apply, you can only 267 * obtain information about the current extension. 268 * 269 * @permission ohos.permission.GET_RUNNING_INFO 270 * @param { number } upperLimit - Get the maximum limit of the number of messages. 271 * @returns { Promise<Array<ExtensionRunningInfo>> } Returns the array of ExtensionRunningInfo. 272 * @throws { BusinessError } 202 - Not system application. 273 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 274 * 2. Incorrect parameter types; 3. Parameter verification failed. 275 * @throws { BusinessError } 16000050 - Internal error. 276 * @syscap SystemCapability.Ability.AbilityRuntime.Core 277 * @systemapi 278 * @since 9 279 */ 280 function getExtensionRunningInfos(upperLimit: number): Promise<Array<ExtensionRunningInfo>>; 281 282 /** 283 * If you apply for permission, you can obtain information about all extensions. If you do not apply, you can only 284 * obtain information about the current extension. 285 * 286 * @permission ohos.permission.GET_RUNNING_INFO 287 * @param { number } upperLimit - Get the maximum limit of the number of messages. 288 * @param { AsyncCallback<Array<ExtensionRunningInfo>> } callback - The callback is used to return the array of 289 * ExtensionRunningInfo. 290 * @throws { BusinessError } 202 - Not system application. 291 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 292 * 2. Incorrect parameter types; 3. Parameter verification failed. 293 * @throws { BusinessError } 16000050 - Internal error. 294 * @syscap SystemCapability.Ability.AbilityRuntime.Core 295 * @systemapi 296 * @since 9 297 */ 298 function getExtensionRunningInfos(upperLimit: number, callback: AsyncCallback<Array<ExtensionRunningInfo>>): void; 299 300 /** 301 * Get the top ability information of the display. 302 * 303 * @returns { Promise<ElementName> } Returns the elementName info of the top ability. 304 * @throws { BusinessError } 202 - Not system application. 305 * @throws { BusinessError } 16000050 - Internal error. 306 * @syscap SystemCapability.Ability.AbilityRuntime.Core 307 * @systemapi 308 * @since 9 309 */ 310 function getTopAbility(): Promise<ElementName>; 311 312 /** 313 * Get the top ability information of the display. 314 * 315 * @param { AsyncCallback<ElementName> } callback - The callback is used to return elementName info of top ability. 316 * @throws { BusinessError } 202 - Not system application. 317 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 318 * 2. Incorrect parameter types; 3. Parameter verification failed. 319 * @throws { BusinessError } 16000050 - Internal error. 320 * @syscap SystemCapability.Ability.AbilityRuntime.Core 321 * @systemapi 322 * @since 9 323 */ 324 function getTopAbility(callback: AsyncCallback<ElementName>): void; 325 326 /** 327 * Acquire the shared data from target ability. 328 * 329 * @param { number } missionId - The missionId of target ability. 330 * @param { AsyncCallback<{ [key: string]: Object }> } callback - The callback is used to return the params of sharing 331 * data and result code. 332 * @throws { BusinessError } 202 - Not system application. 333 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 334 * 2. Incorrect parameter types; 3. Parameter verification failed. 335 * @throws { BusinessError } 16000050 - Internal error. 336 * @syscap SystemCapability.Ability.AbilityRuntime.Core 337 * @systemapi 338 * @since 10 339 */ 340 /** 341 * Acquire the shared data from target ability. 342 * 343 * @param { number } missionId - The missionId of target ability. 344 * @param { AsyncCallback<Record<string, Object>> } callback - The callback is used to return the params of sharing 345 * data and result code. 346 * @throws { BusinessError } 202 - Not system application. 347 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 348 * 2. Incorrect parameter types; 3. Parameter verification failed. 349 * @throws { BusinessError } 16000050 - Internal error. 350 * @syscap SystemCapability.Ability.AbilityRuntime.Core 351 * @systemapi 352 * @since 11 353 */ 354 function acquireShareData(missionId: number, callback: AsyncCallback<Record<string, Object>>): void; 355 356 /** 357 * Acquire the shared data from target ability. 358 * 359 * @param { number } missionId - The missionId of target ability. 360 * @returns { Promise<{ [key: string]: Object }> } The promise returned by the function. 361 * @throws { BusinessError } 202 - Not system application. 362 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 363 * 2. Incorrect parameter types; 3. Parameter verification failed. 364 * @throws { BusinessError } 16000050 - Internal error. 365 * @syscap SystemCapability.Ability.AbilityRuntime.Core 366 * @systemapi 367 * @since 10 368 */ 369 /** 370 * Acquire the shared data from target ability. 371 * 372 * @param { number } missionId - The missionId of target ability. 373 * @returns { Promise<Record<string, Object>> } The promise returned by the function. 374 * @throws { BusinessError } 202 - Not system application. 375 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 376 * 2. Incorrect parameter types; 3. Parameter verification failed. 377 * @throws { BusinessError } 16000050 - Internal error. 378 * @syscap SystemCapability.Ability.AbilityRuntime.Core 379 * @systemapi 380 * @since 11 381 */ 382 function acquireShareData(missionId: number): Promise<Record<string, Object>>; 383 384 /** 385 * Notify the result of save as to target ability. 386 * @param { AbilityResult } parameter - Indicates the result to return. 387 * @param { number } requestCode - Request code defined by the user. 388 * @param { AsyncCallback<void> } callback - The callback of the function. 389 * @throws { BusinessError } 201 - Permission denied. 390 * @throws { BusinessError } 202 - Not system application. 391 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 392 * 2. Incorrect parameter types; 3. Parameter verification failed. 393 * @throws { BusinessError } 16000050 - Internal error. 394 * @syscap SystemCapability.Ability.AbilityRuntime.Core 395 * @systemapi 396 * @StageModelOnly 397 * @since 10 398 */ 399 function notifySaveAsResult(parameter: AbilityResult, requestCode: number, callback: AsyncCallback<void>): void; 400 401 /** 402 * Notify the result of save as to target ability. 403 * @param { AbilityResult } parameter - Indicates the result to return. 404 * @param { number } requestCode - Request code defined by the user. 405 * @returns { Promise<void> } The promise returned by the function. 406 * @throws { BusinessError } 201 - Permission denied. 407 * @throws { BusinessError } 202 - Not system application. 408 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 409 * 2. Incorrect parameter types; 3. Parameter verification failed. 410 * @throws { BusinessError } 16000050 - Internal error. 411 * @syscap SystemCapability.Ability.AbilityRuntime.Core 412 * @systemapi 413 * @StageModelOnly 414 * @since 10 415 */ 416 function notifySaveAsResult(parameter: AbilityResult, requestCode: number): Promise<void>; 417 418 /** 419 * Get the foreground ui abilities. 420 * 421 * @permission ohos.permission.GET_RUNNING_INFO 422 * @param { AsyncCallback<Array<AbilityStateData>> } callback - The callback is used to return the list of AbilityStateDatas. 423 * @throws { BusinessError } 201 - Permission denied. 424 * @throws { BusinessError } 202 - Not system application. 425 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 426 * 2. Incorrect parameter types; 3. Parameter verification failed. 427 * @throws { BusinessError } 16000050 - Internal error. 428 * @syscap SystemCapability.Ability.AbilityRuntime.Core 429 * @systemapi 430 * @since 11 431 */ 432 function getForegroundUIAbilities(callback: AsyncCallback<Array<AbilityStateData>>): void; 433 434 /** 435 * Get the foreground ui abilities. 436 * 437 * @permission ohos.permission.GET_RUNNING_INFO 438 * @returns { Promise<Array<AbilityStateData>> } Returns the list of AbilityStateDatas. 439 * @throws { BusinessError } 201 - Permission denied. 440 * @throws { BusinessError } 202 - Not system application. 441 * @throws { BusinessError } 16000050 - Internal error. 442 * @syscap SystemCapability.Ability.AbilityRuntime.Core 443 * @systemapi 444 * @since 11 445 */ 446 function getForegroundUIAbilities(): Promise<Array<AbilityStateData>>; 447 448 /** 449 * Querying whether to allow embedded startup of atomic service. 450 * 451 * @param { Context } context - The context that initiates the query request. 452 * @param { string } appId - Globally unique identifier of an application, which is allocated by the cloud. 453 * @returns { Promise<boolean> } Returns the result in the form of callback. 454 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 455 * 2. Incorrect parameter types; 3. Parameter verification failed. 456 * @throws { BusinessError } 16000050 - Internal error. 457 * @syscap SystemCapability.Ability.AbilityRuntime.Core 458 * @systemapi 459 * @StageModelOnly 460 * @since 12 461 */ 462 function isEmbeddedOpenAllowed(context: Context, appId: string): Promise<boolean>; 463 464 /** 465 * Notifies the application of the assertion debugging result. 466 * 467 * @permission ohos.permission.NOTIFY_DEBUG_ASSERT_RESULT 468 * @param { string } sessionId - Indicates the request ID of AssertFault. 469 * @param { UserStatus } status - Operation status of the user. 470 * @returns { Promise<void> } The promise returned by the function. 471 * @throws { BusinessError } 201 - The application does not have permission to call the interface. 472 * @throws { BusinessError } 202 - Not system application. 473 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 474 * 2. Incorrect parameter types; 3. Parameter verification failed. 475 * @throws { BusinessError } 16000050 - Internal error. 476 * @syscap SystemCapability.Ability.AbilityRuntime.Core 477 * @systemapi 478 * @stagemodelonly 479 * @since 12 480 */ 481 function notifyDebugAssertResult(sessionId: string, status: UserStatus): Promise<void>; 482 483 /** 484 * Set the enable status for starting and stopping resident processes. 485 * The caller application can only set the resident status of the configured process. 486 * 487 * @param { string } bundleName - The bundle name of the resident process. 488 * @param { boolean } enable - Set resident process enable status. 489 * @returns { Promise<void> } The promise returned by the function. 490 * @throws { BusinessError } 202 - Not a system application. 491 * @throws { BusinessError } 401 - Parameter error. Possible cause: 1.Non empty package name needs to be provided, 2.The second parameter needs to provide a Boolean type setting value. 492 * @throws { BusinessError } 16000050 - Internal error. 493 * @throws { BusinessError } 16200006 - The caller application can only set the resident status of the configured process. 494 * @syscap SystemCapability.Ability.AbilityRuntime.Core 495 * @systemapi 496 * @since 12 497 */ 498 function setResidentProcessEnabled(bundleName: string, enable: boolean): Promise<void>; 499 500 /** 501 * Query the rule to open embedded atomic service. 502 * 503 * @param { Context } context - The context that initiates the query request. 504 * @param { string } appId - Globally unique identifier of an application, which is allocated by the cloud. 505 * @returns { Promise<AtomicServiceStartupRule> } Returns the result in the form of callback. 506 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 507 * 2. Incorrect parameter types; 3. Parameter verification failed. 508 * @throws { BusinessError } 801 - Capability not supported. 509 * @throws { BusinessError } 16000050 - Internal error. 510 * @syscap SystemCapability.Ability.AbilityRuntime.Core 511 * @systemapi 512 * @stagemodelonly 513 * @since 18 514 */ 515 function queryAtomicServiceStartupRule(context: Context, appId: string): Promise<AtomicServiceStartupRule>; 516 517 /** 518 * The class of an ability running information. 519 * 520 * @typedef { _AbilityRunningInfo } 521 * @syscap SystemCapability.Ability.AbilityRuntime.Core 522 * @systemapi 523 * @since 9 524 */ 525 export type AbilityRunningInfo = _AbilityRunningInfo; 526 527 /** 528 * The ability state data. 529 * 530 * @typedef { _AbilityStateData.default } 531 * @syscap SystemCapability.Ability.AbilityRuntime.Core 532 * @systemapi 533 * @since 11 534 */ 535 export type AbilityStateData = _AbilityStateData.default; 536 537 /** 538 * The class of an extension running information. 539 * 540 * @typedef { _ExtensionRunningInfo } 541 * @syscap SystemCapability.Ability.AbilityRuntime.Core 542 * @systemapi 543 * @since 9 544 */ 545 export type ExtensionRunningInfo = _ExtensionRunningInfo; 546 547 /** 548 * The ability foreground state observer. 549 * 550 * @typedef { _AbilityForegroundStateObserver.default } 551 * @syscap SystemCapability.Ability.AbilityRuntime.Core 552 * @systemapi 553 * @since 11 554 */ 555 export type AbilityForegroundStateObserver = _AbilityForegroundStateObserver.default; 556} 557 558export default abilityManager; 559