1 /* 2 * Copyright (c) 2023-2025 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 #ifndef OHOS_ABILITY_RUNTIME_JS_UI_ABILITY_H 17 #define OHOS_ABILITY_RUNTIME_JS_UI_ABILITY_H 18 19 #include "ability_delegator_infos.h" 20 #include "freeze_util.h" 21 #include "js_embeddable_ui_ability_context.h" 22 #include "ui_ability.h" 23 #include "recovery_param.h" 24 25 class NativeReference; 26 27 namespace OHOS { 28 namespace AbilityRuntime { 29 class JsRuntime; 30 struct InsightIntentExecutorInfo; 31 using AbilityHandler = AppExecFwk::AbilityHandler; 32 using AbilityInfo = AppExecFwk::AbilityInfo; 33 using OHOSApplication = AppExecFwk::OHOSApplication; 34 using Want = AppExecFwk::Want; 35 using AbilityStartSetting = AppExecFwk::AbilityStartSetting; 36 using Configuration = AppExecFwk::Configuration; 37 using InsightIntentExecuteResult = AppExecFwk::InsightIntentExecuteResult; 38 using InsightIntentExecuteParam = AppExecFwk::InsightIntentExecuteParam; 39 using InsightIntentExecutorAsyncCallback = AppExecFwk::InsightIntentExecutorAsyncCallback; 40 41 struct CallOnSaveStateInfo { 42 AppExecFwk::AbilityTransactionCallbackInfo<AppExecFwk::OnSaveStateResult> *callbackInfo; 43 AppExecFwk::WantParams wantParams; 44 AppExecFwk::StateReason reason; 45 }; 46 47 struct CallObjectMethodParams { 48 bool withResult = false; 49 bool showMethodNotFoundLog = true; 50 }; 51 52 class JsUIAbility : public UIAbility { 53 public: 54 /** 55 * @brief Create a JsUIAbility instance through the singleton pattern 56 * @param runtime The runtime of the ability 57 * @return Returns the JsUIability Instance point 58 */ 59 static UIAbility *Create(const std::unique_ptr<Runtime> &runtime); 60 61 explicit JsUIAbility(JsRuntime &jsRuntime); 62 ~JsUIAbility() override; 63 64 /** 65 * @brief Init the UIability 66 * @param abilityInfo Indicate the Ability information 67 * @param application Indicates the main process 68 * @param handler the UIability EventHandler object 69 * @param token the remote token 70 */ 71 void Init(std::shared_ptr<AppExecFwk::AbilityLocalRecord> record, 72 const std::shared_ptr<OHOSApplication> application, 73 std::shared_ptr<AbilityHandler> &handler, const sptr<IRemoteObject> &token) override; 74 75 static void CreateAndBindContext(const std::shared_ptr<AbilityRuntime::AbilityContext> &abilityContext, 76 const std::unique_ptr<Runtime>& runtime); 77 78 /** 79 * @brief OnStart,Start JsUIability 80 * @param want Indicates the {@link Want} structure containing startup information about the ability 81 * @param sessionInfo Indicates the sessionInfo 82 */ 83 void OnStart(const Want &want, sptr<AAFwk::SessionInfo> sessionInfo = nullptr) override; 84 85 /** 86 * @brief Called when this ability enters the <b>STATE_STOP</b> state. 87 * The ability in the <b>STATE_STOP</b> is being destroyed. 88 * You can override this function to implement your own processing logic. 89 */ 90 void OnStop() override; 91 92 /** 93 * @brief Called when this ability enters the <b>STATE_STOP</b> state. 94 * The ability in the <b>STATE_STOP</b> is being destroyed. 95 * You can override this function to implement your own processing logic. 96 * @param callbackInfo Indicates the lifecycle transaction callback information 97 * @param isAsyncCallback Indicates whether it is an asynchronous lifecycle callback 98 */ 99 void OnStop(AppExecFwk::AbilityTransactionCallbackInfo<> *callbackInfo, bool &isAsyncCallback) override; 100 101 /** 102 * @brief The callback of OnStop. 103 */ 104 void OnStopCallback() override; 105 106 /** 107 * @brief The sync callback of OnContinue. 108 */ 109 int32_t OnContinueSyncCB(napi_value result, WantParams &wantParams, napi_value jsWantParams); 110 111 /** 112 * @brief The async callback of OnContinue. 113 */ 114 int32_t OnContinueAsyncCB(napi_ref jsWantParams, int32_t status, 115 const AppExecFwk::AbilityInfo &abilityInfo) override; 116 117 /** 118 * @brief Prepare user data of local Ability. 119 * @param wantParams Indicates the user data to be saved. 120 * @return If the ability is willing to continue and data saved successfully, it returns 0; 121 * otherwise, it returns errcode. 122 */ 123 int32_t OnContinue(WantParams &wantParams, bool &isAsyncOnContinue, 124 const AppExecFwk::AbilityInfo &abilityInfo) override; 125 126 /** 127 * @brief Update configuration 128 * @param configuration Indicates the updated configuration information. 129 */ 130 void OnConfigurationUpdated(const Configuration &configuration) override; 131 132 /** 133 * @brief Update Contextconfiguration 134 */ 135 void UpdateContextConfiguration() override; 136 137 /** 138 * @brief Called when the system configuration is updated. 139 * @param level Indicates the memory trim level, which shows the current memory usage status. 140 */ 141 void OnMemoryLevel(int level) override; 142 143 /** 144 * @brief Called when the launch mode of an ability is set to singleInstance. This happens when you re-launch an 145 * ability that has been at the top of the ability stack. 146 * @param want Indicates the new Want containing information about the ability. 147 */ 148 void OnNewWant(const Want &want) override; 149 150 /** 151 * @brief Prepare user data of local Ability. 152 * @param reason the reason why framework invoke this function 153 * @param wantParams Indicates the user data to be saved. 154 * @return result code defined in abilityConstants 155 */ 156 int32_t OnSaveState(int32_t reason, WantParams &wantParams, 157 AppExecFwk::AbilityTransactionCallbackInfo<AppExecFwk::OnSaveStateResult> *callbackInfo, 158 bool &isAsync, AppExecFwk::StateReason stateReason) override; 159 160 /** 161 * @brief Called when startAbilityForResult(ohos.aafwk.content.Want,int) is called to start an ability and the 162 * result is returned. This method is called only on Page abilities. You can start a new ability to perform some 163 * calculations and use setResult (int,ohos.aafwk.content.Want) to return the calculation result. Then the system 164 * calls back the current method to use the returned data to execute its own logic. 165 * @param requestCode Indicates the request code returned after the ability is started. You can define the request 166 * code to identify the results returned by abilities. The value ranges from 0 to 65535. 167 * @param resultCode Indicates the result code returned after the ability is started. You can define the result code 168 * to identify an error. 169 * @param want Indicates the data returned after the ability is started. You can define the data returned. The 170 * value can be null. 171 */ 172 void OnAbilityResult(int requestCode, int resultCode, const Want &resultData) override; 173 174 /** 175 * @brief request a remote object of callee from this ability. 176 * @return Returns the remote object of callee. 177 */ 178 sptr<IRemoteObject> CallRequest() override; 179 180 /** 181 * @brief dump ability info 182 * @param params dump params that indicate different dump targets 183 * @param info dump ability info 184 */ 185 void Dump(const std::vector<std::string> ¶ms, std::vector<std::string> &info) override; 186 187 void OnAfterFocusedCommon(bool isFocused) override; 188 189 /** 190 * @brief Get JsAbility 191 * @return Return the JsAbility 192 */ 193 std::shared_ptr<NativeReference> GetJsAbility(); 194 195 /** 196 * @brief Callback when the ability is shared.You can override this function to implement your own sharing logic. 197 * @param wantParams Indicates the user data to be saved. 198 * @return the result of OnShare 199 */ 200 int32_t OnShare(WantParams &wantParams) override; 201 202 /** 203 * @brief Set the continueState of an application to window. 204 * @param state Indicates the continueState of an application. 205 */ 206 void SetContinueState(int32_t state) override; 207 208 void NotifyWindowDestroy() override; 209 210 #ifdef SUPPORT_SCREEN 211 public: 212 /** 213 * @brief Called after instantiating WindowScene. 214 * You can override this function to implement your own processing logic. 215 */ 216 void OnSceneCreated() override; 217 218 /** 219 * @brief Called after ability stoped. 220 * You can override this function to implement your own processing logic. 221 */ 222 void OnSceneWillDestroy() override; 223 224 /** 225 * @brief Called after ability stoped. 226 * You can override this function to implement your own processing logic. 227 */ 228 void onSceneDestroyed() override; 229 230 /** 231 * @brief Called after ability restored. 232 * You can override this function to implement your own processing logic. 233 */ 234 void OnSceneRestored() override; 235 236 /** 237 * @brief Called when this ability enters the <b>STATE_FOREGROUND</b> state. 238 * The ability in the <b>STATE_FOREGROUND</b> state is visible. 239 * You can override this function to implement your own processing logic. 240 */ 241 void OnForeground(const Want &want) override; 242 243 /** 244 * @brief Call "onForeground" js function barely. 245 * 246 * @param want Want 247 */ 248 void CallOnForegroundFunc(const Want &want) override; 249 250 /** 251 * @brief Request focus for current window, can be override. 252 * 253 * @param want Want 254 */ 255 void RequestFocus(const Want &want) override; 256 257 /** 258 * @brief Called when this ability enters the <b>STATE_BACKGROUND</b> state. 259 * The ability in the <b>STATE_BACKGROUND</b> state is invisible. 260 * You can override this function to implement your own processing logic. 261 */ 262 void OnBackground() override; 263 264 /** 265 * @brief Called before this ability enters the <b>STATE_FOREGROUND</b> state. 266 * The ability in the <b>STATE_FOREGROUND</b> state is invisible. 267 * You can override this function to implement your own processing logic. 268 */ 269 void OnWillForeground() override; 270 271 /** 272 * @brief Called after wms show event. 273 * The ability in the <b>STATE_FOREGROUND</b> state is invisible. 274 * You can override this function to implement your own processing logic. 275 */ 276 void OnDidForeground() override; 277 278 /** 279 * @brief Called before OnBackground. 280 * The ability in the <b>STATE_BACKGROUND</b> state is invisible. 281 * You can override this function to implement your own processing logic. 282 */ 283 void OnWillBackground() override; 284 285 /** 286 * @brief Called after wms hiden event. 287 * The ability in the <b>STATE_BACKGROUND</b> state is invisible. 288 * You can override this function to implement your own processing logic. 289 */ 290 void OnDidBackground() override; 291 292 /** 293 * Called when back press is dispatched. 294 * Return true if ability will be moved to background; return false if will be terminated 295 */ 296 bool OnBackPress() override; 297 298 /** 299 * @brief Called when ability prepare terminate. 300 * @param callbackInfo The callbackInfo is used when onPrepareToTerminateAsync is implemented. 301 * @param isAsync The returned flag indicates if onPrepareToTerminateAsync is implemented. 302 */ 303 void OnPrepareTerminate(AppExecFwk::AbilityTransactionCallbackInfo<bool> *callbackInfo, bool &isAsync) override; 304 305 /** 306 * @brief Get JsWindow Stage 307 * @return Returns the current NativeReference 308 */ 309 std::shared_ptr<NativeReference> GetJsWindowStage(); 310 311 /** 312 * @brief Get JsRuntime 313 * @return Returns the current JsRuntime 314 */ 315 const JsRuntime &GetJsRuntime(); 316 317 /** 318 * @brief Execute insight intent when an ability is in foreground, schedule it to foreground repeatly. 319 * 320 * @param want Want. 321 * @param executeParam insight intent execute param. 322 * @param callback insight intent async callback. 323 */ 324 void ExecuteInsightIntentRepeateForeground(const Want &want, 325 const std::shared_ptr<InsightIntentExecuteParam> &executeParam, 326 std::unique_ptr<InsightIntentExecutorAsyncCallback> callback) override; 327 328 /** 329 * @brief Execute insight intent when an ability didn't started or in background, schedule it to foreground. 330 * 331 * @param want Want. 332 * @param executeParam insight intent execute param. 333 * @param callback insight intent async callback. 334 */ 335 void ExecuteInsightIntentMoveToForeground(const Want &want, 336 const std::shared_ptr<InsightIntentExecuteParam> &executeParam, 337 std::unique_ptr<InsightIntentExecutorAsyncCallback> callback) override; 338 339 /** 340 * @brief Execute insight intent when an ability start with page insight intent. 341 * 342 * @param want Want. 343 * @param executeParam insight intent execute param. 344 * @param callback insight intent async callback. 345 */ 346 void ExecuteInsightIntentPage(const AAFwk::Want &want, 347 const std::shared_ptr<InsightIntentExecuteParam> &executeParam, 348 std::unique_ptr<InsightIntentExecutorAsyncCallback> callback) override; 349 350 /** 351 * @brief Execute insight intent when an ability didn't started, schedule it to background. 352 * 353 * @param want Want. 354 * @param executeParam insight intent execute param. 355 * @param callback insight intent async callback. 356 */ 357 virtual void ExecuteInsightIntentBackground(const AAFwk::Want &want, 358 const std::shared_ptr<InsightIntentExecuteParam> &executeParam, 359 std::unique_ptr<InsightIntentExecutorAsyncCallback> callback) override; 360 361 /** 362 * @brief Called when distributed system trying to collaborate remote ability. 363 * @param want want with collaborative info. 364 */ 365 void HandleCollaboration(const Want &want) override; 366 367 /** 368 * @brief Called when startAbility request failed. 369 * @param requestId, the requestId. 370 * @param element, the element to start ability. 371 * @param message, the message to be returned to the calling app. 372 */ 373 void OnAbilityRequestFailure(const std::string &requestId, const AppExecFwk::ElementName &element, 374 const std::string &message, int32_t resultCode = 0) override; 375 376 /** 377 * @brief Called when startAbility request succeeded. 378 * @param requestId, the requestId. 379 * @param element, the element to start ability. 380 * @param message, the message to be returned to the calling app. 381 */ 382 void OnAbilityRequestSuccess(const std::string &requestId, const AppExecFwk::ElementName &element, 383 const std::string &message) override; 384 385 protected: 386 void DoOnForeground(const Want &want) override; 387 void ContinuationRestore(const Want &want) override; 388 389 private: 390 bool IsRestorePageStack(const Want &want); 391 void RestorePageStack(const Want &want); 392 void GetPageStackFromWant(const Want &want, std::string &pageStack); 393 void AbilityContinuationOrRecover(const Want &want); 394 void UpdateJsWindowStage(napi_value windowStage); 395 inline bool GetInsightIntentExecutorInfo(const Want &want, 396 const std::shared_ptr<InsightIntentExecuteParam> &executeParam, 397 InsightIntentExecutorInfo& executeInfo); 398 int32_t OnCollaborate(WantParams &wantParams); 399 void SetInsightIntentParam(const Want &want, bool coldStart); 400 401 std::shared_ptr<NativeReference> jsWindowStageObj_; 402 int32_t windowMode_ = 0; 403 #endif 404 405 private: 406 napi_value CallObjectMethod(const char *name, napi_value const *argv = nullptr, size_t argc = 0, 407 bool withResult = false, bool showMethodNotFoundLog = true); 408 napi_value CallObjectMethod(const char *name, bool &hasCaughtException, 409 const CallObjectMethodParams &callObjectMethodParams, napi_value const *argv = nullptr, size_t argc = 0); 410 bool CheckPromise(napi_value result); 411 bool CallPromise(napi_value result, AppExecFwk::AbilityTransactionCallbackInfo<> *callbackInfo); 412 bool CallPromise(napi_value result, AppExecFwk::AbilityTransactionCallbackInfo<int32_t> *callbackInfo); 413 bool CallPromise(napi_value result, AppExecFwk::AbilityTransactionCallbackInfo<bool> *callbackInfo); 414 int32_t CallSaveStatePromise(napi_value result, CallOnSaveStateInfo info); 415 std::unique_ptr<NativeReference> CreateAppWindowStage(); 416 sptr<IRemoteObject> SetNewRuleFlagToCallee(napi_env env, napi_value remoteJsObj); 417 void SetAbilityContext(std::shared_ptr<AbilityInfo> abilityInfo, 418 std::shared_ptr<AAFwk::Want> want, const std::string &moduleName, const std::string &srcPath); 419 void DoOnForegroundForSceneIsNull(const Want &want); 420 void GetDumpInfo( 421 napi_env env, napi_value dumpInfo, napi_value onDumpInfo, std::vector<std::string> &info); 422 void AddLifecycleEventBeforeJSCall(FreezeUtil::TimeoutState state, const std::string &methodName) const; 423 void AddLifecycleEventAfterJSCall(FreezeUtil::TimeoutState state, const std::string &methodName) const; 424 void CreateJSContext(napi_env env, napi_value &contextObj, int32_t screenMode); 425 bool CheckSatisfyTargetAPIVersion(int32_t targetAPIVersion); 426 bool BackPressDefaultValue(); 427 void UpdateAbilityObj(std::shared_ptr<AbilityInfo> abilityInfo, 428 const std::string &moduleName, const std::string &srcPath); 429 void ReleaseOnContinueAsset(const napi_env env, napi_value &promise, 430 napi_ref &jsWantParamsRef, AppExecFwk::AbilityTransactionCallbackInfo<int32_t> *callbackInfo); 431 void RemoveShareRouterByBundleType(const Want &want); 432 void HandleAbilityDelegatorStart(); 433 434 JsRuntime &jsRuntime_; 435 std::shared_ptr<NativeReference> shellContextRef_; 436 std::shared_ptr<NativeReference> jsAbilityObj_; 437 sptr<IRemoteObject> remoteCallee_; 438 bool reusingWindow_ = false; 439 }; 440 } // namespace AbilityRuntime 441 } // namespace OHOS 442 #endif // OHOS_ABILITY_RUNTIME_JS_UI_ABILITY_H 443