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