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 DATASHARE_EXT_ABILITY_H
17 #define DATASHARE_EXT_ABILITY_H
18 
19 #include <memory>
20 #include "extension_base.h"
21 #include "datashare_business_error.h"
22 #include "datashare_values_bucket.h"
23 #include "datashare_predicates.h"
24 #include "datashare_result_set.h"
25 #include "datashare_operation_statement.h"
26 
27 namespace OHOS {
28 namespace AAFwk {
29 class IDataAbilityObserver;
30 }
31 namespace AbilityRuntime {
32 class Runtime;
33 }
34 namespace DataShare {
35 using namespace AbilityRuntime;
36 class DataShareExtAbilityContext;
37 class DataShareExtAbility;
38 using CreatorFunc = std::function<DataShareExtAbility* (const std::unique_ptr<Runtime>& runtime)>;
39 /**
40  * @brief Basic datashare extension ability components.
41  */
42 class DataShareExtAbility : public ExtensionBase<DataShareExtAbilityContext> {
43 public:
44     DataShareExtAbility() = default;
45     virtual ~DataShareExtAbility() = default;
46 
47     /**
48      * @brief Init the extension.
49      *
50      * @param record the extension record.
51      * @param application the application info.
52      * @param handler the extension handler.
53      * @param token the remote token.
54      */
55     virtual void Init(const std::shared_ptr<AbilityLocalRecord> &record,
56         const std::shared_ptr<OHOSApplication> &application,
57         std::shared_ptr<AbilityHandler> &handler,
58         const sptr<IRemoteObject> &token) override;
59 
60     /**
61      * @brief Create Extension.
62      *
63      * @param runtime The runtime.
64      * @return The DataShareExtAbility instance.
65      */
66     static DataShareExtAbility* Create(const std::unique_ptr<Runtime>& runtime);
67 
68     /**
69      * @brief Obtains the MIME types of files supported.
70      *
71      * @param uri Indicates the path of the files to obtain.
72      * @param mimeTypeFilter Indicates the MIME types of the files to obtain. This parameter cannot be null.
73      *
74      * @return Returns the matched MIME types. If there is no match, null is returned.
75      */
76     virtual std::vector<std::string> GetFileTypes(const Uri &uri, const std::string &mimeTypeFilter);
77 
78     /**
79      * @brief Opens a file in a specified remote path.
80      *
81      * @param uri Indicates the path of the file to open.
82      * @param mode Indicates the file open mode, which can be "r" for read-only access, "w" for write-only access
83      * (erasing whatever data is currently in the file), "wt" for write access that truncates any existing file,
84      * "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing data,
85      *  or "rwt" for read and write access that truncates any existing file.
86      *
87      * @return Returns the file descriptor.
88      */
89     virtual int OpenFile(const Uri &uri, const std::string &mode);
90 
91     /**
92      * @brief This is like openFile, open a file that need to be able to return sub-sections of files，often assets
93      * inside of their .hap.
94      *
95      * @param uri Indicates the path of the file to open.
96      * @param mode Indicates the file open mode, which can be "r" for read-only access, "w" for write-only access
97      * (erasing whatever data is currently in the file), "wt" for write access that truncates any existing file,
98      * "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing
99      * data, or "rwt" for read and write access that truncates any existing file.
100      *
101      * @return Returns the RawFileDescriptor object containing file descriptor.
102      */
103     virtual int OpenRawFile(const Uri &uri, const std::string &mode);
104 
105     /**
106      * @brief Inserts a single data record into the database.
107      *
108      * @param uri Indicates the path of the data to operate.
109      * @param value  Indicates the data record to insert. If this parameter is null, a blank row will be inserted.
110      *
111      * @return Returns the index of the inserted data record.
112      */
113     virtual int Insert(const Uri &uri, const DataShareValuesBucket &value);
114 
115     /**
116      * @brief Inserts a single data record into the database.
117      *
118      * @param uri Indicates the path of the data to operate.
119      * @param value  Indicates the data record to insert. If this parameter is null, a blank row will be inserted.
120      * @param result  Indicates the data result to insert.
121      *
122      * @return Returns the index of the inserted data record.
123      */
124     virtual int InsertExt(const Uri &uri, const DataShareValuesBucket &value, std::string &result);
125 
126     /**
127      * @brief Updates data records in the database.
128      *
129      * @param uri Indicates the path of data to update.
130      * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null.
131      * @param value Indicates the data to update. This parameter can be null.
132      *
133      * @return Returns the number of data records updated.
134      */
135     virtual int Update(const Uri &uri, const DataSharePredicates &predicates,
136         const DataShareValuesBucket &value);
137 
138     /**
139      * @brief Batch updates data records in the database.
140      *
141      * @param updateOperations Indicates the param of data to update.
142      * @param results Indicates the number of data records updated.
143      *
144      * @return Return the execution results of batch updates.
145      */
146     virtual int BatchUpdate(const UpdateOperations &operations, std::vector<BatchUpdateResult> &results);
147 
148     /**
149      * @brief Deletes one or more data records from the database.
150      *
151      * @param uri Indicates the path of the data to operate.
152      * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null.
153      *
154      * @return Returns the number of data records deleted.
155      */
156     virtual int Delete(const Uri &uri, const DataSharePredicates &predicates);
157 
158     /**
159      * @brief Deletes one or more data records from the database.
160      *
161      * @param uri Indicates the path of data to query.
162      * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null.
163      * @param columns Indicates the columns to query. If this parameter is null, all columns are queried.
164      * @param businessError Indicates the error by query.
165      *
166      * @return Returns the query result.
167      */
168     virtual std::shared_ptr<DataShareResultSet> Query(const Uri &uri, const DataSharePredicates &predicates,
169         std::vector<std::string> &columns, DatashareBusinessError &businessError);
170 
171     /**
172      * @brief Obtains the MIME type matching the data specified by the URI of the Data ability. This method should be
173      * implemented by a Data ability. Data abilities supports general data types, including text, HTML, and JPEG.
174      *
175      * @param uri Indicates the URI of the data.
176      *
177      * @return Returns the MIME type that matches the data specified by uri.
178      */
179     virtual std::string GetType(const Uri &uri);
180 
181     /**
182      * @brief Inserts multiple data records into the database.
183      *
184      * @param uri Indicates the path of the data to operate.
185      * @param values Indicates the data records to insert.
186      *
187      * @return Returns the number of data records inserted.
188      */
189     virtual int BatchInsert(const Uri &uri, const std::vector<DataShareValuesBucket> &values);
190 
191     /**
192      * @brief Performs batch operations on the database.
193      *
194      * @param statements Indicates a list of database operation statement on the database.
195      * @param result Indicates the result of the operation.
196      *
197      * @return Returns the ipc result.
198      */
199     virtual int ExecuteBatch(const std::vector<OperationStatement> &statements, ExecResultSet &result);
200 
201     /**
202      * @brief Registers an observer to DataObsMgr specified by the given Uri.
203      *
204      * @param uri, Indicates the path of the data to operate.
205      * @param dataObserver, Indicates the IDataAbilityObserver object.
206      */
207     virtual bool RegisterObserver(const Uri &uri, const sptr<AAFwk::IDataAbilityObserver> &dataObserver);
208 
209     /**
210      * @brief Deregisters an observer used for DataObsMgr specified by the given Uri.
211      *
212      * @param uri, Indicates the path of the data to operate.
213      * @param dataObserver, Indicates the IDataAbilityObserver object.
214      */
215     virtual bool UnregisterObserver(const Uri &uri, const sptr<AAFwk::IDataAbilityObserver> &dataObserver);
216 
217     /**
218      * @brief Notifies the registered observers of a change to the data resource specified by Uri.
219      *
220      * @param uri, Indicates the path of the data to operate.
221      *
222      * @return Return true if success. otherwise return false.
223      */
224     virtual bool NotifyChange(const Uri &uri);
225 
226     /**
227      * @brief Converts the given uri that refer to the Data ability into a normalized URI. A normalized URI can be used
228      * across devices, persisted, backed up, and restored. It can refer to the same item in the Data ability even if
229      * the context has changed. If you implement URI normalization for a Data ability, you must also implement
230      * denormalizeUri(ohos.utils.net.Uri) to enable URI denormalization. After this feature is enabled, URIs passed to
231      * any method that is called on the Data ability must require normalization verification and denormalization. The
232      * default implementation of this method returns null, indicating that this Data ability does not support URI
233      * normalization.
234      *
235      * @param uri Indicates the Uri object to normalize.
236      *
237      * @return Returns the normalized Uri object if the Data ability supports URI normalization; returns null otherwise.
238      */
239     virtual Uri NormalizeUri(const Uri &uri);
240 
241     /**
242      * @brief Converts the given normalized uri generated by normalizeUri(ohos.utils.net.Uri) into a denormalized one.
243      * The default implementation of this method returns the original URI passed to it.
244      *
245      * @param uri uri Indicates the Uri object to denormalize.
246      *
247      * @return Returns the denormalized Uri object if the denormalization is successful; returns the original Uri
248      * passed to this method if there is nothing to do; returns null if the data identified by the original Uri cannot
249      * be found in the current environment.
250      */
251     virtual Uri DenormalizeUri(const Uri &uri);
252 
253     /**
254      * @brief Set a creator function.
255      *
256      * @param creator The function for create a datashare extension ability.
257      */
258     static void SetCreator(const CreatorFunc& creator);
259 private:
260     static CreatorFunc creator_;
261 };
262 }  // namespace DataShare
263 }  // namespace OHOS
264 #endif  // DATASHARE_EXT_ABILITY_H