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_WANT_AGENT_HELPER_H 17 #define OHOS_ABILITY_RUNTIME_WANT_AGENT_HELPER_H 18 19 #include <string> 20 #include <memory> 21 #include "context/application_context.h" 22 #include "completed_callback.h" 23 #include "completed_dispatcher.h" 24 #include "event_handler.h" 25 #include "nlohmann/json.hpp" 26 #include "trigger_info.h" 27 #include "want.h" 28 #include "want_agent.h" 29 #include "want_agent_info.h" 30 #include "want_params.h" 31 32 namespace OHOS::AbilityRuntime::WantAgent { 33 /** 34 * A helper class used to obtain, trigger, cancel, and compare WantAgent objects and to obtain 35 * the bundle name, UID, and hash code value of an WantAgent object. 36 * 37 */ 38 39 static const int FLAG_ONE_SHOT = 1 << 30; 40 static const int FLAG_NO_CREATE = 1 << 29; 41 static const int FLAG_CANCEL_CURRENT = 1 << 28; 42 static const int FLAG_UPDATE_CURRENT = 1 << 27; 43 static const int FLAG_IMMUTABLE = 1 << 26; 44 static const int FLAG_ALLOW_CANCEL = 1 << 20; 45 static const int FLAG_INVLID = 0; 46 47 static const int INVLID_WANT_AGENT_USER_ID = -1; 48 49 class WantAgentHelper final : public std::enable_shared_from_this<WantAgentHelper> { 50 public: 51 /** 52 * Obtains an WantAgent object. 53 * The WantAgent class does not have any constructor, and you can only use this method to create an 54 * WantAgent object. 55 * 56 * @param context Indicates the context of the caller. This parameter cannot be null. 57 * @param paramsInfo Indicates the WantAgentInfo object that contains parameters of the 58 * WantAgent object to create. 59 * @return Returns ERR_OK If get wantaget correctly. 60 */ 61 static ErrCode GetWantAgent( 62 const std::shared_ptr<OHOS::AbilityRuntime::ApplicationContext> &context, 63 const WantAgentInfo ¶msInfo, std::shared_ptr<WantAgent> &wantAgent); 64 65 /** 66 * Obtains an WantAgent object. 67 * 68 * The WantAgent class does not have any constructor, and you can only use this method to create an 69 * WantAgent object. 70 * 71 * @param paramsInfo Indicates the WantAgentInfo object that contains parameters of the 72 * WantAgent object to create. 73 * @param userId Indicates the user id for this wantagent info, default is INVLID_WANT_AGENT_USER_ID(-1). 74 * @return Returns the created WantAgent object. 75 */ 76 static std::shared_ptr<WantAgent> GetWantAgent(const WantAgentInfo ¶msInfo, 77 int32_t userId = INVLID_WANT_AGENT_USER_ID, int32_t uid = -1); 78 79 /** 80 * Obtains an WantAgent object operation type. 81 * 82 * @param agent Indicates the WantAgent to trigger. 83 * @return Returns the created WantAgent object. 84 */ 85 static WantAgentConstant::OperationType GetType(std::shared_ptr<WantAgent> agent); 86 static ErrCode GetType(const std::shared_ptr<WantAgent> &agent, int32_t &operType); 87 88 /** 89 * Triggers an WantAgent. 90 * 91 * After this method is called, events associated with the specified WantAgent will be executed, 92 * such as starting an ability or sending a common event. 93 * 94 * @param context Indicates the context of the caller. This parameter cannot be null. 95 * @param agent Indicates the WantAgent to trigger. 96 * @param onCompleted Indicates the callback method to be called after the WantAgent is triggered. 97 * This parameter can be null. 98 * @param handler Indicates the thread for executing the callback indicated by OnCompleted. 99 * If this parameter is null, the callback method will be executed in a thread in the thread pool of 100 * the current process. 101 * @param paramsInfo Indicates the TriggerInfo object that contains triggering parameters. 102 */ 103 static ErrCode TriggerWantAgent(std::shared_ptr<WantAgent> agent, 104 const std::shared_ptr<CompletedCallback> &callback, 105 const TriggerInfo ¶msInfo); 106 107 /** 108 * Cancels an WantAgent. 109 * 110 * if flags not equal FLAG_INVLID, cancel only when flags match wantAgent flags. 111 * 112 * @param agent Indicates the WantAgent to cancel. 113 * @param flags Indicates the flags to cancel, default is FLAG_INVLID(0). 114 */ 115 static ErrCode Cancel(const std::shared_ptr<WantAgent> agent, uint32_t flags = FLAG_INVLID); 116 117 /** 118 * Checks whether two WantAgent objects are the same. 119 * 120 * @param agent Indicates one of the WantAgent object to compare. 121 * @param otherAgent Indicates the other WantAgent object to compare. 122 * @return Returns ERR_OK If the two objects are the same. 123 */ 124 static ErrCode IsEquals(const std::shared_ptr<WantAgent> &agent, const std::shared_ptr<WantAgent> &otherAgent); 125 126 /** 127 * @brief Get bundle name by want agent. 128 * 129 * @param agent The WantAgent. 130 * @param bundleName BundleName obtained. 131 * @return Returns ERR_OK if get bundle name succeed. 132 */ 133 static ErrCode GetBundleName(const std::shared_ptr<WantAgent> &agent, std::string &bundleName); 134 135 /** 136 * @brief Get uid by want agent. 137 * 138 * @param agent The WantAgent. 139 * @param uid Uid obtained. 140 * @return Returns ERR_OK if get bundle name succeed. 141 */ 142 static ErrCode GetUid(const std::shared_ptr<WantAgent> &agent, int32_t &uid); 143 144 /** 145 * Obtains the Want WantAgent. 146 * 147 * @param agent Indicates the WantAgent whose Want is to be obtained. 148 * @return Returns the Want of the WantAgent. 149 */ 150 static std::shared_ptr<AAFwk::Want> GetWant(const std::shared_ptr<WantAgent> &agent); 151 static ErrCode GetWant(const std::shared_ptr<WantAgent> &agent, std::shared_ptr<AAFwk::Want> &want); 152 153 /** 154 * Register Cancel function Listener. 155 * 156 * @param cancelListener Register listener object. 157 * @param agent Indicates the WantAgent whose bundle name is to be obtained. 158 */ 159 static void RegisterCancelListener( 160 const std::shared_ptr<CancelListener> &cancelListener, const std::shared_ptr<WantAgent> &agent); 161 162 /** 163 * Unregister Cancel function Listener. 164 * 165 * @param cancelListener Register listener object. 166 * @param agent Indicates the WantAgent whose bundle name is to be obtained. 167 */ 168 static void UnregisterCancelListener( 169 const std::shared_ptr<CancelListener> &cancelListener, const std::shared_ptr<WantAgent> &agent); 170 171 /** 172 * Convert WantAgentInfo object to json string. 173 * 174 * @param jsonObject Json object. 175 * @return WantAgentInfo object's json string. 176 */ 177 static std::string ToString(const std::shared_ptr<WantAgent> &agent); 178 179 /** 180 * Convert json string to WantAgentInfo object. 181 * 182 * @param jsonString Json string. 183 * @return WantAgentInfo object. 184 */ 185 static std::shared_ptr<WantAgent> FromString(const std::string &jsonString, int32_t uid = -1); 186 187 private: 188 WantAgentHelper(); 189 virtual ~WantAgentHelper() = default; 190 191 private: 192 static ErrCode Send(const std::shared_ptr<PendingWant> &pendingWant, 193 WantAgentConstant::OperationType type, 194 const sptr<CompletedDispatcher> &callBack, 195 const TriggerInfo ¶msInfo); 196 197 static unsigned int FlagsTransformer(const std::vector<WantAgentConstant::Flags> &flags); 198 199 static std::vector<WantAgentConstant::Flags> ParseFlags(nlohmann::json jsonObject); 200 }; 201 } // namespace OHOS::AbilityRuntime::WantAgent 202 #endif // OHOS_ABILITY_RUNTIME_WANT_AGENT_HELPER_H 203