1/* 2 * Copyright (c) 2021-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 AbilityKit 19 */ 20 21import { AsyncCallback } from '../@ohos.base'; 22import { ApplicationInfo } from '../bundle/applicationInfo'; 23import { ProcessInfo } from './processInfo'; 24import { ElementName } from '../bundle/elementName'; 25import BaseContext from '../application/BaseContext'; 26import { HapModuleInfo } from '../bundle/hapModuleInfo'; 27import { AppVersionInfo } from './appVersionInfo'; 28import { AbilityInfo } from '../bundle/abilityInfo'; 29import bundle from '../@ohos.bundle'; 30 31/** 32 * The context of an ability or an application. It allows access to 33 * application-specific resources, request and verification permissions. 34 * Can only be obtained through the ability. 35 * 36 * @interface Context 37 * @syscap SystemCapability.Ability.AbilityRuntime.Core 38 * @FAModelOnly 39 * @since 6 40 */ 41export interface Context extends BaseContext { 42 /** 43 * Get the local root dir of an app. If it is the first call, the dir 44 * will be created. 45 * If in the context of the ability, return the root dir of 46 * the ability; if in the context of the application, return the 47 * root dir of the application. 48 * 49 * @returns { Promise<string> } the root dir 50 * @syscap SystemCapability.Ability.AbilityRuntime.Core 51 * @FAModelOnly 52 * @since 7 53 */ 54 getOrCreateLocalDir(): Promise<string>; 55 56 /** 57 * Get the local root dir of an app. If it is the first call, the dir 58 * will be created. 59 * If in the context of the ability, return the root dir of 60 * the ability; if in the context of the application, return the 61 * root dir of the application. 62 * 63 * @param { AsyncCallback<string> } callback - Returns the local root directory of the application. 64 * @syscap SystemCapability.Ability.AbilityRuntime.Core 65 * @FAModelOnly 66 * @since 7 67 */ 68 getOrCreateLocalDir(callback: AsyncCallback<string>): void; 69 70 /** 71 * Verify whether the specified permission is allowed for a particular 72 * pid and uid running in the system. 73 * Pid and uid are optional. If you do not pass in pid and uid, 74 * it will check your own permission. 75 * 76 * @param { string } permission - The name of the specified permission. 77 * @param { PermissionOptions } [options] - Permission Options. 78 * @returns { Promise<number> } asynchronous callback with {@code 0} if the PID 79 * and UID have the permission; callback with {@code -1} otherwise. 80 * @syscap SystemCapability.Ability.AbilityRuntime.Core 81 * @FAModelOnly 82 * @since 7 83 */ 84 verifyPermission(permission: string, options?: PermissionOptions): Promise<number>; 85 86 /** 87 * Verify whether the specified permission is allowed for a particular 88 * pid and uid running in the system. 89 * Pid and uid are optional. If you do not pass in pid and uid, 90 * it will check your own permission. 91 * 92 * @param { string } permission - The name of the specified permission 93 * @param { PermissionOptions } options - Permission Options 94 * @param { AsyncCallback<number> } callback - Return permission verification result, 0 has permission, 95 * -1 has no permission. 96 * @syscap SystemCapability.Ability.AbilityRuntime.Core 97 * @FAModelOnly 98 * @since 7 99 */ 100 verifyPermission(permission: string, options: PermissionOptions, callback: AsyncCallback<number>): void; 101 102 /** 103 * Verify whether the specified permission is allowed for a particular 104 * pid and uid running in the system. 105 * Pid and uid are optional. If you do not pass in pid and uid, 106 * it will check your own permission. 107 * 108 * @param { string } permission - The name of the specified permission 109 * @param { AsyncCallback<number> } callback - Return permission verification result, 0 has permission, 110 * -1 has no permission. 111 * @syscap SystemCapability.Ability.AbilityRuntime.Core 112 * @FAModelOnly 113 * @since 7 114 */ 115 verifyPermission(permission: string, callback: AsyncCallback<number>): void; 116 117 /** 118 * Requests certain permissions from the system. 119 * 120 * @param { Array<string> } permissions - Indicates the list of permissions to be requested.parameter cannot be null. 121 * @param { number } requestCode - Indicates the request code to be passed to the PermissionRequestResult 122 * @param { AsyncCallback<PermissionRequestResult> } resultCallback - Return authorization result information. 123 * @syscap SystemCapability.Ability.AbilityRuntime.Core 124 * @FAModelOnly 125 * @since 7 126 */ 127 requestPermissionsFromUser( 128 permissions: Array<string>, 129 requestCode: number, 130 resultCallback: AsyncCallback<PermissionRequestResult> 131 ): void; 132 133 /** 134 * Requests certain permissions from the system. 135 * 136 * @param { Array<string> } permissions - Indicates the list of permissions to be requested.Parameter cannot be null. 137 * @param { number } requestCode - Indicates the request code to be passed to the PermissionRequestResult 138 * @returns { Promise<PermissionRequestResult> } Indicates the request code to be passed to PermissionRequestResult. 139 * @syscap SystemCapability.Ability.AbilityRuntime.Core 140 * @FAModelOnly 141 * @since 7 142 */ 143 requestPermissionsFromUser(permissions: Array<string>, requestCode: number): Promise<PermissionRequestResult>; 144 145 /** 146 * Obtains information about the current application. 147 * 148 * @param { AsyncCallback<ApplicationInfo> } callback - Returns information about the current application. 149 * @syscap SystemCapability.Ability.AbilityRuntime.Core 150 * @FAModelOnly 151 * @since 7 152 */ 153 getApplicationInfo(callback: AsyncCallback<ApplicationInfo>): void; 154 155 /** 156 * Obtains information about the current application. 157 * 158 * @returns { Promise<ApplicationInfo> } Information about the current application. 159 * @syscap SystemCapability.Ability.AbilityRuntime.Core 160 * @FAModelOnly 161 * @since 7 162 */ 163 getApplicationInfo(): Promise<ApplicationInfo>; 164 165 /** 166 * Obtains the bundle name of the current ability. 167 * 168 * @param { AsyncCallback<string> } callback - Returns the Bundle name of the current capability. 169 * @syscap SystemCapability.Ability.AbilityRuntime.Core 170 * @FAModelOnly 171 * @since 7 172 */ 173 getBundleName(callback: AsyncCallback<string>): void; 174 175 /** 176 * Obtains the bundle name of the current ability. 177 * 178 * @returns { Promise<string> } The Bundle name of the current capability. 179 * @syscap SystemCapability.Ability.AbilityRuntime.Core 180 * @FAModelOnly 181 * @since 7 182 */ 183 getBundleName(): Promise<string>; 184 185 /** 186 * Obtains the current display orientation of this ability. 187 * 188 * @param { AsyncCallback<bundle.DisplayOrientation> } callback - Indicates the realistic direction of the screen. 189 * @syscap SystemCapability.Ability.AbilityRuntime.Core 190 * @FAModelOnly 191 * @since 7 192 */ 193 getDisplayOrientation(callback: AsyncCallback<bundle.DisplayOrientation>): void; 194 195 /** 196 * Obtains the current display orientation of this ability. 197 * 198 * @returns { Promise<bundle.DisplayOrientation> } Indicates the screen display direction. 199 * @syscap SystemCapability.Ability.AbilityRuntime.Core 200 * @FAModelOnly 201 * @since 7 202 */ 203 getDisplayOrientation(): Promise<bundle.DisplayOrientation>; 204 205 /** 206 * Obtains the absolute path to the application-specific cache directory 207 * 208 * @param { AsyncCallback<string> } callback - Returns the absolute path of the application's cache directory. 209 * @syscap SystemCapability.Ability.AbilityRuntime.Core 210 * @FAModelOnly 211 * @since 6 212 * @deprecated since 7 213 */ 214 getExternalCacheDir(callback: AsyncCallback<string>): void; 215 216 /** 217 * Obtains the absolute path to the application-specific cache directory 218 * 219 * @returns { Promise<string> } Return the cache directory of the application. 220 * @syscap SystemCapability.Ability.AbilityRuntime.Core 221 * @FAModelOnly 222 * @since 6 223 * @deprecated since 7 224 */ 225 getExternalCacheDir(): Promise<string>; 226 227 /** 228 * Sets the display orientation of the current ability. 229 * 230 * @param { bundle.DisplayOrientation } orientation - Indicates the new orientation for the current ability. 231 * @param { AsyncCallback<void> } callback - Indicates the realistic direction of the screen. 232 * @syscap SystemCapability.Ability.AbilityRuntime.Core 233 * @FAModelOnly 234 * @since 7 235 */ 236 setDisplayOrientation(orientation: bundle.DisplayOrientation, callback: AsyncCallback<void>): void; 237 238 /** 239 * Sets the display orientation of the current ability. 240 * 241 * @param { bundle.DisplayOrientation } orientation - Indicates the new orientation for the current ability. 242 * @returns { Promise<void> } the promise returned by the function. 243 * @syscap SystemCapability.Ability.AbilityRuntime.Core 244 * @FAModelOnly 245 * @since 7 246 */ 247 setDisplayOrientation(orientation: bundle.DisplayOrientation): Promise<void>; 248 249 /** 250 * Sets whether to show this ability on top of the lock screen whenever the lock screen is displayed, keeping the 251 * ability in the ACTIVE state. 252 * The interface can only take effect in API8 and below versions. 253 * 254 * @param { boolean } show - Specifies whether to show this ability on top of the lock screen. The value true means 255 * to show it on the lock screen, and the value false means not. 256 * @param { AsyncCallback<void> } callback - Returns the callback result. 257 * @syscap SystemCapability.Ability.AbilityRuntime.Core 258 * @FAModelOnly 259 * @since 7 260 * @deprecated since 9 261 * @useinstead ohos.window/window.WindowStage#setShowOnLockScreen 262 */ 263 setShowOnLockScreen(show: boolean, callback: AsyncCallback<void>): void; 264 265 /** 266 * Sets whether to show this ability on top of the lock screen whenever the lock screen is displayed, keeping the 267 * ability in the ACTIVE state. 268 * The interface can only take effect in API8 and below versions. 269 * 270 * @param { boolean } show - Specifies whether to show this ability on top of the lock screen. The value true means to 271 * show it on the lock screen, and the value false means not. 272 * @returns { Promise<void> } the promise returned by the function. 273 * @syscap SystemCapability.Ability.AbilityRuntime.Core 274 * @FAModelOnly 275 * @since 7 276 * @deprecated since 9 277 * @useinstead ohos.window/window.WindowStage#setShowOnLockScreen 278 */ 279 setShowOnLockScreen(show: boolean): Promise<void>; 280 281 /** 282 * Sets whether to wake up the screen when this ability is restored. 283 * 284 * @param { boolean } wakeUp - Specifies whether to wake up the screen. The value true means to wake it up, 285 * and the value false means not. 286 * @param { AsyncCallback<void> } callback - Returns the callback result. 287 * @syscap SystemCapability.Ability.AbilityRuntime.Core 288 * @FAModelOnly 289 * @since 7 290 * @deprecated since 12 291 * @useinstead ohos.window.Window#setWakeUpScreen 292 */ 293 setWakeUpScreen(wakeUp: boolean, callback: AsyncCallback<void>): void; 294 295 /** 296 * Sets whether to wake up the screen when this ability is restored. 297 * 298 * @param { boolean } wakeUp - Specifies whether to wake up the screen. The value true means to wake it up, and the 299 * value false means not. 300 * @returns { Promise<void> } the promise returned by the function. 301 * @syscap SystemCapability.Ability.AbilityRuntime.Core 302 * @FAModelOnly 303 * @since 7 304 * @deprecated since 12 305 * @useinstead ohos.window.Window#setWakeUpScreen 306 */ 307 setWakeUpScreen(wakeUp: boolean): Promise<void>; 308 309 /** 310 * Obtains information about the current process, including the process ID and name. 311 * 312 * @param { AsyncCallback<ProcessInfo> } callback - Return current process information. 313 * @syscap SystemCapability.Ability.AbilityRuntime.Core 314 * @FAModelOnly 315 * @since 7 316 */ 317 getProcessInfo(callback: AsyncCallback<ProcessInfo>): void; 318 319 /** 320 * Obtains information about the current process, including the process ID and name. 321 * 322 * @returns { Promise<ProcessInfo> } Information about the current process. 323 * @syscap SystemCapability.Ability.AbilityRuntime.Core 324 * @FAModelOnly 325 * @since 7 326 */ 327 getProcessInfo(): Promise<ProcessInfo>; 328 329 /** 330 * Obtains the ohos.bundle.ElementName object of the current ability.This method is available only to Page abilities. 331 * 332 * @param { AsyncCallback<ElementName> } callback - Returns the ohos.bundle.ElementName of the current capability. 333 * @syscap SystemCapability.Ability.AbilityRuntime.Core 334 * @FAModelOnly 335 * @since 7 336 */ 337 getElementName(callback: AsyncCallback<ElementName>): void; 338 339 /** 340 * Obtains the ohos.bundle.ElementName object of the current ability.This method is available only to Page abilities. 341 * 342 * @returns { Promise<ElementName> } The ohos.bundle.ElementName object of the current capability. 343 * @syscap SystemCapability.Ability.AbilityRuntime.Core 344 * @FAModelOnly 345 * @since 7 346 */ 347 getElementName(): Promise<ElementName>; 348 349 /** 350 * Obtains the name of the current process. 351 * 352 * @param { AsyncCallback<string> } callback - Return current process name. 353 * @syscap SystemCapability.Ability.AbilityRuntime.Core 354 * @FAModelOnly 355 * @since 7 356 */ 357 getProcessName(callback: AsyncCallback<string>): void; 358 359 /** 360 * Obtains the name of the current process. 361 * 362 * @returns { Promise<string> } Returns the name of the current process. 363 * @syscap SystemCapability.Ability.AbilityRuntime.Core 364 * @FAModelOnly 365 * @since 7 366 */ 367 getProcessName(): Promise<string>; 368 369 /** 370 * Obtains the bundle name of the ability that called the current ability. 371 * 372 * @param { AsyncCallback<string> } callback - Returns the Bundle name of the ability caller. 373 * @syscap SystemCapability.Ability.AbilityRuntime.Core 374 * @FAModelOnly 375 * @since 7 376 */ 377 getCallingBundle(callback: AsyncCallback<string>): void; 378 379 /** 380 * Obtains the bundle name of the ability that called the current ability. 381 * 382 * @returns { Promise<string> } Returns the Bundle name of the ability caller. 383 * @syscap SystemCapability.Ability.AbilityRuntime.Core 384 * @FAModelOnly 385 * @since 7 386 */ 387 getCallingBundle(): Promise<string>; 388 389 /** 390 * Obtains the file directory of this application on the internal storage. 391 * 392 * @param { AsyncCallback<string> } callback - Return the file directory of this application on internal storage. 393 * @syscap SystemCapability.Ability.AbilityRuntime.Core 394 * @FAModelOnly 395 * @since 6 396 */ 397 getFilesDir(callback: AsyncCallback<string>): void; 398 399 /** 400 * Obtains the file directory of this application on the internal storage. 401 * 402 * @returns { Promise<string> } Return the file directory of this application on internal storage. 403 * @syscap SystemCapability.Ability.AbilityRuntime.Core 404 * @FAModelOnly 405 * @since 6 406 */ 407 getFilesDir(): Promise<string>; 408 409 /** 410 * Obtains the cache directory of this application on the internal storage. 411 * 412 * @param { AsyncCallback<string> } callback - Returns the internal storage directory of the application. 413 * @syscap SystemCapability.Ability.AbilityRuntime.Core 414 * @FAModelOnly 415 * @since 6 416 */ 417 getCacheDir(callback: AsyncCallback<string>): void; 418 419 /** 420 * Obtains the cache directory of this application on the internal storage. 421 * 422 * @returns { Promise<string> } Returns the internal storage directory of the application. 423 * @syscap SystemCapability.Ability.AbilityRuntime.Core 424 * @FAModelOnly 425 * @since 6 426 */ 427 getCacheDir(): Promise<string>; 428 429 /** 430 * Obtains the distributed file path for storing ability or application data files. 431 * If the distributed file path does not exist, the system will create a path and return the created path. 432 * 433 * @returns { Promise<string> } Returns the distributed file path of the Ability or application. If it is the first 434 * call, a directory will be created. 435 * @syscap SystemCapability.Ability.AbilityRuntime.Core 436 * @FAModelOnly 437 * @since 7 438 */ 439 getOrCreateDistributedDir(): Promise<string>; 440 441 /** 442 * Obtains the distributed file path for storing ability or application data files. 443 * If the distributed file path does not exist, the system will create a path and return the created path. 444 * 445 * @param { AsyncCallback<string> } callback - Returns the distributed file path of Ability or application. 446 * If the path does not exist,the system will create a path and return the created path. 447 * @syscap SystemCapability.Ability.AbilityRuntime.Core 448 * @FAModelOnly 449 * @since 7 450 */ 451 getOrCreateDistributedDir(callback: AsyncCallback<string>): void; 452 453 /** 454 * Obtains the application type. 455 * 456 * @param { AsyncCallback<string> } callback - Returns the type of the current application. 457 * @syscap SystemCapability.Ability.AbilityRuntime.Core 458 * @FAModelOnly 459 * @since 7 460 */ 461 getAppType(callback: AsyncCallback<string>): void; 462 463 /** 464 * Obtains the application type. 465 * 466 * @returns { Promise<string> } Returns the type of this app. 467 * @syscap SystemCapability.Ability.AbilityRuntime.Core 468 * @FAModelOnly 469 * @since 7 470 */ 471 getAppType(): Promise<string>; 472 473 /** 474 * Obtains the ModuleInfo object for this application. 475 * 476 * @param { AsyncCallback<HapModuleInfo> } callback - Returns the ModuleInfo object of the application. 477 * @syscap SystemCapability.Ability.AbilityRuntime.Core 478 * @FAModelOnly 479 * @since 7 480 */ 481 getHapModuleInfo(callback: AsyncCallback<HapModuleInfo>): void; 482 483 /** 484 * Obtains the ModuleInfo object for this application. 485 * 486 * @returns { Promise<HapModuleInfo> } Return to the ModuleInfo of the application and enjoy it. 487 * @syscap SystemCapability.Ability.AbilityRuntime.Core 488 * @FAModelOnly 489 * @since 7 490 */ 491 getHapModuleInfo(): Promise<HapModuleInfo>; 492 493 /** 494 * Obtains the application version information. 495 * 496 * @param { AsyncCallback<AppVersionInfo> } callback - Return application version information. 497 * @syscap SystemCapability.Ability.AbilityRuntime.Core 498 * @FAModelOnly 499 * @since 7 500 */ 501 getAppVersionInfo(callback: AsyncCallback<AppVersionInfo>): void; 502 503 /** 504 * Obtains the application version information. 505 * 506 * @returns { Promise<AppVersionInfo> } Return application version information. 507 * @syscap SystemCapability.Ability.AbilityRuntime.Core 508 * @FAModelOnly 509 * @since 7 510 */ 511 getAppVersionInfo(): Promise<AppVersionInfo>; 512 513 /** 514 * Obtains the context of this application. 515 * 516 * @returns { Context } Return application context information. 517 * @syscap SystemCapability.Ability.AbilityRuntime.Core 518 * @FAModelOnly 519 * @since 7 520 */ 521 getApplicationContext(): Context; 522 523 /** 524 * Checks the detailed information of this ability. 525 * 526 * @param { AsyncCallback<AbilityInfo> } callback - Return the detailed information of the current belonging Ability. 527 * @syscap SystemCapability.Ability.AbilityRuntime.Core 528 * @FAModelOnly 529 * @since 7 530 */ 531 getAbilityInfo(callback: AsyncCallback<AbilityInfo>): void; 532 533 /** 534 * Checks the detailed information of this ability. 535 * 536 * @returns { Promise<AbilityInfo> } Return the detailed information of the current belonging Ability. 537 * @syscap SystemCapability.Ability.AbilityRuntime.Core 538 * @FAModelOnly 539 * @since 7 540 */ 541 getAbilityInfo(): Promise<AbilityInfo>; 542 543 /** 544 * Checks whether the configuration of this ability is changing. 545 * 546 * @param { AsyncCallback<boolean> } callback - True if the configuration of the capability is being changed, otherwise false. 547 * @syscap SystemCapability.Ability.AbilityRuntime.Core 548 * @FAModelOnly 549 * @since 7 550 */ 551 isUpdatingConfigurations(callback: AsyncCallback<boolean>): void; 552 553 /** 554 * Checks whether the configuration of this ability is changing. 555 * 556 * @returns { Promise<boolean> } true if the configuration of this ability is changing and false otherwise. 557 * @syscap SystemCapability.Ability.AbilityRuntime.Core 558 * @FAModelOnly 559 * @since 7 560 */ 561 isUpdatingConfigurations(): Promise<boolean>; 562 563 /** 564 * Inform the system of the time required for drawing this Page ability. 565 * 566 * @param { AsyncCallback<void> } callback - Represents the specified callback method. 567 * @syscap SystemCapability.Ability.AbilityRuntime.Core 568 * @FAModelOnly 569 * @since 7 570 */ 571 printDrawnCompleted(callback: AsyncCallback<void>): void; 572 573 /** 574 * Inform the system of the time required for drawing this Page ability. 575 * 576 * @returns { Promise<void> } The promise form returns the result. 577 * @syscap SystemCapability.Ability.AbilityRuntime.Core 578 * @FAModelOnly 579 * @since 7 580 */ 581 printDrawnCompleted(): Promise<void>; 582} 583/** 584 * @typedef PermissionRequestResult 585 * @syscap SystemCapability.Ability.AbilityRuntime.Core 586 * @FAModelOnly 587 * @since 7 588 */ 589interface PermissionRequestResult { 590 /** 591 * @type { number } 592 * @default The request code passed in by the user 593 * @syscap SystemCapability.Ability.AbilityRuntime.Core 594 * @FAModelOnly 595 * @since 7 596 */ 597 requestCode: number; 598 599 /** 600 * @type { Array<string> } 601 * @default The permissions passed in by the user 602 * @syscap SystemCapability.Ability.AbilityRuntime.Core 603 * @FAModelOnly 604 * @since 7 605 */ 606 permissions: Array<string>; 607 608 /** 609 * @type { Array<number> } 610 * @default The results for the corresponding request permissions 611 * @syscap SystemCapability.Ability.AbilityRuntime.Core 612 * @FAModelOnly 613 * @since 7 614 */ 615 authResults: Array<number>; 616} 617 618/** 619 * @typedef PermissionOptions 620 * @syscap SystemCapability.Ability.AbilityRuntime.Core 621 * @FAModelOnly 622 * @since 7 623 */ 624interface PermissionOptions { 625 /** 626 * @type { ?number } 627 * @default The process id 628 * @syscap SystemCapability.Ability.AbilityRuntime.Core 629 * @FAModelOnly 630 * @since 7 631 */ 632 pid?: number; 633 634 /** 635 * @type { ?number } 636 * @default The user id 637 * @syscap SystemCapability.Ability.AbilityRuntime.Core 638 * @FAModelOnly 639 * @since 7 640 */ 641 uid?: number; 642} 643