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 16import { AsyncCallback } from './basic'; 17import Context from './application/Context'; 18import DataShareResultSet from './@ohos.data.DataShareResultSet'; 19import dataSharePredicates from './@ohos.data.dataSharePredicates'; 20import { ValuesBucket } from './@ohos.data.ValuesBucket'; 21 22/** 23* This module provides the dataShare capability for consumer. 24* @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 25* @systemapi 26* @StageModelOnly 27* @since 9 28 */ 29declare namespace dataShare { 30 /** 31 * Obtains the dataShareHelper. 32 * @param {Context} context - Indicates the application context. 33 * @param {string} uri - Indicates the path of the file to open. 34 * @param {AsyncCallback<DataShareHelper>} callback - {DataShareHelper}: the dataShareHelper for consumer. 35 * @throws {BusinessError} 401 - the parameter check failed. 36 * @throws {BusinessError} 15700010 - the DataShareHelper is not initialized successfully. 37 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 38 * @systemapi 39 * @StageModelOnly 40 * @since 9 41 */ 42 function createDataShareHelper(context: Context, uri: string, callback: AsyncCallback<DataShareHelper>): void; 43 44 /** 45 * Obtains the dataShareHelper. 46 * @param {Context} context - Indicates the application context. 47 * @param {string} uri - Indicates the path of the file to open. 48 * @returns {Promise<DataShareHelper>} {DataShareHelper}: the dataShareHelper for consumer. 49 * @throws {BusinessError} 401 - the parameter check failed. 50 * @throws {BusinessError} 15700010 - the DataShareHelper is not initialized successfully. 51 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 52 * @systemapi 53 * @StageModelOnly 54 * @since 9 55 */ 56 function createDataShareHelper(context: Context, uri: string): Promise<DataShareHelper>; 57 58 /** 59 * DataShareHelper 60 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 61 * @systemapi 62 * @StageModelOnly 63 * @since 9 64 */ 65 interface DataShareHelper { 66 /** 67 * Registers an observer to observe data specified by the given uri. 68 * @param {string} type - type must be 'dataChange'. 69 * @param {string} uri - Indicates the path of the data to operate. 70 * @param {AsyncCallback<void>} callback - the callback of on. 71 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 72 * @systemapi 73 * @StageModelOnly 74 * @since 9 75 */ 76 on(type: 'dataChange', uri: string, callback: AsyncCallback<void>): void; 77 78 /** 79 * Deregisters an observer used for monitoring data specified by the given uri. 80 * @param {string} type - type must be 'dataChange'. 81 * @param {string} uri - Indicates the path of the data to operate. 82 * @param {AsyncCallback<void>} callback - the callback of off. 83 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 84 * @systemapi 85 * @StageModelOnly 86 * @since 9 87 */ 88 off(type: 'dataChange', uri: string, callback?: AsyncCallback<void>): void; 89 90 /** 91 * Inserts a single data record into the database. 92 * @param {string} uri - Indicates the path of the data to operate. 93 * @param {ValueBucket} value - Indicates the data record to insert. If this parameter is null, 94 * a blank row will be inserted. 95 * @param {AsyncCallback<number>} callback - {number}: the index of the inserted data record. 96 * @throws {BusinessError} 401 - the parameter check failed. 97 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 98 * @systemapi 99 * @StageModelOnly 100 * @since 9 101 */ 102 insert(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void; 103 104 /** 105 * Inserts a single data record into the database. 106 * @param {string} uri - Indicates the path of the data to operate. 107 * @param {ValueBucket} value - Indicates the data record to insert. If this parameter is null, 108 * a blank row will be inserted. 109 * @returns {Promise<number>} {number}: the index of the inserted data record. 110 * @throws {BusinessError} 401 - the parameter check failed. 111 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 112 * @systemapi 113 * @StageModelOnly 114 * @since 9 115 */ 116 insert(uri: string, value: ValuesBucket): Promise<number>; 117 118 /** 119 * Deletes one or more data records from the database. 120 * @param {string} uri - Indicates the path of the data to operate. 121 * @param {dataSharePredicates.DataSharePredicates} predicates - Indicates filter criteria. 122 * You should define the processing logic when this parameter is null. 123 * @param {AsyncCallback<number>} callback - {number}: the number of data records deleted. 124 * @throws {BusinessError} 401 - the parameter check failed. 125 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 126 * @systemapi 127 * @StageModelOnly 128 * @since 9 129 */ 130 delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void; 131 132 /** 133 * Deletes one or more data records from the database. 134 * @param {string} uri - Indicates the path of the data to operate. 135 * @param {dataSharePredicates.DataSharePredicates} predicates - Indicates filter criteria. 136 * You should define the processing logic when this parameter is null. 137 * @returns {Promise<number>} {number}: the number of data records deleted. 138 * @throws {BusinessError} 401 - the parameter check failed. 139 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 140 * @systemapi 141 * @StageModelOnly 142 * @since 9 143 */ 144 delete(uri: string, predicates: dataSharePredicates.DataSharePredicates): Promise<number>; 145 146 /** 147 * Queries data in the database. 148 * @param {string} uri - Indicates the path of data to query. 149 * @param {dataSharePredicates.DataSharePredicates} predicates - Indicates filter criteria. 150 * You should define the processing logic when this parameter is null. 151 * @param {Array<string>} columns - Indicates the columns to query. 152 * If this parameter is null, all columns are queried. 153 * @param {AsyncCallback<DataShareResultSet>} callback - {DataShareResultSet}: the query result. 154 * @throws {BusinessError} 401 - the parameter check failed. 155 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 156 * @systemapi 157 * @StageModelOnly 158 * @since 9 159 */ 160 query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, 161 callback: AsyncCallback<DataShareResultSet>): void; 162 163 /** 164 * Queries data in the database. 165 * @param {string} uri - Indicates the path of data to query. 166 * @param {dataSharePredicates.DataSharePredicates} predicates - Indicates filter criteria. 167 * You should define the processing logic when this parameter is null. 168 * @param {Array<string>} columns - Indicates the columns to query. 169 * If this parameter is null, all columns are queried. 170 * @returns {Promise<DataShareResultSet>} {DataShareResultSet}: the query result. 171 * @throws {BusinessError} 401 - the parameter check failed. 172 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 173 * @systemapi 174 * @StageModelOnly 175 * @since 9 176 */ 177 query(uri: string, predicates: dataSharePredicates.DataSharePredicates, 178 columns: Array<string>): Promise<DataShareResultSet>; 179 180 /** 181 * Updates data records in the database. 182 * @param {string} uri - Indicates the path of data to update. 183 * @param {dataSharePredicates.DataSharePredicates} predicates - Indicates filter criteria. 184 * You should define the processing logic when this parameter is null. 185 * @param {ValueBucket} value - Indicates the data to update. This parameter can be null. 186 * @param {AsyncCallback<number>} callback - {number}: the number of data records updated. 187 * @throws {BusinessError} 401 - the parameter check failed. 188 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 189 * @systemapi 190 * @StageModelOnly 191 * @since 9 192 */ 193 update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket, 194 callback: AsyncCallback<number>): void; 195 196 /** 197 * Updates data records in the database. 198 * @param {string} uri - Indicates the path of data to update. 199 * @param {dataSharePredicates.DataSharePredicates} predicates - Indicates filter criteria. 200 * You should define the processing logic when this parameter is null. 201 * @param {ValueBucket} value - Indicates the data to update. This parameter can be null. 202 * @returns {Promise<number>} {number}: the number of data records updated. 203 * @throws {BusinessError} 401 - the parameter check failed. 204 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 205 * @systemapi 206 * @StageModelOnly 207 * @since 9 208 */ 209 update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket): Promise<number>; 210 211 /** 212 * Inserts multiple data records into the database. 213 * @param {string} uri - Indicates the path of the data to operate. 214 * @param {Array<ValuesBucket>} values - Indicates the data records to insert. 215 * @param {AsyncCallback<number>} callback - {number}: the number of data records inserted. 216 * @throws {BusinessError} 401 - the parameter check failed. 217 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 218 * @systemapi 219 * @StageModelOnly 220 * @since 9 221 */ 222 batchInsert(uri: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>): void; 223 224 /** 225 * Inserts multiple data records into the database. 226 * @param {string} uri - Indicates the path of the data to operate. 227 * @param {Array<ValuesBucket>} values - Indicates the data records to insert. 228 * @returns {Promise<number>} {number}: the number of data records inserted. 229 * @throws {BusinessError} 401 - the parameter check failed. 230 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 231 * @systemapi 232 * @StageModelOnly 233 * @since 9 234 */ 235 batchInsert(uri: string, values: Array<ValuesBucket>): Promise<number>; 236 237 /** 238 * Converts the given {@code uri} that refers to the DataShare into a normalized {@link ohos.utils.net.Uri}. 239 * A normalized uri can be used across devices, persisted, backed up, and restored. 240 * <p>To transfer a normalized uri from another environment to the current environment, you should call this 241 * method again to re-normalize the uri for the current environment or call {@link #denormalizeUri(Uri)} 242 * to convert it to a denormalized uri that can be used only in the current environment. 243 * @param {string} uri - Indicates the {@link ohos.utils.net.Uri} object to normalize. 244 * @param {AsyncCallback<string>} callback - {string}: the normalized Uri, 245 * if the DataShare supports uri normalization. 246 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 247 * @systemapi 248 * @StageModelOnly 249 * @since 9 250 */ 251 normalizeUri(uri: string, callback: AsyncCallback<string>): void; 252 253 /** 254 * Converts the given {@code uri} that refers to the DataShare into a normalized {@link ohos.utils.net.Uri}. 255 * A normalized uri can be used across devices, persisted, backed up, and restored. 256 * <p>To transfer a normalized uri from another environment to the current environment, you should call this 257 * method again to re-normalize the uri for the current environment or call {@link #denormalizeUri(Uri)} 258 * to convert it to a denormalized uri that can be used only in the current environment. 259 * @param {string} uri - Indicates the {@link ohos.utils.net.Uri} object to normalize. 260 * @returns {Promise<string>} {string}: the normalized Uri if the DataShare supports uri normalization; 261 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 262 * @systemapi 263 * @StageModelOnly 264 * @since 9 265 */ 266 normalizeUri(uri: string): Promise<string>; 267 268 /** 269 * Converts the given normalized {@code uri} generated by {@link #normalizeUri(Uri)} into a denormalized one. 270 * @param {string} uri - Indicates the {@link ohos.utils.net.Uri} object to denormalize. 271 * @param {AsyncCallback<string>} callback - {string}: the denormalized {@code Uri} object if 272 * the denormalization is successful; returns the original {@code Uri} passed to this method if 273 * there is nothing to do; returns {@code null} if the data identified by the normalized {@code Uri} 274 * cannot be found in the current environment. 275 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 276 * @systemapi 277 * @StageModelOnly 278 * @since 9 279 */ 280 denormalizeUri(uri: string, callback: AsyncCallback<string>): void; 281 282 /** 283 * Converts the given normalized {@code uri} generated by {@link #normalizeUri(Uri)} into a denormalized one. 284 * @param {string} uri - Indicates the {@link ohos.utils.net.Uri} object to denormalize. 285 * @returns {Promise<string>} {string}: the denormalized {@code Uri} object if the denormalization 286 * is successful; returns the original {@code Uri} passed to this method if there is nothing to do; 287 * returns {@code null} if the data identified by the normalized {@code Uri} cannot be found in the 288 * current environment. 289 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 290 * @systemapi 291 * @StageModelOnly 292 * @since 9 293 */ 294 denormalizeUri(uri: string): Promise<string>; 295 296 /** 297 * Notifies the registered observers of a change to the data resource specified by Uri. 298 * @param {string} uri - Indicates the {@link ohos.utils.net.Uri} object to notifyChange. 299 * @param {AsyncCallback<void>} callback - the callback of notifyChange. 300 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 301 * @systemapi 302 * @StageModelOnly 303 * @since 9 304 */ 305 notifyChange(uri: string, callback: AsyncCallback<void>): void; 306 307 /** 308 * Notifies the registered observers of a change to the data resource specified by Uri. 309 * @param {string} uri - Indicates the {@link ohos.utils.net.Uri} object to notifyChange. 310 * @returns {Promise<void>} the promise returned by the function. 311 * @syscap SystemCapability.DistributedDataManager.DataShare.Consumer 312 * @systemapi 313 * @StageModelOnly 314 * @since 9 315 */ 316 notifyChange(uri: string): Promise<void>; 317 } 318} 319 320export default dataShare;