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_DATA_ABILITY_HELPER_H 17 #define OHOS_ABILITY_RUNTIME_DATA_ABILITY_HELPER_H 18 19 #include "data_ability_helper_impl.h" 20 21 namespace OHOS { 22 namespace DataShare { 23 class DataShareHelper; 24 } 25 namespace AppExecFwk { 26 class DataAbilityHelper final : public std::enable_shared_from_this<DataAbilityHelper> { 27 public: 28 ~DataAbilityHelper() = default; 29 30 /** 31 * @brief Creates a DataAbilityHelper instance without specifying the Uri based on the given Context. 32 * 33 * @param context Indicates the Context object on OHOS. 34 * 35 * @return Returns the created DataAbilityHelper instance where Uri is not specified. 36 */ 37 static std::shared_ptr<DataAbilityHelper> Creator(const std::shared_ptr<Context> context); 38 39 /** 40 * @brief Creates a DataAbilityHelper instance with the Uri specified based on the given Context. 41 * 42 * @param context Indicates the Context object on OHOS. 43 * @param uri Indicates the database table or disk file to operate. 44 * 45 * @return Returns the created DataAbilityHelper instance with a specified Uri. 46 */ 47 static std::shared_ptr<DataAbilityHelper> Creator( 48 const std::shared_ptr<Context> context, const std::shared_ptr<Uri> &uri); 49 50 /** 51 * @brief Creates a DataAbilityHelper instance with the Uri specified based on the given Context. 52 * 53 * @param context Indicates the Context object on OHOS. 54 * @param uri Indicates the database table or disk file to operate. 55 * 56 * @return Returns the created DataAbilityHelper instance with a specified Uri. 57 */ 58 static std::shared_ptr<DataAbilityHelper> Creator( 59 const std::shared_ptr<OHOS::AbilityRuntime::Context> context, const std::shared_ptr<Uri> &uri); 60 61 /** 62 * @brief You can use this method to specify the Uri of the data to operate and set the binding relationship 63 * between the ability using the Data template (Data ability for short) and the associated client process in 64 * a DataAbilityHelper instance. 65 * 66 * @param context Indicates the Context object on OHOS. 67 * @param uri Indicates the database table or disk file to operate. 68 * @param tryBind Specifies whether the exit of the corresponding Data ability process causes the exit of the 69 * client process. 70 * 71 * @return Returns the created DataAbilityHelper instance. 72 */ 73 static std::shared_ptr<DataAbilityHelper> Creator( 74 const std::shared_ptr<Context> context, const std::shared_ptr<Uri> &uri, const bool tryBind); 75 76 /** 77 * @brief You can use this method to specify the Uri of the data to operate and set the binding relationship 78 * between the ability using the Data template (Data ability for short) and the associated client process in 79 * a DataAbilityHelper instance. 80 * 81 * @param context Indicates the Context object on OHOS. 82 * @param uri Indicates the database table or disk file to operate. 83 * @param tryBind Specifies whether the exit of the corresponding Data ability process causes the exit of the 84 * client process. 85 * 86 * @return Returns the created DataAbilityHelper instance. 87 */ 88 static std::shared_ptr<DataAbilityHelper> Creator(const std::shared_ptr<OHOS::AbilityRuntime::Context> context, 89 const std::shared_ptr<Uri> &uri, const bool tryBind); 90 91 /** 92 * @brief Creates a DataAbilityHelper instance without specifying the Uri based. 93 * 94 * @param token Indicates the System token. 95 * 96 * @return Returns the created DataAbilityHelper instance where Uri is not specified. 97 */ 98 static std::shared_ptr<DataAbilityHelper> Creator(const sptr<IRemoteObject> token); 99 100 /** 101 * @brief You can use this method to specify the Uri of the data to operate and set the binding relationship 102 * between the ability using the Data template (Data ability for short) and the associated client process in 103 * a DataAbilityHelper instance. 104 * 105 * @param token Indicates the System token. 106 * @param uri Indicates the database table or disk file to operate. 107 * 108 * @return Returns the created DataAbilityHelper instance. 109 */ 110 static std::shared_ptr<DataAbilityHelper> Creator( 111 const sptr<IRemoteObject> token, const std::shared_ptr<Uri> &uri); 112 113 /** 114 * @brief Releases the client resource of the Data ability. 115 * You should call this method to releases client resource after the data operations are complete. 116 * 117 * @return Returns true if the resource is successfully released; returns false otherwise. 118 */ 119 bool Release(); 120 /** 121 * @brief Obtains the MIME types of files supported. 122 * 123 * @param uri Indicates the path of the files to obtain. 124 * @param mimeTypeFilter Indicates the MIME types of the files to obtain. This parameter cannot be null. 125 * 126 * @return Returns the matched MIME types. If there is no match, null is returned. 127 */ 128 std::vector<std::string> GetFileTypes(Uri &uri, const std::string &mimeTypeFilter); 129 130 /** 131 * @brief Opens a file in a specified remote path. 132 * 133 * @param uri Indicates the path of the file to open. 134 * @param mode Indicates the file open mode, which can be "r" for read-only access, "w" for write-only access 135 * (erasing whatever data is currently in the file), "wt" for write access that truncates any existing file, 136 * "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing data, 137 * or "rwt" for read and write access that truncates any existing file. 138 * 139 * @return Returns the file descriptor. 140 */ 141 int OpenFile(Uri &uri, const std::string &mode); 142 143 /** 144 * @brief This is like openFile, open a file that need to be able to return sub-sections of files，often assets 145 * inside of their .hap. 146 * 147 * @param uri Indicates the path of the file to open. 148 * @param mode Indicates the file open mode, which can be "r" for read-only access, "w" for write-only access 149 * (erasing whatever data is currently in the file), "wt" for write access that truncates any existing file, 150 * "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing 151 * data, or "rwt" for read and write access that truncates any existing file. 152 * 153 * @return Returns the RawFileDescriptor object containing file descriptor. 154 */ 155 int OpenRawFile(Uri &uri, const std::string &mode); 156 157 /** 158 * @brief Inserts a single data record into the database. 159 * 160 * @param uri Indicates the path of the data to operate. 161 * @param value Indicates the data record to insert. If this parameter is null, a blank row will be inserted. 162 * 163 * @return Returns the index of the inserted data record. 164 */ 165 int Insert(Uri &uri, const NativeRdb::ValuesBucket &value); 166 167 /** 168 * @brief Updates data records in the database. 169 * 170 * @param uri Indicates the path of data to update. 171 * @param value Indicates the data to update. This parameter can be null. 172 * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null. 173 * 174 * @return Returns the number of data records updated. 175 */ 176 int Update(Uri &uri, const NativeRdb::ValuesBucket &value, const NativeRdb::DataAbilityPredicates &predicates); 177 178 /** 179 * @brief Deletes one or more data records from the database. 180 * 181 * @param uri Indicates the path of the data to operate. 182 * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null. 183 * 184 * @return Returns the number of data records deleted. 185 */ 186 int Delete(Uri &uri, const NativeRdb::DataAbilityPredicates &predicates); 187 188 std::shared_ptr<AppExecFwk::PacMap> Call( 189 const Uri &uri, const std::string &method, const std::string &arg, const AppExecFwk::PacMap &pacMap); 190 191 /** 192 * @brief Deletes one or more data records from the database. 193 * 194 * @param uri Indicates the path of data to query. 195 * @param columns Indicates the columns to query. If this parameter is null, all columns are queried. 196 * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null. 197 * 198 * @return Returns the query result. 199 */ 200 std::shared_ptr<NativeRdb::AbsSharedResultSet> Query( 201 Uri &uri, std::vector<std::string> &columns, const NativeRdb::DataAbilityPredicates &predicates); 202 203 /** 204 * @brief Obtains the MIME type matching the data specified by the URI of the Data ability. This method should be 205 * implemented by a Data ability. Data abilities supports general data types, including text, HTML, and JPEG. 206 * 207 * @param uri Indicates the URI of the data. 208 * 209 * @return Returns the MIME type that matches the data specified by uri. 210 */ 211 std::string GetType(Uri &uri); 212 213 /** 214 * @brief Reloads data in the database. 215 * 216 * @param uri Indicates the position where the data is to reload. This parameter is mandatory. 217 * @param extras Indicates the PacMap object containing the additional parameters to be passed in this call. This 218 * parameter can be null. If a custom Sequenceable object is put in the PacMap object and will be transferred across 219 * processes, you must call BasePacMap.setClassLoader(ClassLoader) to set a class loader for the custom object. 220 * 221 * @return Returns true if the data is successfully reloaded; returns false otherwise. 222 */ 223 bool Reload(Uri &uri, const PacMap &extras); 224 225 /** 226 * @brief Inserts multiple data records into the database. 227 * 228 * @param uri Indicates the path of the data to operate. 229 * @param values Indicates the data records to insert. 230 * 231 * @return Returns the number of data records inserted. 232 */ 233 int BatchInsert(Uri &uri, const std::vector<NativeRdb::ValuesBucket> &values); 234 235 /** 236 * @brief Registers an observer to DataObsMgr specified by the given Uri. 237 * 238 * @param uri, Indicates the path of the data to operate. 239 * @param dataObserver, Indicates the IDataAbilityObserver object. 240 */ 241 void RegisterObserver(const Uri &uri, const sptr<AAFwk::IDataAbilityObserver> &dataObserver); 242 243 /** 244 * @brief Deregisters an observer used for DataObsMgr specified by the given Uri. 245 * 246 * @param uri, Indicates the path of the data to operate. 247 * @param dataObserver, Indicates the IDataAbilityObserver object. 248 */ 249 void UnregisterObserver(const Uri &uri, const sptr<AAFwk::IDataAbilityObserver> &dataObserver); 250 251 /** 252 * @brief Notifies the registered observers of a change to the data resource specified by Uri. 253 * 254 * @param uri, Indicates the path of the data to operate. 255 */ 256 void NotifyChange(const Uri &uri); 257 258 /** 259 * @brief Converts the given uri that refer to the Data ability into a normalized URI. A normalized URI can be used 260 * across devices, persisted, backed up, and restored. It can refer to the same item in the Data ability even if the 261 * context has changed. If you implement URI normalization for a Data ability, you must also implement 262 * denormalizeUri(ohos.utils.net.Uri) to enable URI denormalization. After this feature is enabled, URIs passed to 263 * any method that is called on the Data ability must require normalization verification and denormalization. The 264 * default implementation of this method returns null, indicating that this Data ability does not support URI 265 * normalization. 266 * 267 * @param uri Indicates the Uri object to normalize. 268 * 269 * @return Returns the normalized Uri object if the Data ability supports URI normalization; returns null otherwise. 270 */ 271 Uri NormalizeUri(Uri &uri); 272 273 /** 274 * @brief Converts the given normalized uri generated by normalizeUri(ohos.utils.net.Uri) into a denormalized one. 275 * The default implementation of this method returns the original URI passed to it. 276 * 277 * @param uri uri Indicates the Uri object to denormalize. 278 * 279 * @return Returns the denormalized Uri object if the denormalization is successful; returns the original Uri passed 280 * to this method if there is nothing to do; returns null if the data identified by the original Uri cannot be found 281 * in the current environment. 282 */ 283 Uri DenormalizeUri(Uri &uri); 284 285 /** 286 * @brief Performs batch operations on the database. 287 * 288 * @param uri Indicates the path of data to operate. 289 * @param operations Indicates a list of database operations on the database. 290 * @return Returns the result of each operation, in array. 291 */ 292 std::vector<std::shared_ptr<DataAbilityResult>> ExecuteBatch( 293 const Uri &uri, const std::vector<std::shared_ptr<DataAbilityOperation>> &operations); 294 295 void SetCallFromJs(); 296 297 private: 298 explicit DataAbilityHelper(const std::shared_ptr<DataAbilityHelperImpl> &helperImpl); 299 explicit DataAbilityHelper(const std::shared_ptr<DataShare::DataShareHelper> &dataShareHelper); 300 301 static bool TransferScheme(const Uri &uri, Uri &dataShareUri); 302 GetDataAbilityHelperImpl()303 inline auto GetDataAbilityHelperImpl() const 304 { 305 return dataAbilityHelperImpl_; 306 } 307 GetDataShareHelper()308 inline auto GetDataShareHelper() const 309 { 310 return dataShareHelper_; 311 } 312 313 std::shared_ptr<DataAbilityHelperImpl> dataAbilityHelperImpl_ = nullptr; 314 std::shared_ptr<DataShare::DataShareHelper> dataShareHelper_ = nullptr; 315 316 bool callFromJs_ = false; // true: call from js, false: call from native 317 }; 318 319 class NAPIDataAbilityHelperWrapper { 320 public: NAPIDataAbilityHelperWrapper(std::weak_ptr<DataAbilityHelper> && dataAbilityHelper)321 explicit NAPIDataAbilityHelperWrapper(std::weak_ptr<DataAbilityHelper>&& dataAbilityHelper) 322 : dataAbilityHelper_(dataAbilityHelper) {} GetDataAbilityHelper()323 inline std::shared_ptr<DataAbilityHelper> GetDataAbilityHelper() const 324 { 325 return dataAbilityHelper_.lock(); 326 } 327 328 private: 329 std::weak_ptr<DataAbilityHelper> dataAbilityHelper_; 330 }; 331 } // namespace AppExecFwk 332 } // namespace OHOS 333 #endif // OHOS_ABILITY_RUNTIME_DATA_ABILITY_HELPER_H 334 335