1/* 2 * Copyright (c) 2022 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 16import Ability from "./@ohos.app.ability.Ability"; 17import AbilityConstant from "./@ohos.app.ability.AbilityConstant"; 18import UIAbilityContext from "./application/UIAbilityContext"; 19import rpc from './@ohos.rpc'; 20import Want from './@ohos.app.ability.Want'; 21import window from './@ohos.window'; 22 23/** 24 * The prototype of the listener function interface registered by the Caller. 25 * @typedef OnReleaseCallback 26 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 27 * @StageModelOnly 28 * @since 9 29 */ 30export interface OnReleaseCallback { 31 (msg: string): void; 32} 33 34/** 35 * The prototype of the message listener function interface registered by the Callee. 36 * @typedef CalleeCallback 37 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 38 * @StageModelOnly 39 * @since 9 40 */ 41export interface CalleeCallback { 42 (indata: rpc.MessageSequence): rpc.Parcelable; 43} 44 45/** 46 * The interface of a Caller. 47 * @interface 48 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 49 * @StageModelOnly 50 * @since 9 51 */ 52export interface Caller { 53 /** 54 * Notify the server of Parcelable type data. 55 * @param { string } method - The notification event string listened to by the callee. 56 * @param { rpc.Parcelable } data - Notification data to the callee. 57 * @returns { Promise<void> } The promise returned by the function. 58 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 59 * @throws { BusinessError } 16200001 - Caller released. The caller has been released. 60 * @throws { BusinessError } 16200002 - Callee invalid. The callee does not exist. 61 * @throws { BusinessError } 16000050 - Internal error. 62 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 63 * @StageModelOnly 64 * @since 9 65 */ 66 call(method: string, data: rpc.Parcelable): Promise<void>; 67 68 /** 69 * Notify the server of Parcelable type data and return the notification result. 70 * @param { string } method - The notification event string listened to by the callee. 71 * @param { rpc.Parcelable } data - Notification data to the callee. 72 * @returns { Promise<rpc.MessageSequence> } Returns the callee's notification result data. 73 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 74 * @throws { BusinessError } 16200001 - Caller released. The caller has been released. 75 * @throws { BusinessError } 16200002 - Callee invalid. The callee does not exist. 76 * @throws { BusinessError } 16000050 - Internal error. 77 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 78 * @StageModelOnly 79 * @since 9 80 */ 81 callWithResult(method: string, data: rpc.Parcelable): Promise<rpc.MessageSequence>; 82 83 /** 84 * Clear service records. 85 * @throws { BusinessError } 16200001 - Caller released. The caller has been released. 86 * @throws { BusinessError } 16200002 - Callee invalid. The callee does not exist. 87 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 88 * @StageModelOnly 89 * @since 9 90 */ 91 release(): void; 92 93 /** 94 * Register death listener notification callback. 95 * @param { OnReleaseCallback } callback - Register a callback function for listening for notifications. 96 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 97 * @throws { BusinessError } 16200001 - Caller released. The caller has been released. 98 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 99 * @StageModelOnly 100 * @since 9 101 */ 102 onRelease(callback: OnReleaseCallback): void; 103 104 /** 105 * Register death listener notification callback. 106 * @param { string } type - release. 107 * @param { OnReleaseCallback } callback - Register a callback function for listening for notifications. 108 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 109 * @throws { BusinessError } 16200001 - Caller released. The caller has been released. 110 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 111 * @StageModelOnly 112 * @since 9 113 */ 114 on(type: "release", callback: OnReleaseCallback): void; 115 116 /** 117 * Unregister death listener notification callback. 118 * @param { string } type - release. 119 * @param { OnReleaseCallback } callback - Unregister a callback function for listening for notifications. 120 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 121 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 122 * @StageModelOnly 123 * @since 9 124 */ 125 off(type: "release", callback: OnReleaseCallback): void; 126 127 /** 128 * Unregister all death listener notification callback. 129 * @param { string } type - release. 130 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 131 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 132 * @StageModelOnly 133 * @since 9 134 */ 135 off(type: "release"): void; 136} 137 138/** 139 * The interface of a Callee. 140 * @interface 141 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 142 * @StageModelOnly 143 * @since 9 144 */ 145export interface Callee { 146 /** 147 * Register data listener callback. 148 * @param { string } method - A string registered to listen for notification events. 149 * @param { CalleeCallback } callback - Register a callback function that listens for notification events. 150 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 151 * @throws { BusinessError } 16200004 Method registered. The method has registered. 152 * @throws { BusinessError } 16000050 Internal error. 153 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 154 * @StageModelOnly 155 * @since 9 156 */ 157 on(method: string, callback: CalleeCallback): void; 158 159 /** 160 * Unregister data listener callback. 161 * @param { string } method - A string registered to listen for notification events. 162 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 163 * @throws { BusinessError } 16200005 Method not registered. The method has not registered. 164 * @throws { BusinessError } 16000050 Internal error. 165 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 166 * @StageModelOnly 167 * @since 9 168 */ 169 off(method: string): void; 170} 171 172/** 173 * The class of a UI ability. 174 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 175 * @StageModelOnly 176 * @since 9 177 */ 178export default class UIAbility extends Ability { 179 /** 180 * Indicates configuration information about an ability context. 181 * @type { UIAbilityContext } 182 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 183 * @StageModelOnly 184 * @since 9 185 */ 186 context: UIAbilityContext; 187 188 /** 189 * Indicates ability launch want. 190 * @type { Want } 191 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 192 * @StageModelOnly 193 * @since 9 194 */ 195 launchWant: Want; 196 197 /** 198 * Indicates ability last request want. 199 * @type { Want } 200 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 201 * @StageModelOnly 202 * @since 9 203 */ 204 lastRequestWant: Want; 205 206 /** 207 * Call Service Stub Object. 208 * @type { Callee } 209 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 210 * @StageModelOnly 211 * @since 9 212 */ 213 callee: Callee; 214 215 /** 216 * Called back when an ability is started for initialization. 217 * @param { Want } want - Indicates the want info of the created ability. 218 * @param { AbilityConstant.LaunchParam } param - Indicates the launch param. 219 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 220 * @StageModelOnly 221 * @since 9 222 */ 223 onCreate(want: Want, param: AbilityConstant.LaunchParam): void; 224 225 /** 226 * Called back when an ability window stage is created. 227 * @param { window.WindowStage } windowStage - Indicates the created WindowStage. 228 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 229 * @StageModelOnly 230 * @since 9 231 */ 232 onWindowStageCreate(windowStage: window.WindowStage): void; 233 234 /** 235 * Called back when an ability window stage is destroyed. 236 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 237 * @StageModelOnly 238 * @since 9 239 */ 240 onWindowStageDestroy(): void; 241 242 /** 243 * Called back when an ability window stage is restored. 244 * @param { window.WindowStage } windowStage - window stage to restore 245 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 246 * @StageModelOnly 247 * @since 9 248 */ 249 onWindowStageRestore(windowStage: window.WindowStage): void; 250 251 /** 252 * Called back before an ability is destroyed. 253 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 254 * @StageModelOnly 255 * @since 9 256 */ 257 onDestroy(): void | Promise<void>; 258 259 /** 260 * Called back when the state of an ability changes to foreground. 261 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 262 * @StageModelOnly 263 * @since 9 264 */ 265 onForeground(): void; 266 267 /** 268 * Called back when the state of an ability changes to background. 269 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 270 * @StageModelOnly 271 * @since 9 272 */ 273 onBackground(): void; 274 275 /** 276 * Called back when an ability prepares to continue. 277 * @param { {[key: string]: Object} } wantParam - Indicates the want parameter. 278 * @returns { AbilityConstant.OnContinueResult } Return the result of onContinue. 279 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 280 * @StageModelOnly 281 * @since 9 282 */ 283 onContinue(wantParam: { [key: string]: Object }): AbilityConstant.OnContinueResult; 284 285 /** 286 * Called when the launch mode of an ability is set to singleton. 287 * This happens when you re-launch an ability that has been at the top of the ability stack. 288 * @param { Want } want - Indicates the want info of ability. 289 * @param { AbilityConstant.LaunchParam } launchParams - Indicates the launch parameters. 290 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 291 * @StageModelOnly 292 * @since 9 293 */ 294 onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void; 295 296 /** 297 * Called when dump client information is required. 298 * It is recommended that developers don't DUMP sensitive information. 299 * @param { Array<string> } params - Indicates the params from command. 300 * @returns { Array<string> } Return the dump info array. 301 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 302 * @StageModelOnly 303 * @since 9 304 */ 305 onDump(params: Array<string>): Array<string>; 306 307 /** 308 * Called back when an ability prepares to save. 309 * @param reason state type when save. 310 * @param wantParam Indicates the want parameter. 311 * @returns 0 if ability agrees to save data successfully, otherwise errcode. 312 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 313 * @StageModelOnly 314 * @since 9 315 */ 316 onSaveState(reason: AbilityConstant.StateType, wantParam : {[key: string]: Object}): AbilityConstant.OnSaveResult; 317} 318