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