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_IABILITY_MONITORE_H
17 #define OHOS_ABILITY_RUNTIME_IABILITY_MONITORE_H
18 
19 #include <condition_variable>
20 #include <memory>
21 #include <mutex>
22 #include <string>
23 
24 #include "ability_delegator_infos.h"
25 
26 namespace OHOS {
27 namespace AppExecFwk {
28 class IAbilityMonitor {
29 public:
30     /**
31      * Indicates that the default timeout is 5 seconds.
32      */
33     static constexpr int64_t MAX_TIME_OUT {5000};
34 
35 public:
36     /**
37      * A constructor used to create a IAbilityMonitor instance with the input parameter passed.
38      *
39      * @param abilityName Indicates the specified ability name for monitoring the lifecycle state changes
40      * of the ability.
41      */
42     explicit IAbilityMonitor(const std::string &abilityName);
43 
44     /**
45      * A constructor used to create a IAbilityMonitor instance with the input parameter passed.
46      *
47      * @param abilityName Indicates the specified ability name for monitoring the lifecycle state changes
48      * @param moduleName Indicates the specified ability moduleName for monitoring the lifecycle state changes
49      * of the ability.
50      */
51     explicit IAbilityMonitor(const std::string &abilityName, const std::string &moduleName);
52 
53     /**
54      * Default deconstructor used to deconstruct.
55      */
56     virtual ~IAbilityMonitor() = default;
57 
58     /**
59      * Match the monitored Ability objects when newAbility objects are started or
60      * the lifecycle states of monitored abilities have changed.
61      *
62      * @param ability Indicates the ability.
63      * @param isNotify Indicates whether to notify the matched ability to the object who waited.
64      * @return true if match is successful; returns false otherwise.
65      */
66     virtual bool Match(const std::shared_ptr<ADelegatorAbilityProperty> &ability, bool isNotify = false);
67 
68     /**
69      * Waits for and returns the started Ability object that matches the conditions specified in this monitor
70      * within 5 seconds.
71      * The current thread will be blocked until the 5-second default timer expires.
72      *
73      * @return the Ability object if any object has started is matched within 5 seconds; returns null otherwise.
74      */
75     virtual std::shared_ptr<ADelegatorAbilityProperty> WaitForAbility();
76 
77     /**
78      * Waits for and returns the started Ability object that matches the conditions specified in this monitor
79      * within the specified time.
80      * The current thread will be blocked until the timer specified by timeoutMillisecond expires.
81      *
82      * @param timeoutMs Indicates the maximum amount of time to wait, in milliseconds.
83      * The value must be a positive integer.
84      * @return the Ability object if any object has started is matched within the specified time;
85      * returns null otherwise.
86      */
87     virtual std::shared_ptr<ADelegatorAbilityProperty> WaitForAbility(const int64_t timeoutMs);
88 
89     /**
90      * Called when ability is started.
91      *
92      * @param abilityObj Indicates the ability object.
93      */
94     virtual void OnAbilityStart(const std::weak_ptr<NativeReference> &abilityObj);
95 
96     /**
97      * Called when ability is in foreground.
98      *
99      * @param abilityObj Indicates the ability object.
100      */
101     virtual void OnAbilityForeground(const std::weak_ptr<NativeReference> &abilityObj);
102 
103     /**
104      * Called when ability is in background.
105      *
106      * @param abilityObj Indicates the ability object.
107      */
108     virtual void OnAbilityBackground(const std::weak_ptr<NativeReference> &abilityObj);
109 
110     /**
111      * Called when ability is stopped.
112      *
113      * @param abilityObj Indicates the ability object.
114      */
115     virtual void OnAbilityStop(const std::weak_ptr<NativeReference> &abilityObj);
116 
117     /**
118      * Called when window stage is created.
119      *
120      * @param abilityObj Indicates the ability object.
121      */
122     virtual void OnWindowStageCreate(const std::weak_ptr<NativeReference> &abilityObj);
123 
124     /**
125      * Called when window stage is restored.
126      *
127      * @param abilityObj Indicates the ability object.
128      */
129     virtual void OnWindowStageRestore(const std::weak_ptr<NativeReference> &abilityObj);
130 
131     /**
132      * Called when window stage is destroyed.
133      *
134      * @param abilityObj Indicates the ability object.
135      */
136     virtual void OnWindowStageDestroy(const std::weak_ptr<NativeReference> &abilityObj);
137 
138 private:
139     std::string abilityName_;
140     std::string moduleName_;
141     std::shared_ptr<ADelegatorAbilityProperty> matchedAbility_;
142 
143     std::condition_variable cvMatch_;
144     std::mutex mMatch_;
145 };
146 }  // namespace AppExecFwk
147 }  // namespace OHOS
148 
149 #endif  // OHOS_ABILITY_RUNTIME_IABILITY_MONITORE_H
150