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 FormKit
19 */
20
21import { AsyncCallback } from '../@ohos.base';
22import type { ConnectOptions } from '../ability/connectOptions';
23import ExtensionContext from './ExtensionContext';
24import Want from '../@ohos.app.ability.Want';
25
26/**
27 * The context of form extension. It allows access to
28 * formExtension-specific resources.
29 *
30 * @extends ExtensionContext
31 * @syscap SystemCapability.Ability.Form
32 * @stagemodelonly
33 * @since 9
34 */
35/**
36 * The context of form extension. It allows access to
37 * formExtension-specific resources.
38 *
39 * @extends ExtensionContext
40 * @syscap SystemCapability.Ability.Form
41 * @stagemodelonly
42 * @atomicservice
43 * @since 11
44 */
45export default class FormExtensionContext extends ExtensionContext {
46  /**
47   * Start an ability within the same bundle.
48   *
49   * @param { Want } want - includes ability name, parameters and relative info sending to an ability.
50   * @param { AsyncCallback<void> } callback - The callback of startAbility.
51   * @throws { BusinessError } 202 - The application is not a system application.
52   * @throws { BusinessError } 401 - Parameter error. Possible causes:
53   *     1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
54   * @throws { BusinessError } 16500050 - An IPC connection error happened.
55   * @throws { BusinessError } 16500100 - Failed to obtain the configuration information.
56   * @throws { BusinessError } 16500101 - The application is not a system application.
57   * @throws { BusinessError } 16501000 - An internal functional error occurred.
58   * @syscap SystemCapability.Ability.Form
59   * @systemapi
60   * @stagemodelonly
61   * @since 9
62   */
63  /**
64   * Start an ability.
65   *
66   * @param { Want } want - includes ability name, parameters and relative info sending to an ability.
67   * @param { AsyncCallback<void> } callback - The callback of startAbility.
68   * @throws { BusinessError } 202 - The application is not a system application.
69   * @throws { BusinessError } 401 - Parameter error. Possible causes:
70   *     1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
71   * @throws { BusinessError } 16500050 - An IPC connection error happened.
72   * @throws { BusinessError } 16500100 - Failed to obtain the configuration information.
73   * @throws { BusinessError } 16501000 - An internal functional error occurred.
74   * @syscap SystemCapability.Ability.Form
75   * @systemapi
76   * @stagemodelonly
77   * @since 12
78   */
79  startAbility(want: Want, callback: AsyncCallback<void>): void;
80
81  /**
82   * Start an ability within the same bundle.
83   *
84   * @param { Want } want - includes ability name, parameters and relative info sending to an ability.
85   * @returns { Promise<void> } The promise returned by the function.
86   * @throws { BusinessError } 202 - The application is not a system application.
87   * @throws { BusinessError } 401 - Parameter error. Possible causes:
88   *     1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
89   * @throws { BusinessError } 16500050 - An IPC connection error happened.
90   * @throws { BusinessError } 16500100 - Failed to obtain the configuration information.
91   * @throws { BusinessError } 16500101 - The application is not a system application.
92   * @throws { BusinessError } 16501000 - An internal functional error occurred.
93   * @syscap SystemCapability.Ability.Form
94   * @systemapi
95   * @stagemodelonly
96   * @since 9
97   */
98  /**
99   * Start an ability.
100   *
101   * @param { Want } want - includes ability name, parameters and relative info sending to an ability.
102   * @returns { Promise<void> } The promise returned by the function.
103   * @throws { BusinessError } 202 - The application is not a system application.
104   * @throws { BusinessError } 401 - Parameter error. Possible causes:
105   *     1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
106   * @throws { BusinessError } 16500050 - An IPC connection error happened.
107   * @throws { BusinessError } 16500100 - Failed to obtain the configuration information.
108   * @throws { BusinessError } 16501000 - An internal functional error occurred.
109   * @syscap SystemCapability.Ability.Form
110   * @systemapi
111   * @stagemodelonly
112   * @since 12
113   */
114  startAbility(want: Want): Promise<void>;
115
116  /**
117   * Connect a service extension ability.
118   * If the target service extension ability is visible, you can connect the target service extension ability;
119   * If the target service extension ability is invisible,
120   * you need to apply for permission:ohos.permission.START_INVISIBLE_ABILITY to connect target invisible service extension ability.
121   * If the target service extension ability is in cross-device, you need to apply for permission:ohos.permission.DISTRIBUTED_DATASYNC.
122   * <p>This method can be called by an ability or service extension, but the destination of the connection must be a
123   * service extension. You must implement the {@link ConnectOptions} interface to obtain the proxy of the target
124   * service extension when the Service extension is connected.</p>
125   *
126   * @param { Want } want - Indicates the service extension to connect.
127   * @param { ConnectOptions } options - Indicates the callback of connection.
128   * @returns { number } Returns the connection id.
129   * @throws { BusinessError } 201 - The application does not have permission to call the interface.
130   * @throws { BusinessError } 401 - Parameter error. Possible causes:
131   *     1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
132   * @throws { BusinessError } 16000001 - The specified ability does not exist.
133   * @throws { BusinessError } 16000002 - Incorrect ability type.
134   * @throws { BusinessError } 16000004 - Can not start invisible component.
135   * @throws { BusinessError } 16000005 - The specified process does not have the permission.
136   * @throws { BusinessError } 16000006 - Cross-user operations are not allowed.
137   * @throws { BusinessError } 16000008 - The crowdtesting application expires.
138   * @throws { BusinessError } 16000011 - The context does not exist.
139   * @throws { BusinessError } 16000050 - Internal error.
140   * @throws { BusinessError } 16000053 - The ability is not on the top of the UI.
141   * @throws { BusinessError } 16000055 - Installation-free timed out.
142   * @syscap SystemCapability.Ability.Form
143   * @systemapi
144   * @stagemodelonly
145   * @since 10
146   */
147  connectServiceExtensionAbility(want: Want, options: ConnectOptions): number;
148
149  /**
150   * Disconnect an ability to a service extension, in contrast to {@link connectServiceExtensionAbility}.
151   *
152   * @param { number } connection - the connection id returned from connectServiceExtensionAbility api.
153   * @param { AsyncCallback<void> } callback - The callback of disconnectServiceExtensionAbility.
154   * @throws { BusinessError } 401 - Parameter error. Possible causes:
155   *     1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
156   * @throws { BusinessError } 16000011 - The context does not exist.
157   * @throws { BusinessError } 16000050 - Internal error.
158   * @syscap SystemCapability.Ability.Form
159   * @systemapi
160   * @stagemodelonly
161   * @since 10
162   */
163  disconnectServiceExtensionAbility(connection: number, callback: AsyncCallback<void>): void;
164
165  /**
166   * Disconnect an ability to a service extension, in contrast to {@link connectServiceExtensionAbility}.
167   *
168   * @param { number } connection - the connection id returned from connectServiceExtensionAbility api.
169   * @returns { Promise<void> } The promise returned by the function.
170   * @throws { BusinessError } 401 - Parameter error. Possible causes:
171   *     1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
172   * @throws { BusinessError } 16000011 - The context does not exist.
173   * @throws { BusinessError } 16000050 - Internal error.
174   * @syscap SystemCapability.Ability.Form
175   * @systemapi
176   * @stagemodelonly
177   * @since 10
178   */
179  disconnectServiceExtensionAbility(connection: number): Promise<void>;
180}
181