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 
16 #ifndef OHOS_ABILITY_RUNTIME_ABILITY_DELEGATOR_H
17 #define OHOS_ABILITY_RUNTIME_ABILITY_DELEGATOR_H
18 
19 #include <functional>
20 #include <list>
21 #include <map>
22 #include <memory>
23 #include <mutex>
24 #include <string>
25 #include <vector>
26 
27 #ifndef SUPPORT_GRAPHICS
28 #include "inttypes.h"
29 #endif
30 
31 #include "ability_delegator_infos.h"
32 #include "ability_lifecycle_executor.h"
33 #include "context.h"
34 #include "delegator_thread.h"
35 #include "iability_monitor.h"
36 #include "iability_stage_monitor.h"
37 #include "shell_cmd_result.h"
38 #include "test_runner.h"
39 #include "want.h"
40 
41 namespace OHOS {
42 namespace AppExecFwk {
43 class AbilityDelegator : public std::enable_shared_from_this<AbilityDelegator> {
44 public:
45     enum class AbilityState : uint8_t {
46         /**
47          * Indicates that the ability has not been initialized.
48          */
49         UNINITIALIZED = 0,
50         /**
51          * Indicates that the ability is in the started state.
52          */
53         STARTED,
54         /**
55          * Indicates that the ability is in the foreground state.
56          */
57         FOREGROUND,
58         /**
59          * Indicates that the ability is in the background state.
60          */
61         BACKGROUND,
62         /**
63          * Indicates that the ability is in the stopped state.
64          */
65         STOPPED
66     };
67 
68     /**
69      * Definition of cleanup function.
70      */
71     using ClearFunc = std::function<void(const std::shared_ptr<ADelegatorAbilityProperty> &)>;
72 
73 public:
74     /**
75      * A constructor used to create a AbilityDelegator instance with the input parameter passed.
76      *
77      * @param context Indicates the ability runtime context.
78      * @param runner Indicates the TestRunner object.
79      * @param observer Indicates the TestObserver object.
80      */
81     AbilityDelegator(const std::shared_ptr<AbilityRuntime::Context> &context, std::unique_ptr<TestRunner> runner,
82         const sptr<IRemoteObject> &observer);
83 
84     /**
85      * Default deconstructor used to deconstruct.
86      */
87     ~AbilityDelegator();
88 
89     /**
90      * Adds monitor for monitoring the lifecycle state changes of the ability.
91      *
92      * @param monitor, Indicates the monitor object.
93      */
94     void AddAbilityMonitor(const std::shared_ptr<IAbilityMonitor> &monitor);
95 
96     /**
97      * Adds monitor for monitoring the lifecycle state changes of the abilityStage.
98      *
99      * @param monitor, Indicates the stage monitor object.
100      */
101     void AddAbilityStageMonitor(const std::shared_ptr<IAbilityStageMonitor> &monitor);
102 
103     /**
104      * Removes ability monitor.
105      *
106      * @param monitor, Indicates the specified monitor object.
107      */
108     void RemoveAbilityMonitor(const std::shared_ptr<IAbilityMonitor> &monitor);
109 
110     /**
111      * Removes abilityStage monitor.
112      *
113      * @param monitor, Indicates the specified stage monitor object.
114      */
115     void RemoveAbilityStageMonitor(const std::shared_ptr<IAbilityStageMonitor> &monitor);
116 
117     /**
118      * Clears all monitors.
119      */
120     void ClearAllMonitors();
121 
122     /**
123      * Obtains the number of monitors.
124      *
125      * @return the number of monitors.
126      */
127     size_t GetMonitorsNum();
128 
129     /**
130      * Obtains the number of stage monitors.
131      *
132      * @return the number of stage monitors.
133      */
134     size_t GetStageMonitorsNum();
135 
136     /**
137      * Waits for the specified monitor and return the obtained ability.
138      *
139      * @param monitor, Indicates the specified monitor object.
140      * @return the obtained ability.
141      */
142     std::shared_ptr<ADelegatorAbilityProperty> WaitAbilityMonitor(const std::shared_ptr<IAbilityMonitor> &monitor);
143 
144     /**
145      * Waits for the specified monitor and return the obtained abilityStage.
146      *
147      * @param monitor, Indicates the specified stage monitor object.
148      * @return the obtained abilityStage.
149      */
150     std::shared_ptr<DelegatorAbilityStageProperty> WaitAbilityStageMonitor(
151         const std::shared_ptr<IAbilityStageMonitor> &monitor);
152 
153     /**
154      * Waits for the specified monitor within the timeout time and return the obtained ability.
155      *
156      * @param monitor, Indicates the specified monitor object.
157      * @param timeoutMs, Indicates the specified time out time, in milliseconds.
158      * @return the obtained ability.
159      */
160     std::shared_ptr<ADelegatorAbilityProperty> WaitAbilityMonitor(
161         const std::shared_ptr<IAbilityMonitor> &monitor, const int64_t timeoutMs);
162 
163     /**
164      * Waits for the specified monitor within the timeout time and return the obtained abilityStage.
165      *
166      * @param monitor, Indicates the specified stage monitor object.
167      * @param timeoutMs, Indicates the specified time out time, in milliseconds.
168      * @return the obtained abilityStage.
169      */
170     std::shared_ptr<DelegatorAbilityStageProperty> WaitAbilityStageMonitor(
171         const std::shared_ptr<IAbilityStageMonitor> &monitor, const int64_t timeoutMs);
172 
173     /**
174      * Obtains the application context.
175      *
176      * @return the application context.
177      */
178     std::shared_ptr<AbilityRuntime::Context> GetAppContext() const;
179 
180     /**
181      * Obtains the lifecycle state of the specified ability.
182      *
183      * @param token, Indicates the specified ability.
184      * @return the lifecycle state of the specified ability.
185      */
186     AbilityDelegator::AbilityState GetAbilityState(const sptr<IRemoteObject> &token);
187 
188     /**
189      * Obtains the ability that is currently being displayed.
190      *
191      * @return the ability that is currently being displayed.
192      */
193     std::shared_ptr<ADelegatorAbilityProperty> GetCurrentTopAbility();
194 
195     /**
196      * Obtains the name of the thread.
197      *
198      * @return the name of the thread.
199      */
200     std::string GetThreadName() const;
201 
202     /**
203      * Notifies TestRunner to prepare.
204      */
205     void Prepare();
206 
207     /**
208      * Notifies TestRunner to run.
209      */
210     void OnRun();
211 
212     /**
213      * Starts an ability based on the given Want.
214      *
215      * @param want, Indicates the Want for starting the ability.
216      * @return the result code.
217      */
218     ErrCode StartAbility(const AAFwk::Want &want);
219 
220     /**
221      * Transits the specified ability to foreground.
222      *
223      * @param token, Indicates the specified ability.
224      * @return true if succeed; returns false otherwise.
225      */
226     bool DoAbilityForeground(const sptr<IRemoteObject> &token);
227 
228     /**
229      * Transits the specified ability to background.
230      *
231      * @param token, Indicates the specified ability.
232      * @return true if succeed; returns false otherwise.
233      */
234     bool DoAbilityBackground(const sptr<IRemoteObject> &token);
235 
236     /**
237      * Executes the specified shell command.
238      *
239      * @param cmd, Indicates the specified shell command.
240      * @param timeoutSec, Indicates the specified time out time, in seconds.
241      * @return the result of the specified shell command.
242      */
243     std::unique_ptr<ShellCmdResult> ExecuteShellCommand(const std::string &cmd, const int64_t timeoutSec);
244 
245     /**
246      * Prints log information to the console.
247      * The total length of the log information to be printed cannot exceed 1000 characters.
248      *
249      * @param msg, Indicates the log information to print.
250      */
251     void Print(const std::string &msg);
252 
253     /**
254      * Saves ability properties when ability is started and notify monitors of state changes.
255      *
256      * @param ability, Indicates the ability properties.
257      */
258     void PostPerformStart(const std::shared_ptr<ADelegatorAbilityProperty> &ability);
259 
260     /**
261      * Saves abilityStage properties when abilityStage is started and notify monitors.
262      *
263      * @param abilityStage , Indicates the abilityStage properties.
264      */
265     void PostPerformStageStart(const std::shared_ptr<DelegatorAbilityStageProperty> &abilityStage);
266 
267     /**
268      * Saves ability properties when scence is created and notify monitors of state changes.
269      *
270      * @param ability, Indicates the ability properties.
271      */
272     void PostPerformScenceCreated(const std::shared_ptr<ADelegatorAbilityProperty> &ability);
273 
274     /**
275      * Saves ability properties when scence is restored and notify monitors of state changes.
276      *
277      * @param ability, Indicates the ability properties.
278      */
279     void PostPerformScenceRestored(const std::shared_ptr<ADelegatorAbilityProperty> &ability);
280 
281     /**
282      * Saves ability properties when scence is destroyed and notify monitors of state changes.
283      *
284      * @param ability, Indicates the ability properties.
285      */
286     void PostPerformScenceDestroyed(const std::shared_ptr<ADelegatorAbilityProperty> &ability);
287 
288     /**
289      * Saves ability properties when ability is in the foreground and notify monitors of state changes.
290      *
291      * @param ability, Indicates the ability properties.
292      */
293     void PostPerformForeground(const std::shared_ptr<ADelegatorAbilityProperty> &ability);
294 
295     /**
296      * Saves ability properties when ability is in the background and notify monitors of state changes.
297      *
298      * @param ability, Indicates the ability properties.
299      */
300     void PostPerformBackground(const std::shared_ptr<ADelegatorAbilityProperty> &ability);
301 
302     /**
303      * Saves ability properties when ability is stopped and notify monitors of state changes.
304      *
305      * @param ability, Indicates the ability properties.
306      */
307     void PostPerformStop(const std::shared_ptr<ADelegatorAbilityProperty> &ability);
308 
309     /**
310      * Finishes user test.
311      *
312      * @param msg, Indicates the status information.The total length of the status information cannot
313      * exceed 1000 characters.
314      * @param resultCode, Indicates the result code.
315      */
316     void FinishUserTest(const std::string &msg, const int64_t resultCode);
317 
318     /**
319      * Registers a function for cleanup.
320      *
321      * @param func, Indicates the cleanup function, called when the ability is stopped.
322      */
323     void RegisterClearFunc(ClearFunc func);
324 
325 private:
326     AbilityDelegator::AbilityState ConvertAbilityState(const AbilityLifecycleExecutor::LifecycleState lifecycleState);
327     void ProcessAbilityProperties(const std::shared_ptr<ADelegatorAbilityProperty> &ability);
328     void RemoveAbilityProperty(const std::shared_ptr<ADelegatorAbilityProperty> &ability);
329     std::shared_ptr<ADelegatorAbilityProperty> FindPropertyByToken(const sptr<IRemoteObject> &token);
330     std::shared_ptr<ADelegatorAbilityProperty> FindPropertyByName(const std::string &name);
331     inline void CallClearFunc(const std::shared_ptr<ADelegatorAbilityProperty> &ability);
332 
333 private:
334     static constexpr size_t INFORMATION_MAX_LENGTH {1000};
335     static constexpr size_t DELEGATOR_PRINT_MAX_LENGTH {10000};
336     const std::string IS_DELEGATOR_CALL = "isDelegatorCall";
337 
338 private:
339     std::shared_ptr<AbilityRuntime::Context> appContext_;
340     std::unique_ptr<TestRunner> testRunner_;
341     sptr<IRemoteObject> observer_;
342 
343     std::unique_ptr<DelegatorThread> delegatorThread_;
344     std::list<std::shared_ptr<ADelegatorAbilityProperty>> abilityProperties_;
345     std::vector<std::shared_ptr<IAbilityMonitor>> abilityMonitors_;
346     std::vector<std::shared_ptr<IAbilityStageMonitor>> abilityStageMonitors_;
347 
348     ClearFunc clearFunc_;
349 
350     std::mutex mutexMonitor_;
351     std::mutex mutexAbilityProperties_;
352     std::mutex mutexStageMonitor_;
353 };
354 }  // namespace AppExecFwk
355 }  // namespace OHOS
356 
357 #endif  // OHOS_ABILITY_RUNTIME_ABILITY_DELEGATOR_H
358