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 #ifndef OHOS_ABILITY_RUNTIME_ABILITY_CONTEXT_H 17 #define OHOS_ABILITY_RUNTIME_ABILITY_CONTEXT_H 18 19 #include "ability_connect_callback.h" 20 #include "ability_info.h" 21 #include "ability_lifecycle_observer_interface.h" 22 #include "caller_callback.h" 23 #include "configuration.h" 24 #include "context.h" 25 #include "free_install_observer_interface.h" 26 #include "iability_callback.h" 27 #include "js_ui_extension_callback.h" 28 #include "mission_info.h" 29 #include "native_engine/native_reference.h" 30 #include "native_engine/native_value.h" 31 #include "start_options.h" 32 #include "want.h" 33 #include <functional> 34 35 #ifdef SUPPORT_GRAPHICS 36 #ifdef SUPPORT_SCREEN 37 #include "pixel_map.h" 38 #endif 39 #endif 40 41 namespace OHOS { 42 namespace Ace { 43 class UIContent; 44 } 45 46 namespace AbilityRuntime { 47 using RuntimeTask = std::function<void(int, const AAFwk::Want&, bool)>; 48 using PermissionRequestTask = std::function<void(const std::vector<std::string>&, const std::vector<int>&)>; 49 using RequestDialogResultTask = std::function<void(int32_t resultCode, const AAFwk::Want&)>; 50 using AbilityConfigUpdateCallback = std::function<void(AppExecFwk::Configuration &config)>; 51 class LocalCallContainer; 52 constexpr int32_t DEFAULT_INVAL_VALUE = -1; 53 class AbilityContext : public Context { 54 public: 55 virtual ~AbilityContext() = default; 56 57 /** 58 * @brief Starts a new ability. 59 * An ability using the AbilityInfo.AbilityType.SERVICE or AbilityInfo.AbilityType.PAGE template uses this method 60 * to start a specific ability. The system locates the target ability from installed abilities based on the value 61 * of the want parameter and then starts it. You can specify the ability to start using the want parameter. 62 * 63 * @param want Indicates the Want containing information about the target ability to start. 64 * @param requestCode Indicates the request code returned after the ability using the AbilityInfo.AbilityType.PAGE 65 * template is started. You can define the request code to identify the results returned by abilities. The value 66 * ranges from 0 to 65535. This parameter takes effect only on abilities using the AbilityInfo.AbilityType.PAGE 67 * template. 68 */ 69 virtual ErrCode StartAbility(const AAFwk::Want &want, int requestCode) = 0; 70 71 /** 72 * @brief Starts a new ability. 73 * An ability using the AbilityInfo.AbilityType.SERVICE or AbilityInfo.AbilityType.PAGE template uses this method 74 * to start a specific ability. The system locates the target ability from installed abilities based on the value 75 * of the want parameter and then starts it. You can specify the ability to start using the want parameter. 76 * 77 * @param want Indicates the Want containing information about the target ability to start. 78 * @param accountId ability caller accountId. 79 * @param requestCode Indicates the request code returned after the ability using the AbilityInfo.AbilityType.PAGE 80 * template is started. You can define the request code to identify the results returned by abilities. The value 81 * ranges from 0 to 65535. This parameter takes effect only on abilities using the AbilityInfo.AbilityType.PAGE 82 * template. 83 */ 84 virtual ErrCode StartAbilityWithAccount(const AAFwk::Want &want, int accountId, int requestCode) = 0; 85 86 /** 87 * @brief Starts a new ability. 88 * An ability using the AbilityInfo.AbilityType.SERVICE or AbilityInfo.AbilityType.PAGE template uses this method 89 * to start a specific ability. The system locates the target ability from installed abilities based on the value 90 * of the want parameter and the value of the start options and then starts it. You can specify the ability to 91 * start using the two parameters. 92 * 93 * @param want Indicates the Want containing application side information about the target ability to start. 94 * @param startOptions Indicates the StartOptions containing service side information about the target ability to 95 * start. 96 * @param requestCode Indicates the request code returned after the ability using the AbilityInfo.AbilityType.PAGE 97 * template is started. You can define the request code to identify the results returned by abilities. The value 98 * ranges from 0 to 65535. This parameter takes effect only on abilities using the AbilityInfo.AbilityType.PAGE 99 * template. 100 */ 101 virtual ErrCode StartAbility(const AAFwk::Want &want, const AAFwk::StartOptions &startOptions, int requestCode) = 0; 102 103 /** 104 * @brief Starts a new ability using the original caller information. 105 * Start a new ability as if it was started by the ability that started current ability. This is for the confirm 106 * ability and selection ability, which passthrough their want to the target. 107 * 108 * @param want Indicates the Want containing information about the target ability to start. 109 * @param requestCode Indicates the request code returned after the ability using the AbilityInfo.AbilityType.PAGE 110 * template is started. You can define the request code to identify the results returned by abilities. The value 111 * ranges from 0 to 65535. This parameter takes effect only on abilities using the AbilityInfo.AbilityType.PAGE 112 * template. 113 */ 114 virtual ErrCode StartAbilityAsCaller(const AAFwk::Want &want, int requestCode) = 0; 115 116 /** 117 * @brief Starts a new ability using the original caller information. 118 * Start a new ability as if it was started by the ability that started current ability. This is for the confirm 119 * ability and selection ability, which passthrough their want to the target. 120 * 121 * @param want Indicates the Want containing information about the target ability to start. 122 * @param startOptions Indicates the StartOptions containing service side information about the target ability to 123 * start. 124 * @param requestCode Indicates the request code returned after the ability using the AbilityInfo.AbilityType.PAGE 125 * template is started. You can define the request code to identify the results returned by abilities. The value 126 * ranges from 0 to 65535. This parameter takes effect only on abilities using the AbilityInfo.AbilityType.PAGE 127 * template. 128 */ 129 virtual ErrCode StartAbilityAsCaller(const AAFwk::Want &want, const AAFwk::StartOptions &startOptions, 130 int requestCode) = 0; 131 132 /** 133 * @brief Starts a new ability. 134 * An ability using the AbilityInfo.AbilityType.SERVICE or AbilityInfo.AbilityType.PAGE template uses this method 135 * to start a specific ability. The system locates the target ability from installed abilities based on the value 136 * of the want parameter and the value of the start options and then starts it. You can specify the ability to 137 * start using the two parameters. 138 * 139 * @param want Indicates the Want containing application side information about the target ability to start. 140 * @param accountId caller userId. 141 * @param startOptions Indicates the StartOptions containing service side information about the target ability to 142 * start. 143 * @param requestCode Indicates the request code returned after the ability using the AbilityInfo.AbilityType.PAGE 144 * template is started. You can define the request code to identify the results returned by abilities. The value 145 * ranges from 0 to 65535. This parameter takes effect only on abilities using the AbilityInfo.AbilityType.PAGE 146 * template. 147 */ 148 virtual ErrCode StartAbilityWithAccount( 149 const AAFwk::Want &want, int accountId, const AAFwk::StartOptions &startOptions, int requestCode) = 0; 150 151 virtual ErrCode StartAbilityForResult(const AAFwk::Want &Want, int requestCode, RuntimeTask &&task) = 0; 152 153 virtual ErrCode StartAbilityForResultWithAccount( 154 const AAFwk::Want &Want, int accountId, int requestCode, RuntimeTask &&task) = 0; 155 156 virtual ErrCode StartAbilityForResult(const AAFwk::Want &Want, const AAFwk::StartOptions &startOptions, 157 int requestCode, RuntimeTask &&task) = 0; 158 159 virtual ErrCode StartAbilityForResultWithAccount(const AAFwk::Want &Want, int accountId, 160 const AAFwk::StartOptions &startOptions, int requestCode, RuntimeTask &&task) = 0; 161 162 virtual ErrCode StartServiceExtensionAbility(const AAFwk::Want &want, int32_t accountId = -1) = 0; 163 164 virtual ErrCode StartUIServiceExtensionAbility(const AAFwk::Want &want, int32_t accountId = -1) = 0; 165 166 virtual ErrCode StopServiceExtensionAbility(const AAFwk::Want& want, int32_t accountId = -1) = 0; 167 168 virtual ErrCode TerminateAbilityWithResult(const AAFwk::Want &want, int resultCode) = 0; 169 170 virtual ErrCode BackToCallerAbilityWithResult(const AAFwk::Want &want, int resultCode, int64_t requestCode) = 0; 171 172 virtual ErrCode RestoreWindowStage(napi_env env, napi_value contentStorage) = 0; 173 174 virtual void OnAbilityResult(int requestCode, int resultCode, const AAFwk::Want &resultData) = 0; 175 176 virtual ErrCode RequestModalUIExtension(const AAFwk::Want& want) = 0; 177 178 virtual ErrCode OpenLink(const AAFwk::Want& want, int requestCode) = 0; 179 180 virtual ErrCode OpenAtomicService(AAFwk::Want& want, const AAFwk::StartOptions &options, int requestCode, 181 RuntimeTask &&task) = 0; 182 183 virtual ErrCode AddFreeInstallObserver(const sptr<AbilityRuntime::IFreeInstallObserver> &observer) = 0; 184 ChangeAbilityVisibility(bool isShow)185 virtual ErrCode ChangeAbilityVisibility(bool isShow) { return 0; } 186 187 /** 188 * @brief Connects the current ability to an ability using the AbilityInfo.AbilityType.SERVICE template. 189 * 190 * @param want Indicates the want containing information about the ability to connect 191 * @param connectCallback Indicates the callback object when the target ability is connected. 192 * @return True means success and false means failure 193 */ 194 virtual ErrCode ConnectAbility(const AAFwk::Want &want, const sptr<AbilityConnectCallback> &connectCallback) = 0; 195 196 /** 197 * @brief Connects the current ability to an ability using the AbilityInfo.AbilityType.SERVICE template. 198 * @param want Indicates the want containing information about the ability to connect 199 * @param accountId caller userId. 200 * @param connectCallback Indicates the callback object when the target ability is connected. 201 * @return True means success and false means failure 202 */ 203 virtual ErrCode ConnectAbilityWithAccount(const AAFwk::Want &want, int accountId, 204 const sptr<AbilityConnectCallback> &connectCallback) = 0; 205 206 /** 207 * @brief Connects the current ability to an uiService ability using the AbilityInfo.AbilityType.SERVICE template. 208 * 209 * @param want Indicates the want containing information about the ability to connect 210 * @param connectCallback Indicates the callback object when the target ability is connected. 211 * @return True means success and false means failure 212 */ 213 virtual ErrCode ConnectUIServiceExtensionAbility(const AAFwk::Want& want, 214 const sptr<AbilityConnectCallback>& connectCallback) = 0; 215 216 /** 217 * @brief Disconnects the current ability from an ability 218 * 219 * @param want Indicates the want containing information about the ability to disconnect 220 * @param connectCallback Indicates the callback object when the target ability is connected. 221 * is set up. The IAbilityConnection object uniquely identifies a connection between two abilities. 222 */ 223 virtual void DisconnectAbility(const AAFwk::Want &want, const sptr<AbilityConnectCallback> &connectCallback, 224 int32_t accountId = -1) = 0; 225 226 /** 227 * @brief get ability info of the current ability 228 * 229 * @return the ability info of the current ability 230 */ 231 virtual std::shared_ptr<AppExecFwk::AbilityInfo> GetAbilityInfo() const = 0; 232 233 /** 234 * @brief Minimize the current ability. 235 * 236 * @param fromUser mark the minimize operation source. 237 */ 238 virtual void MinimizeAbility(bool fromUser = false) = 0; 239 240 /** 241 * @brief Get OnBackPressedCallBack. 242 * @param needMoveToBackground true if ability will be moved to background; false if ability will be terminated. 243 * 244 * @return Returns ERR_OK on success, others on failure. 245 */ 246 virtual ErrCode OnBackPressedCallBack(bool &needMoveToBackground) = 0; 247 248 virtual ErrCode MoveAbilityToBackground() = 0; 249 250 virtual ErrCode MoveUIAbilityToBackground() = 0; 251 252 virtual ErrCode TerminateSelf() = 0; 253 254 virtual ErrCode CloseAbility() = 0; 255 256 /** 257 * @brief Get ContentStorage. 258 * 259 * @return Returns the ContentStorage. 260 */ 261 virtual std::unique_ptr<NativeReference>& GetContentStorage() = 0; 262 263 /** 264 * call function by callback object 265 * 266 * @param want Request info for ability. 267 * @param callback Indicates the callback object. 268 * @param accountId Indicates the account to start. 269 * 270 * @return Returns zero on success, others on failure. 271 */ 272 virtual ErrCode StartAbilityByCall(const AAFwk::Want& want, const std::shared_ptr<CallerCallBack> &callback, 273 int32_t accountId = DEFAULT_INVAL_VALUE) = 0; 274 275 /** 276 * caller release by callback object 277 * 278 * @param callback Indicates the callback object. 279 * 280 * @return Returns zero on success, others on failure. 281 */ 282 virtual ErrCode ReleaseCall(const std::shared_ptr<CallerCallBack> &callback) = 0; 283 284 /** 285 * clear failed call connection by callback object 286 * 287 * @param callback Indicates the callback object. 288 * 289 * @return void. 290 */ 291 virtual void ClearFailedCallConnection(const std::shared_ptr<CallerCallBack> &callback) = 0; 292 293 /** 294 * @brief Get LocalCallContainer. 295 * 296 * @return Returns the LocalCallContainer. 297 */ 298 virtual std::shared_ptr<LocalCallContainer> GetLocalCallContainer() = 0; 299 300 virtual void SetConfiguration(const std::shared_ptr<AppExecFwk::Configuration> &config) = 0; 301 302 virtual void RegisterAbilityCallback(std::weak_ptr<AppExecFwk::IAbilityCallback> abilityCallback) = 0; 303 304 virtual void SetWeakSessionToken(const wptr<IRemoteObject>& sessionToken) = 0; 305 virtual void SetAbilityRecordId(int32_t abilityRecordId) = 0; 306 virtual int32_t GetAbilityRecordId() = 0; 307 308 /** 309 * @brief Requests dialogService from the system. 310 * This method is called for dialog request. This is an asynchronous method. When it is executed, 311 * the task will be called back. 312 * 313 * @param env js env. 314 * @param want Indicates the dialog service to be requested. 315 * @param task The callback or promise fo js interface. 316 * @return Returns ERR_OK if success. 317 */ 318 virtual ErrCode RequestDialogService(napi_env env, AAFwk::Want &want, RequestDialogResultTask &&task) = 0; 319 320 /** 321 * @brief Requests dialogService from the system. 322 * This method is called for dialog request. This is an asynchronous method. When it is executed, 323 * the task will be called back. 324 * 325 * @param want Indicates the dialog service to be requested. 326 * @param task The callback or promise fo js interface. 327 * @return Returns ERR_OK if success. 328 */ 329 virtual ErrCode RequestDialogService(AAFwk::Want &want, RequestDialogResultTask &&task) = 0; 330 331 /** 332 * @brief Report drawn completed. 333 * 334 * @return Returns ERR_OK on success, others on failure. 335 */ 336 virtual ErrCode ReportDrawnCompleted() = 0; 337 338 virtual ErrCode GetMissionId(int32_t &missionId) = 0; 339 340 /** 341 * Set mission continue state of this ability. 342 * 343 * @param state the mission continuation state of this ability. 344 * @return Returns ERR_OK if success. 345 */ 346 virtual ErrCode SetMissionContinueState(const AAFwk::ContinueState &state) = 0; 347 348 /** 349 * Register lifecycle observer on ability. 350 * 351 * @param observer the lifecycle observer to be registered on ability. 352 */ 353 virtual void RegisterAbilityLifecycleObserver(const std::shared_ptr<AppExecFwk::ILifecycleObserver> &observer) = 0; 354 355 /** 356 * Unregister lifecycle observer on ability. 357 * 358 * @param observer the lifecycle observer to be unregistered on ability. 359 */ 360 virtual void UnregisterAbilityLifecycleObserver( 361 const std::shared_ptr<AppExecFwk::ILifecycleObserver> &observer) = 0; 362 363 virtual void SetRestoreEnabled(bool enabled) = 0; 364 virtual bool GetRestoreEnabled() = 0; 365 virtual void RegisterAbilityConfigUpdateCallback(AbilityConfigUpdateCallback abilityConfigUpdateCallback) = 0; 366 virtual std::shared_ptr<AppExecFwk::Configuration> GetAbilityConfiguration() const = 0; 367 virtual void SetAbilityConfiguration(const AppExecFwk::Configuration &config) = 0; 368 virtual void SetAbilityColorMode(int32_t colorMode) = 0; 369 virtual void SetAbilityResourceManager(std::shared_ptr<Global::Resource::ResourceManager> abilityResourceMgr) = 0; 370 virtual ErrCode RevokeDelegator() = 0; 371 372 virtual std::shared_ptr<AAFwk::Want> GetWant() = 0; 373 374 #ifdef SUPPORT_GRAPHICS 375 #ifdef SUPPORT_SCREEN 376 /** 377 * @brief Set mission label of this ability. 378 * 379 * @param label the label of this ability. 380 * @return Returns ERR_OK if success. 381 */ 382 virtual ErrCode SetMissionLabel(const std::string &label) = 0; 383 384 /** 385 * @brief Set mission icon of this ability. 386 * 387 * @param icon the icon of this ability. 388 * @return Returns ERR_OK if success. 389 */ 390 virtual ErrCode SetMissionIcon(const std::shared_ptr<OHOS::Media::PixelMap> &icon) = 0; 391 392 /** 393 * @brief Set ability label and icon of this ability. 394 * 395 * @param label the label of this ability. 396 * @param icon the icon of this ability. 397 * @return Returns ERR_OK if success. 398 */ 399 virtual ErrCode SetAbilityInstanceInfo(const std::string& label, std::shared_ptr<OHOS::Media::PixelMap> icon) = 0; 400 401 virtual int GetCurrentWindowMode() = 0; 402 403 /** 404 * @brief Get window rectangle of this ability. 405 * 406 * @param the left position of window rectangle. 407 * @param the top position of window rectangle. 408 * @param the width position of window rectangle. 409 * @param the height position of window rectangle. 410 */ 411 virtual void GetWindowRect(int32_t &left, int32_t &top, int32_t &width, int32_t &height) = 0; 412 413 /** 414 * @brief Get ui content object. 415 * 416 * @return UIContent object of ACE. 417 */ 418 virtual Ace::UIContent* GetUIContent() = 0; 419 virtual ErrCode StartAbilityByType(const std::string &type, AAFwk::WantParams &wantParam, 420 const std::shared_ptr<JsUIExtensionCallback> &uiExtensionCallbacks) = 0; 421 virtual ErrCode CreateModalUIExtensionWithApp(const AAFwk::Want &want) = 0; 422 virtual void EraseUIExtension(int32_t sessionId) = 0; 423 #endif 424 #endif 425 virtual bool IsTerminating() = 0; 426 virtual void SetTerminating(bool state) = 0; 427 virtual void InsertResultCallbackTask(int requestCode, RuntimeTask&& task) = 0; 428 virtual void RemoveResultCallbackTask(int requestCode) = 0; 429 using SelfType = AbilityContext; 430 static const size_t CONTEXT_TYPE_ID; 431 432 protected: IsContext(size_t contextTypeId)433 bool IsContext(size_t contextTypeId) override 434 { 435 return contextTypeId == CONTEXT_TYPE_ID || Context::IsContext(contextTypeId); 436 } 437 }; 438 } // namespace AbilityRuntime 439 } // namespace OHOS 440 #endif // OHOS_ABILITY_RUNTIME_ABILITY_CONTEXT_H 441