1/*
2 * Copyright (c) 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 ExtensionContext from './ExtensionContext';
22import type Want from '../@ohos.app.ability.Want';
23import type StartOptions from '../@ohos.app.ability.StartOptions';
24import type AbilityStartCallback from './AbilityStartCallback';
25import { ConnectOptions } from '../ability/connectOptions';
26
27/**
28 * The context of UI service extension. It allows access to UIServiceExtension-specific resources.
29 *
30 * @extends ExtensionContext
31 * @syscap SystemCapability.Ability.AbilityRuntime.Core
32 * @systemapi
33 * @stagemodelonly
34 * @since 14
35 */
36export default class UIServiceExtensionContext extends ExtensionContext {
37  /**
38   * UI service extension uses this method to start a specific ability.If the caller application is in foreground,
39   * you can use this method to start ability; If the caller application is in the background,
40   * you need to apply for permission:ohos.permission.START_ABILITIES_FROM_BACKGROUND.
41   * If the target ability is visible, you can start the target ability; If the target ability is invisible,
42   * you need to apply for permission:ohos.permission.START_INVISIBLE_ABILITY to start target invisible ability.
43   * If the target ability is in cross-device, you need to apply for permission:ohos.permission.DISTRIBUTED_DATASYNC.
44   *
45   * @param { Want } want - Indicates the ability to start.
46   * @param { StartOptions } [options] - Indicates the start options.
47   * @returns { Promise<void> } The promise returned by the function.
48   * @throws { BusinessError } 201 - The application does not have permission to call the interface.
49   * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;
50   * 2. Incorrect parameter types; 3. Parameter verification failed.
51   * @throws { BusinessError } 16000001 - The specified ability does not exist.
52   * @throws { BusinessError } 16000002 - Incorrect ability type.
53   * @throws { BusinessError } 16000004 - Failed to start the invisible ability.
54   * @throws { BusinessError } 16000005 - The specified process does not have the permission.
55   * @throws { BusinessError } 16000006 - Cross-user operations are not allowed.
56   * @throws { BusinessError } 16000008 - The crowdtesting application expires.
57   * @throws { BusinessError } 16000009 - An ability cannot be started or stopped in Wukong mode.
58   * @throws { BusinessError } 16000010 - The call with the continuation and prepare continuation flag is forbidden.
59   * @throws { BusinessError } 16000011 - The context does not exist.
60   * @throws { BusinessError } 16000012 - The application is controlled.
61   * @throws { BusinessError } 16000013 - The EDM prohibits the application from launching.
62   * @throws { BusinessError } 16000019 - Can not match any component.
63   * @throws { BusinessError } 16000050 - Internal error.
64   * @throws { BusinessError } 16000053 - The ability is not on the top of the UI.
65   * @throws { BusinessError } 16000055 - Installation-free timed out.
66   * @throws { BusinessError } 16200001 - The caller has been released.
67   * @syscap SystemCapability.Ability.AbilityRuntime.Core
68   * @systemapi
69   * @stagemodelonly
70   * @since 14
71   */
72  startAbility(want: Want, options?: StartOptions): Promise<void>;
73
74  /**
75   * Destroys the UI service extension.
76   *
77   * @returns { Promise<void> } The promise returned by the function.
78   * @syscap SystemCapability.Ability.AbilityRuntime.Core
79   * @systemapi
80   * @stagemodelonly
81   * @since 14
82   */
83  terminateSelf(): Promise<void>;
84
85  /**
86   * Starts the UIAbility or UIExtensionAbility by type.
87   * If the target ability is visible, you can start the target ability; If the target ability is invisible,
88   * you need to apply for permission:ohos.permission.START_INVISIBLE_ABILITY to start target invisible ability.
89   * If the caller application is in the background, it is not allowed to call this interface.
90   *
91   * @param { string } type - The type of target ability.
92   * @param { Record<string, Object> } wantParam - Indicates the want parameter.
93   * @param { AbilityStartCallback } abilityStartCallback - Indicates the abilityStartCallback.
94   * @returns { Promise<void> } The promise returned by the function.
95   * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;
96   * 2. Incorrect parameter types; 3. Parameter verification failed.
97   * @throws { BusinessError } 16000050 - Internal error.
98   * @syscap SystemCapability.Ability.AbilityRuntime.Core
99   * @systemapi
100   * @stagemodelonly
101   * @since 14
102   */
103  startAbilityByType(type: string, wantParam: Record<string, Object>,
104    abilityStartCallback: AbilityStartCallback): Promise<void>;
105
106  /**
107   * Connects to a service extension ability.
108   * If the target service extension ability is visible, you can connect the target service extension ability;
109   * If the target service extension ability is invisible,
110   * you need to apply for permission:ohos.permission.START_INVISIBLE_ABILITY to connect target invisible service extension ability.
111   * If the target service extension ability is in cross-device, you need to apply for permission:ohos.permission.DISTRIBUTED_DATASYNC.
112   * <p>This method can be called by an ability or service extension, but the destination of the connection must be a
113   * service extension. You must implement the {@link ConnectOptions} interface to obtain the proxy of the target
114   * service extension when the Service extension is connected.</p>
115   *
116   * @param { Want } want - Indicates the service extension to connect.
117   * @param { ConnectOptions } options - Indicates the callback of connection.
118   * @returns { number } Returns the connection id.
119   * @throws { BusinessError } 201 - The application does not have permission to call the interface.
120   * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;
121   * 2. Incorrect parameter types; 3. Parameter verification failed.
122   * @throws { BusinessError } 16000001 - The specified ability does not exist.
123   * @throws { BusinessError } 16000002 - Incorrect ability type.
124   * @throws { BusinessError } 16000004 - Failed to start the invisible ability.
125   * @throws { BusinessError } 16000005 - The specified process does not have the permission.
126   * @throws { BusinessError } 16000006 - Cross-user operations are not allowed.
127   * @throws { BusinessError } 16000008 - The crowdtesting application expires.
128   * @throws { BusinessError } 16000011 - The context does not exist.
129   * @throws { BusinessError } 16000013 - The EDM prohibits the application from launching.
130   * @throws { BusinessError } 16000050 - Internal error.
131   * @throws { BusinessError } 16000053 - The ability is not on the top of the UI.
132   * @throws { BusinessError } 16000055 - Installation-free timed out.
133   * @syscap SystemCapability.Ability.AbilityRuntime.Core
134   * @systemapi
135   * @stagemodelonly
136   * @since 14
137   */
138  connectServiceExtensionAbility(want: Want, options: ConnectOptions): number;
139
140  /**
141   * Disconnect an ability from a service extension, in contrast to {@link connectServiceExtensionAbility}.
142   *
143   * @param { number } connectionId - the connection id returned from connectServiceExtensionAbility api.
144   * @returns { Promise<void> } The promise returned by the function.
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 } 16000011 - The context does not exist.
148   * @throws { BusinessError } 16000050 - Internal error.
149   * @syscap SystemCapability.Ability.AbilityRuntime.Core
150   * @systemapi
151   * @stagemodelonly
152   * @since 14
153   */
154  disconnectServiceExtensionAbility(connectionId: number): Promise<void>;
155}
156