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