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_HELPER_H 17 #define DATASHARE_HELPER_H 18 19 #include <list> 20 #include <map> 21 #include <memory> 22 #include <mutex> 23 #include <string> 24 25 #include "data_ability_observer_interface.h" 26 #include "datashare_business_error.h" 27 #include "datashare_errno.h" 28 #include "datashare_observer.h" 29 #include "datashare_operation_statement.h" 30 #include "datashare_predicates.h" 31 #include "datashare_result_set.h" 32 #include "datashare_template.h" 33 #include "datashare_values_bucket.h" 34 #include "uri.h" 35 36 using Uri = OHOS::Uri; 37 38 namespace OHOS { 39 namespace AppExecFwk { 40 class PacMap; 41 class IDataAbilityObserver; 42 } // namespace AppExecFwk 43 44 namespace DataShare { 45 using string = std::string; 46 class DataShareHelper : public std::enable_shared_from_this<DataShareHelper> { 47 public: 48 /** 49 * @brief Destructor. 50 */ 51 virtual ~DataShareHelper() = default; 52 53 /** 54 * @brief You can use this method to specify the Uri of the data to operate and set the binding relationship 55 * between the ability using the Data template (data share for short) and the associated client process in 56 * a DataShareHelper instance. 57 * 58 * @param token Indicates the System token. 59 * @param strUri Indicates the database table or disk file to operate. 60 * @param waitTime connect extension waiting time. 61 * 62 * @return Returns the created DataShareHelper instance. 63 */ 64 [[deprecated( 65 "Use Create(const sptr<IRemoteObject> &, const std::string &, const std::string &, const int &) instead.")]] 66 static std::shared_ptr<DataShareHelper> Creator(const sptr<IRemoteObject> &token, 67 const std::string &strUri, const std::string &extUri = "", const int waitTime = 2); 68 69 /** 70 * @brief Creates a DataShareHelper instance with the Uri and {@link #CreateOptions} . 71 * 72 * @param strUri Indicates the database table or disk file to operate. 73 * @param options Indicates the optional config. 74 * @param waitTime connect extension waiting time. 75 * 76 * @return Returns the created DataShareHelper instance with a specified Uri. 77 */ 78 [[deprecated( 79 "Use Create(const sptr<IRemoteObject> &, const std::string &,const std::string &, const int &) instead.")]] 80 static std::shared_ptr<DataShareHelper> Creator(const std::string &strUri, const CreateOptions &options, 81 const std::string &bundleName = "", const int waitTime = 2); 82 83 /** 84 * @brief Creates a DataShareHelper instance, priority silent access, use non-silent access when silent is not 85 * available, at this time, it is necessary to apply for communication permission with the extension. 86 * 87 * @param token Indicates the System token. 88 * @param strUri Indicates the database table or disk file to operate for silent access. 89 * @param extUri Indicates the database table or disk file to operate for non silent access. 90 * @param waitTime connect extension waiting time. 91 * 92 * @return Returns the created DataShareHelper instance with a specified Uri. 93 */ 94 static std::pair<int, std::shared_ptr<DataShareHelper>> Create(const sptr<IRemoteObject> &token, 95 const std::string &strUri, const std::string &extUri, const int waitTime = 2); 96 97 /** 98 * @brief Releases the client resource of the Data share. 99 * You should call this method to releases client resource after the data operations are complete. 100 * 101 * @return Returns true if the resource is successfully released; returns false otherwise. 102 */ 103 virtual bool Release() = 0; 104 105 /** 106 * @brief Obtains the MIME types of files supported. 107 * 108 * @param uri Indicates the path of the files to obtain. 109 * @param mimeTypeFilter Indicates the MIME types of the files to obtain. This parameter cannot be null. 110 * 111 * @return Returns the matched MIME types. If there is no match, null is returned. 112 */ 113 virtual std::vector<std::string> GetFileTypes(Uri &uri, const std::string &mimeTypeFilter) = 0; 114 115 /** 116 * @brief Opens a file in a specified remote path. 117 * 118 * @param uri Indicates the path of the file to open. 119 * @param mode Indicates the file open mode, which can be "r" for read-only access, "w" for write-only access 120 * (erasing whatever data is currently in the file), "wt" for write access that truncates any existing file, 121 * "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing data, 122 * or "rwt" for read and write access that truncates any existing file. 123 * 124 * @return Returns the file descriptor. 125 */ 126 virtual int OpenFile(Uri &uri, const std::string &mode) = 0; 127 128 /** 129 * @brief This is like openFile, open a file that need to be able to return sub-sections of files，often assets 130 * inside of their .hap. 131 * 132 * @param uri Indicates the path of the file to open. 133 * @param mode Indicates the file open mode, which can be "r" for read-only access, "w" for write-only access 134 * (erasing whatever data is currently in the file), "wt" for write access that truncates any existing file, 135 * "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing 136 * data, or "rwt" for read and write access that truncates any existing file. 137 * 138 * @return Returns the RawFileDescriptor object containing file descriptor. 139 */ 140 virtual int OpenRawFile(Uri &uri, const std::string &mode) = 0; 141 142 /** 143 * @brief Inserts a single data record into the database. 144 * 145 * @param uri Indicates the path of the data to operate. 146 * @param value Indicates the data record to insert. If this parameter is null, a blank row will be inserted. 147 * 148 * @return Returns the index of the inserted data record. 149 */ 150 [[deprecated("Use InsertEx(Uri &, const DataShareValuesBucket &) instead.")]] 151 virtual int Insert(Uri &uri, const DataShareValuesBucket &value) = 0; 152 153 /** 154 * @brief Inserts a single data record into the database. 155 * 156 * @param uri Indicates the path of the data to operate. 157 * @param value Indicates the data record to insert. If this parameter is null, a blank row will be inserted. 158 * @param result Indicates the result string of the insert operation. 159 * 160 * @return Returns the index of the inserted data record. 161 */ 162 virtual int InsertExt(Uri &uri, const DataShareValuesBucket &value, std::string &result) = 0; 163 164 /** 165 * @brief Updates data records in the database. 166 * 167 * @param uri Indicates the path of data to update. 168 * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null. 169 * @param value Indicates the data to update. This parameter can be null. 170 * 171 * @return Returns the number of data records updated. 172 */ 173 [[deprecated("Use UpdateEx(Uri &, const DataSharePredicates &, const DataShareValuesBucket &) instead.")]] 174 virtual int Update(Uri &uri, const DataSharePredicates &predicates, const DataShareValuesBucket &value) = 0; 175 176 /** 177 * @brief Batch updates data records in the database. 178 * 179 * @param updateOperations Indicates the param of data to update. 180 * @param results Indicates the number of data records updated. 181 * 182 * @return Return the execution results of batch updates. 183 */ 184 virtual int BatchUpdate(const UpdateOperations &operations, std::vector<BatchUpdateResult> &results) = 0; 185 186 /** 187 * @brief Deletes one or more data records from the database. 188 * 189 * @param uri Indicates the path of the data to operate. 190 * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null. 191 * 192 * @return Returns the number of data records deleted. 193 */ 194 [[deprecated("Use DeleteEx(Uri &, const DataSharePredicates &) instead.")]] 195 virtual int Delete(Uri &uri, const DataSharePredicates &predicates) = 0; 196 197 /** 198 * @brief Query records from the database. 199 * 200 * @param uri Indicates the path of data to query. 201 * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null. 202 * @param columns Indicates the columns to query. If this parameter is null, all columns are queried. 203 * @param businessError Indicates the error by query. 204 * 205 * @return Returns the query result. 206 */ 207 virtual std::shared_ptr<DataShareResultSet> Query(Uri &uri, const DataSharePredicates &predicates, 208 std::vector<std::string> &columns, DatashareBusinessError *businessError = nullptr) = 0; 209 210 /** 211 * @brief Obtains the MIME type matching the data specified by the URI of the Data share. This method should be 212 * implemented by a Data share. Data abilities supports general data types, including text, HTML, and JPEG. 213 * 214 * @param uri Indicates the URI of the data. 215 * 216 * @return Returns the MIME type that matches the data specified by uri. 217 */ 218 virtual std::string GetType(Uri &uri) = 0; 219 220 /** 221 * @brief Inserts multiple data records into the database. 222 * 223 * @param uri Indicates the path of the data to operate. 224 * @param values Indicates the data records to insert. 225 * 226 * @return Returns the number of data records inserted. 227 */ 228 virtual int BatchInsert(Uri &uri, const std::vector<DataShareValuesBucket> &values) = 0; 229 230 /** 231 * @brief Performs batch operations on the database. 232 * 233 * @param statements Indicates a list of database operation statement on the database. 234 * @param result Indicates the result of the operation. 235 * 236 * @return Returns the ipc result. 237 */ 238 virtual int ExecuteBatch(const std::vector<OperationStatement> &statements, ExecResultSet &result) = 0; 239 240 /** 241 * @brief Registers an observer to DataObsMgr specified by the given Uri. 242 * 243 * @param uri, Indicates the path of the data to operate. 244 * @param dataObserver, Indicates the IDataAbilityObserver object. 245 * 246 * @return Returns the result. Error codes are listed in DataShare datashare_errno.h and 247 * DataObs dataobs_mgr_errors.h. 248 */ 249 virtual int RegisterObserver(const Uri &uri, const sptr<AAFwk::IDataAbilityObserver> &dataObserver) = 0; 250 251 /** 252 * @brief Deregisters an observer used for DataObsMgr specified by the given Uri. 253 * 254 * @param uri, Indicates the path of the data to operate. 255 * @param dataObserver, Indicates the IDataAbilityObserver object. 256 * 257 * @return Returns the result. Error codes are listed in DataShare datashare_errno.h and 258 * DataObs dataobs_mgr_errors.h. 259 */ 260 virtual int UnregisterObserver(const Uri &uri, const sptr<AAFwk::IDataAbilityObserver> &dataObserver) = 0; 261 262 /** 263 * @brief Notifies the registered observers of a change to the data resource specified by Uri. 264 * 265 * @param uri, Indicates the path of the data to operate. 266 */ 267 virtual void NotifyChange(const Uri &uri) = 0; 268 269 /** 270 * Registers an observer to DataObsMgr specified by the given Uri. 271 * 272 * @param uri, Indicates the path of the data to operate. 273 * @param dataObserver, Indicates the IDataAbilityObserver object. 274 * @param isDescendants, Indicates the Whether to note the change of descendants. 275 */ 276 void RegisterObserverExt(const Uri &uri, std::shared_ptr<DataShareObserver> dataObserver, bool isDescendants); 277 278 /** 279 * Deregisters an observer used for DataObsMgr specified by the given Uri. 280 * 281 * @param uri, Indicates the path of the data to operate. 282 * @param dataObserver, Indicates the IDataAbilityObserver object 283 */ 284 void UnregisterObserverExt(const Uri &uri, std::shared_ptr<DataShareObserver> dataObserver); 285 286 /** 287 * Notifies the registered observers of a change to the data resource specified by Uris. 288 * 289 * @param changeInfo Indicates the info of the data to operate. 290 */ 291 void NotifyChangeExt(const DataShareObserver::ChangeInfo &changeInfo); 292 293 /** 294 * @brief Converts the given uri that refer to the Data share into a normalized URI. A normalized URI can be used 295 * across devices, persisted, backed up, and restored. It can refer to the same item in the Data share even if the 296 * context has changed. If you implement URI normalization for a Data share, you must also implement 297 * denormalizeUri(ohos.utils.net.Uri) to enable URI denormalization. After this feature is enabled, URIs passed to 298 * any method that is called on the Data share must require normalization verification and denormalization. The 299 * default implementation of this method returns null, indicating that this Data share does not support URI 300 * normalization. 301 * 302 * @param uri Indicates the Uri object to normalize. 303 * 304 * @return Returns the normalized Uri object if the Data share supports URI normalization; returns null otherwise. 305 */ 306 virtual Uri NormalizeUri(Uri &uri) = 0; 307 308 /** 309 * @brief Converts the given normalized uri generated by normalizeUri(ohos.utils.net.Uri) into a denormalized one. 310 * The default implementation of this method returns the original URI passed to it. 311 * 312 * @param uri uri Indicates the Uri object to denormalize. 313 * 314 * @return Returns the denormalized Uri object if the denormalization is successful; returns the original Uri passed 315 * to this method if there is nothing to do; returns null if the data identified by the original Uri cannot be found 316 * in the current environment. 317 */ 318 virtual Uri DenormalizeUri(Uri &uri) = 0; 319 320 /** 321 * @brief Adds a template of {@link #SubscribeRdbData}. 322 * @param uri, the uri to add. 323 * @param subscriberId, the subscribe id to add. 324 * @param tpl, the template to add. 325 * @return Returns the error code. 326 */ 327 virtual int AddQueryTemplate(const std::string &uri, int64_t subscriberId, Template &tpl) = 0; 328 329 /** 330 * @brief Deletes a template of {@link #SubscribeRdbData} 331 * @param uri, the uri to delete. 332 * @param subscriberId, the subscribe id to delete. 333 * @return Returns the error code. 334 */ 335 virtual int DelQueryTemplate(const std::string &uri, int64_t subscriberId) = 0; 336 337 /** 338 * @brief Update a single data into host data area. 339 * @param data, the data to publish. 340 * @param bundleName the bundleName of data to publish. 341 * @return Returns the error code. 342 */ 343 virtual std::vector<OperationResult> Publish(const Data &data, const std::string &bundleName) = 0; 344 345 /** 346 * @brief Get published data by bundleName. 347 * @param bundleName, the bundleName of data. 348 * @param resultCode, the errcode returned by function 349 * @return Data {@link #Data} 350 */ 351 virtual Data GetPublishedData(const std::string &bundleName, int &resultCode) = 0; 352 353 /** 354 * @brief Registers observers to observe rdb data specified by the given uris and template. 355 * @param uris, the paths of the data to operate. 356 * @param templateId, the template of observers. 357 * @param callback, the callback function of observers. 358 * @return Returns the error code. 359 */ 360 virtual std::vector<OperationResult> SubscribeRdbData(const std::vector<std::string> &uris, 361 const TemplateId &templateId, const std::function<void(const RdbChangeNode &changeNode)> &callback) = 0; 362 363 /** 364 * @brief Unregisters observers used for monitoring data specified by the given uris and template. 365 * @param uris, the paths of the data to operate, if uris is empty, Unregisters all observers. 366 * @param templateId, the template of observers. 367 * @return Returns the error code. 368 */ 369 virtual std::vector<OperationResult> UnsubscribeRdbData(const std::vector<std::string> &uris, 370 const TemplateId &templateId) = 0; 371 372 /** 373 * @brief Enable observers by the given uris and template. 374 * @param uris, the paths of the data to operate. 375 * @param templateId, the template of observers. 376 * @return Returns the error code. 377 */ 378 virtual std::vector<OperationResult> EnableRdbSubs(const std::vector<std::string> &uris, 379 const TemplateId &templateId) = 0; 380 381 /** 382 * @brief Disable observers by the given uris and template. 383 * @param uris, the paths of the data to operate. 384 * @param templateId, the template of observers. 385 * @return Returns the error code. 386 */ 387 virtual std::vector<OperationResult> DisableRdbSubs(const std::vector<std::string> &uris, 388 const TemplateId &templateId) = 0; 389 390 /** 391 * @brief Registers observers to observe published data specified by the given uris and subscriberId. 392 * @param uris, the uris of the data to operate. 393 * @param subscriberId, the subscriberId of observers. 394 * @param callback, the callback function of observers. 395 * @return Returns the error code. 396 */ 397 virtual std::vector<OperationResult> SubscribePublishedData(const std::vector<std::string> &uris, 398 int64_t subscriberId, const std::function<void(const PublishedDataChangeNode &changeNode)> &callback) = 0; 399 400 /** 401 * @brief Unregisters observers used for monitoring data specified by the given uris and subscriberId. 402 * @param uris, the uris of the data to operate, if uris is empty, Unregisters all observers. 403 * @param subscriberId, the subscriberId of observers. 404 * @return Returns the error code. 405 */ 406 virtual std::vector<OperationResult> UnsubscribePublishedData(const std::vector<std::string> &uris, 407 int64_t subscriberId) = 0; 408 409 /** 410 * @brief Enable observers by the given uris and subscriberId. 411 * @param uris, the paths of the data to operate. 412 * @param subscriberId, the subscriberId of observers. 413 * @return Returns the error code. 414 */ 415 virtual std::vector<OperationResult> EnablePubSubs(const std::vector<std::string> &uris, int64_t subscriberId) = 0; 416 417 /** 418 * @brief Disable observers by the given uris and template. 419 * @param uris, the paths of the data to operate. 420 * @param subscriberId, the subscriberId of observers. 421 * @return Returns the error code. 422 */ 423 virtual std::vector<OperationResult> DisablePubSubs(const std::vector<std::string> &uris, int64_t subscriberId) = 0; 424 425 /** 426 * @brief Set default switch for silent access. 427 * @param uri, the uri to disable/enable. 428 * @param enable, the enable of silent switch. 429 * @return Returns the error code. 430 */ 431 static int SetSilentSwitch(Uri &uri, bool enable); 432 433 /** 434 * @brief Inserts a single data record into the database. 435 * 436 * @param uri Indicates the path of the data to operate. 437 * @param value Indicates the data record to insert. If this parameter is null, a blank row will be inserted. 438 * 439 * @return Returns pair<int32_t errCode, int32_t index>, the errCode and the index of the inserted data record. 440 */ 441 virtual std::pair<int32_t, int32_t> InsertEx(Uri &uri, const DataShareValuesBucket &value); 442 443 /** 444 * @brief Updates data records in the database. 445 * 446 * @param uri Indicates the path of data to update. 447 * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null. 448 * @param value Indicates the data to update. This parameter can be null. 449 * 450 * @return Returns pair<int32_t errCode, int32_t index>, the errCode and the index of data records updated. 451 */ 452 virtual std::pair<int32_t, int32_t> UpdateEx( 453 Uri &uri, const DataSharePredicates &predicates, const DataShareValuesBucket &value); 454 455 /** 456 * @brief Deletes one or more data records from the database. 457 * 458 * @param uri Indicates the path of the data to operate. 459 * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null. 460 * 461 * @return Returns pair<int32_t errCode, int32_t index>, the errCode and the index of data records deleted. 462 */ 463 virtual std::pair<int32_t, int32_t> DeleteEx(Uri &uri, const DataSharePredicates &predicates); 464 465 private: 466 static std::shared_ptr<DataShareHelper> CreateServiceHelper(const std::string &extUri = "", 467 const std::string &bundleName = ""); 468 469 static int GetSilentProxyStatus(const std::string &uri); 470 471 static std::shared_ptr<DataShareHelper> CreateExtHelper(Uri &uri, const sptr<IRemoteObject> &token, 472 const int waitTime = 2); 473 474 static std::string TransferUriPrefix(const std::string &originPrefix, const std::string &replacedPrefix, 475 const std::string &originUriStr); 476 477 static bool IsProxy(Uri &uri); 478 479 static std::pair<int, std::shared_ptr<DataShareHelper>> CreateProxyHelper(const std::string &strUri, 480 const std::string &extUri); 481 }; 482 } // namespace DataShare 483 } // namespace OHOS 484 #endif // DATASHARE_HELPER_H