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_TRIGGER_INFO_H
17 #define OHOS_ABILITY_RUNTIME_TRIGGER_INFO_H
18 
19 #include <string>
20 #include <memory>
21 #include "want.h"
22 #include "want_params.h"
23 #include "start_options.h"
24 
25 namespace OHOS::AbilityRuntime::WantAgent {
26 class TriggerInfo final : public std::enable_shared_from_this<TriggerInfo> {
27 public:
28     /**
29      * Default constructor used to create a {@code TriggerInfo} instance.
30      *
31      */
32     TriggerInfo();
33     virtual ~TriggerInfo() = default;
34 
35     /**
36      * A constructor used to create a {@code TriggerInfo} instance based on the input parameters.
37      *
38      * @param permission Indicates the permission required for an {@link WantAgent} recipient.
39      * This parameter is valid only when the {@link WantAgent} is triggered to send common events.
40      * @param extraInfo Indicates the custom extra data you want to add for triggering an {@link WantAgent}.
41      * @param want Indicates the extra {@link ohos.aafwk.content.Want}.
42      * If {@code flags} in {@link WantAgentInfo} contains {@link WantAgentConstant.Flags#CONSTANT_FLAG},
43      * this parameter is invalid. If flags contains {@link WantAgentConstant.Flags#REPLACE_ELEMENT},
44      * {@link WantAgentConstant.Flags#REPLACE_ACTION}, {@link WantAgentConstant.Flags#REPLACE_URI},
45      * {@link WantAgentConstant.Flags#REPLACE_ENTITIES}, and {@link WantAgentConstant.Flags#REPLACE_BUNDLE},
46      * the {@code element}, {@code action}, {@code uri}, {@code entities}, and {@code bundleName} attributes of the
47      * {@link ohos.aafwk.content.Want} specified in this parameter will be used to replace the
48      * corresponding attributes in the original {@link ohos.aafwk.content.Want}, respectively.
49      * If this parameter is null, the original {@link ohos.aafwk.content.Want} remains unchanged.
50      * @param code Indicates the result code provided for the target of the {@link WantAgent}.
51      */
52     TriggerInfo(const std::string &permission, const std::shared_ptr<AAFwk::WantParams> &extraInfo,
53         const std::shared_ptr<AAFwk::Want> &want, int resultCode);
54 
55     /**
56      * A constructor used to create a {@code TriggerInfo} instance based on the input parameters.
57      *
58      * @param permission Indicates the permission required for an {@link WantAgent} recipient.
59      * This parameter is valid only when the {@link WantAgent} is triggered to send common events.
60      * @param extraInfo Indicates the custom extra data you want to add for triggering an {@link WantAgent}.
61      * @param want Indicates the extra {@link ohos.aafwk.content.Want}.
62      * If {@code flags} in {@link WantAgentInfo} contains {@link WantAgentConstant.Flags#CONSTANT_FLAG},
63      * this parameter is invalid. If flags contains {@link WantAgentConstant.Flags#REPLACE_ELEMENT},
64      * {@link WantAgentConstant.Flags#REPLACE_ACTION}, {@link WantAgentConstant.Flags#REPLACE_URI},
65      * {@link WantAgentConstant.Flags#REPLACE_ENTITIES}, and {@link WantAgentConstant.Flags#REPLACE_BUNDLE},
66      * the {@code element}, {@code action}, {@code uri}, {@code entities}, and {@code bundleName} attributes of the
67      * {@link ohos.aafwk.content.Want} specified in this parameter will be used to replace the
68      * corresponding attributes in the original {@link ohos.aafwk.content.Want}, respectively.
69      * If this parameter is null, the original {@link ohos.aafwk.content.Want} remains unchanged.
70      * @param startOptions Indicates the custom start options data you want to add for triggering an {@link WantAgent}.
71      * @param code Indicates the result code provided for the target of the {@link WantAgent}.
72      */
73     TriggerInfo(const std::string &permission, const std::shared_ptr<AAFwk::WantParams> &extraInfo,
74         const std::shared_ptr<AAFwk::Want> &want, const std::shared_ptr<AAFwk::StartOptions> &startOptions,
75         int resultCode);
76 
77     /**
78      * A constructor used to create a {@code TriggerInfo} instance by copying parameters from an existing one.
79      *sender_info.cpp
80      * @param paramInfo Indicates the existing {@code TriggerInfo} object.
81      */
82     explicit TriggerInfo(const TriggerInfo &paramInfo);
83 
84     /**
85      * A copy assignment operator used to create a {@code TriggerInfo} instance by copying parameters from an existing
86      * one.
87      *
88      * @param paramInfo Indicates the existing {@code TriggerInfo} object.
89      */
90     const TriggerInfo &operator=(const TriggerInfo &paramInfo);
91 
92     /**
93      * Obtains the permission from the current {@code TriggerInfo} object.
94      *
95      * @return Returns the permission name.
96      */
97     std::string GetPermission() const;
98 
99     /**
100      * Obtains the extra data from the {@code TriggerInfo} object.
101      *
102      * @return Returns the extra data.
103      */
104     std::shared_ptr<AAFwk::WantParams> GetExtraInfo() const;
105 
106     /**
107      * Obtains the {@link ohos.aafwk.content.Want} used for triggering an {@link WantAgent}.
108      *
109      * @return Returns an {@link ohos.aafwk.content.Want} object.
110      */
111     std::shared_ptr<AAFwk::Want> GetWant() const;
112 
113     /**
114      * Obtains the startOptions from the {@code TriggerInfo} object.
115      *
116      * @return Returns the start options data.
117      */
118     std::shared_ptr<AAFwk::StartOptions> GetStartOptions() const;
119 
120     /**
121      * Obtains the result code provided for the target of the {@link WantAgent}.
122      *
123      * @return Returns the result code provided for the target of the {@link WantAgent}.
124      */
125     int GetResultCode() const;
126 
127     /**
128      * A builder class for {@link TriggerInfo} objects.
129      *
130      */
131 public:
132     class Builder final : public std::enable_shared_from_this<Builder> {
133     public:
134         /**
135          * Default constructor used to create a {@code Builder} instance.
136          *
137          */
138         Builder();
139         virtual ~Builder() = default;
140 
141         /**
142          * Sets the permission that the {@link WantAgent} recipient must have.
143          *
144          * @param permission Indicates the permission to set. This parameter is valid only when the {@link WantAgent}
145          * to trigger is intended to send a common event.
146          * @return Returns this {@code Builder} object with the specified permission.
147          */
148         std::shared_ptr<Builder> SetPermission(const std::string &permission);
149 
150         /**
151          * Sets custom data.
152          *
153          * @param params Indicates the custom data to set.
154          * @return Returns this {@code Builder} object with the custom data.
155          */
156         std::shared_ptr<Builder> SetWantParams(const std::shared_ptr<AAFwk::WantParams> &params);
157 
158         /**
159          * Sets a custom {@link ohos.aafwk.content.Want}.
160          *
161          * @param want Indicates the custom {@code Want} to set. If the member variable {@code flags} of the
162          * {@link WantAgentInfo} contains {@link WantAgentConstant.Flags#CONSTANT_FLAG}, this parameter does not
163          * take effect. If {@code flags} contains {@link WantAgentConstant.Flags#REPLACE_ELEMENT},
164          * {@link WantAgentConstant.Flags#REPLACE_ACTION}, {@link WantAgentConstant.Flags#REPLACE_URI},
165          * {@link WantAgentConstant.Flags#REPLACE_ENTITIES}, and {@link WantAgentConstant.Flags#REPLACE_BUNDLE},
166          * the {@code element}, {@code action}, {@code uri}, {@code entities}, and {@code bundleName} attributes of the
167          * {@link ohos.aafwk.content.Want} specified in this parameter will be used to replace the corresponding
168          * attributes in the original {@link ohos.aafwk.content.Want}, respectively. If this parameter is null, the
169          * original {@link ohos.aafwk.content.Want} remains unchanged.
170          * @return Returns this {@code Builder} object with the custom {@code Want}.
171          */
172         std::shared_ptr<Builder> SetWant(const std::shared_ptr<AAFwk::Want> &want);
173 
174         /**
175          * Sets the start options provided for the target of the {@link WantAgent}.
176          *
177          * @param startOptions Indicates startOptions parameter provided for the target of the {@link WantAgent}.
178          * @return Returns this {@code Builder} object with the specified start options.
179          */
180         std::shared_ptr<Builder> SetStartOptions(const std::shared_ptr<AAFwk::StartOptions> &startOptions);
181 
182         /**
183          * Sets the result code provided for the target of the {@link WantAgent}.
184          *
185          * @param code Indicates the result code provided for the target of the {@link WantAgent}.
186          * @return Returns this {@code Builder} object with the specified result code.
187          */
188         std::shared_ptr<Builder> SetResultCode(int resultCode);
189 
190         /**
191          * Creates a {@link TriggerInfo} object using all of the settings.
192          *
193          * @return Returns the created {@code TriggerInfo} object.
194          */
195         std::shared_ptr<TriggerInfo> Build();
196 
197     private:
198         std::string permission_;
199         std::shared_ptr<AAFwk::WantParams> params_;
200         std::shared_ptr<AAFwk::Want> want_;
201         std::shared_ptr<AAFwk::StartOptions> startOptions_;
202         int resultCode_ = 0;
203     };
204 
205 private:
206     std::string permission_;
207     std::shared_ptr<AAFwk::WantParams> extraInfo_;
208     std::shared_ptr<AAFwk::Want> want_;
209     std::shared_ptr<AAFwk::StartOptions> startOptions_;
210     int resultCode_ = 0;
211 };
212 }  // namespace OHOS::AbilityRuntime::WantAgent
213 #endif  // OHOS_ABILITY_RUNTIME_TRIGGER_INFO_H
214