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