1 /* 2 * Copyright (c) 2021 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_APP_CONTEXT_H 17 #define OHOS_ABILITY_RUNTIME_APP_CONTEXT_H 18 19 #include "context_container.h" 20 21 namespace OHOS { 22 namespace AppExecFwk { 23 class AppContext : public ContextContainer, public std::enable_shared_from_this<AppContext> { 24 public: 25 AppContext(); 26 virtual ~AppContext(); 27 28 /** 29 * @brief Obtains information about the current ability. 30 * The returned information includes the class name, bundle name, and other information about the current ability. 31 * 32 * @return Returns the AbilityInfo object for the current ability. 33 */ 34 const std::shared_ptr<AbilityInfo> GetAbilityInfo() override; 35 36 /** 37 * @brief Starts a new ability. 38 * An ability using the AbilityInfo.AbilityType.SERVICE or AbilityInfo.AbilityType.PAGE template uses this method 39 * to start a specific ability. The system locates the target ability from installed abilities based on the value 40 * of the want parameter and then starts it. You can specify the ability to start using the want parameter. 41 * 42 * @param want Indicates the Want containing information about the target ability to start. 43 * 44 * @param requestCode Indicates the request code returned after the ability using the AbilityInfo.AbilityType.PAGE 45 * template is started. You can define the request code to identify the results returned by abilities. The value 46 * ranges from 0 to 65535. This parameter takes effect only on abilities using the AbilityInfo.AbilityType.PAGE 47 * template. 48 * 49 * @return errCode ERR_OK on success, others on failure. 50 */ 51 ErrCode StartAbility(const AAFwk::Want &want, int requestCode) override; 52 53 /** 54 * @brief Starts a new ability with special ability start setting. 55 * 56 * @param want Indicates the Want containing information about the target ability to start. 57 * @param requestCode Indicates the request code returned after the ability is started. You can define the request 58 * code to identify the results returned by abilities. The value ranges from 0 to 65535. 59 * @param abilityStartSetting Indicates the special start setting used in starting ability. 60 * 61 * @return errCode ERR_OK on success, others on failure. 62 */ 63 ErrCode StartAbility(const Want &want, int requestCode, const AbilityStartSetting &abilityStartSetting) override; 64 65 /** 66 * @brief Destroys another ability you had previously started by calling Ability.startAbilityForResult 67 * (ohos.aafwk.content.Want, int, ohos.aafwk.ability.startsetting.AbilityStartSetting) with the same requestCode 68 * passed. 69 * 70 * @param requestCode Indicates the request code passed for starting the ability. 71 * 72 * @return errCode ERR_OK on success, others on failure. 73 */ 74 ErrCode TerminateAbility(int requestCode) override; 75 76 /** 77 * @brief Destroys the current ability. 78 * 79 * @return errCode ERR_OK on success, others on failure. 80 */ 81 ErrCode TerminateAbility() override; 82 83 /** 84 * @brief 85 * Destroys this Service ability if the number of times it has been started equals the number represented by the 86 * given {@code startId}. This method is the same as calling {@link #terminateAbility} to destroy this Service 87 * ability, except that this method helps you avoid destroying it if a client has requested a Service 88 * ability startup in {@link ohos.aafwk.ability.Ability#onCommand} but you are unaware of it. 89 * 90 * @param startId Indicates the number of startup times of this Service ability passed to 91 * {@link ohos.aafwk.ability.Ability#onCommand}. The {@code startId} is 92 * incremented by 1 every time this ability is started. For example, 93 * if this ability has been started for six times, the value of {@code startId} is {@code 6}. 94 * 95 * @return Returns {@code true} if the {@code startId} matches the number of startup times 96 * and this Service ability will be destroyed; returns {@code false} otherwise. 97 */ 98 bool TerminateAbilityResult(int startId) override; 99 100 /** 101 * @brief Obtains the bundle name of the ability that called the current ability. 102 * You can use the obtained bundle name to check whether the calling ability is allowed to receive the data you will 103 * send. If you did not use Ability.startAbilityForResult(ohos.aafwk.content.Want, int, 104 * ohos.aafwk.ability.startsetting.AbilityStartSetting) to start the calling ability, null is returned. 105 * 106 * @return Returns the bundle name of the calling ability; returns null if no calling ability is available. 107 */ 108 std::string GetCallingBundle() override; 109 110 /** 111 * @brief Connects the current ability to an ability using the AbilityInfo.AbilityType.SERVICE template. 112 * 113 * @param want Indicates the want containing information about the ability to connect 114 * 115 * @param conn Indicates the callback object when the target ability is connected. 116 * 117 * @return True means success and false means failure 118 */ 119 bool ConnectAbility(const Want &want, const sptr<AAFwk::IAbilityConnection> &conn) override; 120 121 /** 122 * @brief Disconnects the current ability from an ability 123 * 124 * @param conn Indicates the IAbilityConnection callback object passed by connectAbility after the connection 125 * is set up. The IAbilityConnection object uniquely identifies a connection between two abilities. 126 * 127 * @return errCode ERR_OK on success, others on failure. 128 */ 129 ErrCode DisconnectAbility(const sptr<AAFwk::IAbilityConnection> &conn) override; 130 131 /** 132 * @brief Destroys another ability that uses the AbilityInfo.AbilityType.SERVICE template. 133 * The current ability using either the AbilityInfo.AbilityType.SERVICE or AbilityInfo.AbilityType.PAGE 134 * template can call this method to destroy another ability that uses the AbilityInfo.AbilityType.SERVICE 135 * template. The current ability itself can be destroyed by calling the terminateAbility() method. 136 * 137 * @param want Indicates the Want containing information about the ability to destroy. 138 * 139 * @return Returns true if the ability is destroyed successfully; returns false otherwise. 140 */ 141 bool StopAbility(const AAFwk::Want &want) override; 142 143 /** 144 * @brief Starts multiple abilities. 145 * 146 * @param wants Indicates the Want containing information array about the target ability to start. 147 */ 148 void StartAbilities(const std::vector<AAFwk::Want> &wants) override; 149 150 /** 151 * @brief Obtains the unique ID of the mission containing this ability. 152 * 153 * @return Returns the unique mission ID. 154 */ 155 int GetMissionId() override; 156 157 protected: 158 sptr<IRemoteObject> GetToken() override; 159 std::mutex mutex_; 160 }; 161 } // namespace AppExecFwk 162 } // namespace OHOS 163 #endif // OHOS_ABILITY_RUNTIME_APP_CONTEXT_H 164