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 I_DATASHARE_H 17 #define I_DATASHARE_H 18 19 #include <memory> 20 #include <string_ex.h> 21 #include <iremote_broker.h> 22 #include "uri.h" 23 24 #include "datashare_values_bucket.h" 25 #include "datashare_predicates.h" 26 #include "datashare_result_set.h" 27 28 namespace OHOS { 29 namespace AAFwk { 30 class IDataAbilityObserver; 31 } 32 namespace DataShare { 33 class IDataShare : public IRemoteBroker { 34 public: 35 DECLARE_INTERFACE_DESCRIPTOR(u"OHOS.DataShare.IDataShare"); 36 37 enum { 38 CMD_GET_FILE_TYPES = 1, 39 CMD_OPEN_FILE = 2, 40 CMD_OPEN_RAW_FILE = 3, 41 CMD_INSERT = 4, 42 CMD_UPDATE = 5, 43 CMD_DELETE = 6, 44 CMD_QUERY = 7, 45 CMD_GET_TYPE = 8, 46 CMD_BATCH_INSERT = 9, 47 CMD_REGISTER_OBSERVER = 10, 48 CMD_UNREGISTER_OBSERVER = 11, 49 CMD_NOTIFY_CHANGE = 12, 50 CMD_NORMALIZE_URI = 13, 51 CMD_DENORMALIZE_URI = 14, 52 }; 53 54 /** 55 * @brief Obtains the MIME types of files supported. 56 * 57 * @param uri Indicates the path of the files to obtain. 58 * @param mimeTypeFilter Indicates the MIME types of the files to obtain. This parameter cannot be null. 59 * 60 * @return Returns the matched MIME types. If there is no match, null is returned. 61 */ 62 virtual std::vector<std::string> GetFileTypes(const Uri &uri, const std::string &mimeTypeFilter) = 0; 63 64 /** 65 * @brief Opens a file in a specified remote path. 66 * 67 * @param uri Indicates the path of the file to open. 68 * @param mode Indicates the file open mode, which can be "r" for read-only access, "w" for write-only access 69 * (erasing whatever data is currently in the file), "wt" for write access that truncates any existing file, 70 * "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing data, 71 * or "rwt" for read and write access that truncates any existing file. 72 * 73 * @return Returns the file descriptor. 74 */ 75 virtual int OpenFile(const Uri &uri, const std::string &mode) = 0; 76 77 /** 78 * @brief This is like openFile, open a file that need to be able to return sub-sections of files，often assets 79 * inside of their .hap. 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 85 * data, or "rwt" for read and write access that truncates any existing file. 86 * 87 * @return Returns the RawFileDescriptor object containing file descriptor. 88 */ 89 virtual int OpenRawFile(const Uri &uri, const std::string &mode) = 0; 90 91 /** 92 * @brief Inserts a single data record into the database. 93 * 94 * @param uri Indicates the path of the data to operate. 95 * @param value Indicates the data record to insert. If this parameter is null, a blank row will be inserted. 96 * 97 * @return Returns the index of the inserted data record. 98 */ 99 virtual int Insert(const Uri &uri, const DataShareValuesBucket &value) = 0; 100 101 /** 102 * @brief Updates data records in the database. 103 * 104 * @param uri Indicates the path of data to update. 105 * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null. 106 * @param value Indicates the data to update. This parameter can be null. 107 * 108 * @return Returns the number of data records updated. 109 */ 110 virtual int Update(const Uri &uri, const DataSharePredicates &predicates, 111 const DataShareValuesBucket &value) = 0; 112 113 /** 114 * @brief Deletes one or more data records from the database. 115 * 116 * @param uri Indicates the path of the data to operate. 117 * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null. 118 * 119 * @return Returns the number of data records deleted. 120 */ 121 virtual int Delete(const Uri &uri, const DataSharePredicates &predicates) = 0; 122 123 /** 124 * @brief Deletes one or more data records from the database. 125 * 126 * @param uri Indicates the path of data to query. 127 * @param predicates Indicates filter criteria. You should define the processing logic when this parameter is null. 128 * @param columns Indicates the columns to query. If this parameter is null, all columns are queried. 129 * 130 * @return Returns the query result. 131 */ 132 virtual std::shared_ptr<DataShareResultSet> Query( 133 const Uri &uri, const DataSharePredicates &predicates, std::vector<std::string> &columns) = 0; 134 135 /** 136 * @brief Obtains the MIME type matching the data specified by the URI of the Data ability. This method should be 137 * implemented by a Data ability. Data abilities supports general data types, including text, HTML, and JPEG. 138 * 139 * @param uri Indicates the URI of the data. 140 * 141 * @return Returns the MIME type that matches the data specified by uri. 142 */ 143 virtual std::string GetType(const Uri &uri) = 0; 144 145 /** 146 * @brief Inserts multiple data records into the database. 147 * 148 * @param uri Indicates the path of the data to operate. 149 * @param values Indicates the data records to insert. 150 * 151 * @return Returns the number of data records inserted. 152 */ 153 virtual int BatchInsert(const Uri &uri, const std::vector<DataShareValuesBucket> &values) = 0; 154 155 /** 156 * @brief Registers an observer to DataObsMgr specified by the given Uri. 157 * 158 * @param uri, Indicates the path of the data to operate. 159 * @param dataObserver, Indicates the IDataAbilityObserver object. 160 */ 161 virtual bool RegisterObserver(const Uri &uri, const sptr<AAFwk::IDataAbilityObserver> &dataObserver) = 0; 162 163 /** 164 * @brief Deregisters an observer used for DataObsMgr specified by the given Uri. 165 * 166 * @param uri, Indicates the path of the data to operate. 167 * @param dataObserver, Indicates the IDataAbilityObserver object. 168 */ 169 virtual bool UnregisterObserver(const Uri &uri, const sptr<AAFwk::IDataAbilityObserver> &dataObserver) = 0; 170 171 /** 172 * @brief Notifies the registered observers of a change to the data resource specified by Uri. 173 * 174 * @param uri, Indicates the path of the data to operate. 175 * 176 * @return Return true if success. otherwise return false. 177 */ 178 virtual bool NotifyChange(const Uri &uri) = 0; 179 180 /** 181 * @brief Converts the given uri that refer to the Data ability into a normalized URI. A normalized URI can be used 182 * across devices, persisted, backed up, and restored. It can refer to the same item in the Data ability even if 183 * the context has changed. If you implement URI normalization for a Data ability, you must also implement 184 * denormalizeUri(ohos.utils.net.Uri) to enable URI denormalization. After this feature is enabled, URIs passed to 185 * any method that is called on the Data ability must require normalization verification and denormalization. The 186 * default implementation of this method returns null, indicating that this Data ability does not support URI 187 * normalization. 188 * 189 * @param uri Indicates the Uri object to normalize. 190 * 191 * @return Returns the normalized Uri object if the Data ability supports URI normalization; returns null otherwise. 192 */ 193 virtual Uri NormalizeUri(const Uri &uri) = 0; 194 195 /** 196 * @brief Converts the given normalized uri generated by normalizeUri(ohos.utils.net.Uri) into a denormalized one. 197 * The default implementation of this method returns the original URI passed to it. 198 * 199 * @param uri uri Indicates the Uri object to denormalize. 200 * 201 * @return Returns the denormalized Uri object if the denormalization is successful; returns the original Uri 202 * passed to this method if there is nothing to do; returns null if the data identified by the original Uri cannot 203 * be found in the current environment. 204 */ 205 virtual Uri DenormalizeUri(const Uri &uri) = 0; 206 }; 207 } // namespace DataShare 208 } // namespace OHOS 209 #endif // I_DATASHARE_H 210 211