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