1/* 2 * Copyright (c) 2021-2023 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 '../@ohos.base'; 17import { ResultSet } from '../data/rdb/resultSet'; 18import { DataAbilityOperation } from './dataAbilityOperation'; 19import { DataAbilityResult } from './dataAbilityResult'; 20import dataAbility from '../@ohos.data.dataAbility'; 21import rdb from '../@ohos.data.rdb'; 22 23/** 24 * DataAbilityHelper 25 * 26 * @interface DataAbilityHelper 27 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 28 * @FAModelOnly 29 * @since 7 30 */ 31export interface DataAbilityHelper { 32 /** 33 * Opens a file in a specified remote path. 34 * 35 * @param { string } uri - Indicates the path of the file to open. 36 * @param { string } mode - Indicates the file open mode, which can be "r" for read-only access, "w" for write-only 37 * access (erasing whatever data is currently in the file), "wt" for write access that truncates 38 * any existing file, "wa" for write-only access to append to any existing data, "rw" for read 39 * and write access on any existing data, or "rwt" for read and write access that truncates any 40 * existing file. 41 * @param { AsyncCallback<number> } callback - Indicates the callback when openfile success 42 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 43 * @FAModelOnly 44 * @since 7 45 */ 46 openFile(uri: string, mode: string, callback: AsyncCallback<number>): void; 47 48 /** 49 * Opens a file in a specified remote path. 50 * 51 * @param { string } uri - Indicates the path of the file to open. 52 * @param { string } mode - Indicates the file open mode, which can be "r" for read-only access, "w" for write-only 53 * access (erasing whatever data is currently in the file), "wt" for write access that truncates 54 * any existing file, "wa" for write-only access to append to any existing data, "rw" for read and 55 * write access on any existing data, or "rwt" for read and write access that truncates any 56 * existing file. 57 * @returns { Promise<number> } Returns the file descriptor. 58 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 59 * @FAModelOnly 60 * @since 7 61 */ 62 openFile(uri: string, mode: string): Promise<number>; 63 64 /** 65 * Registers an observer to observe data specified by the given uri. 66 * 67 * @param { 'dataChange' } type - dataChange. 68 * @param { string } uri - Indicates the path of the data to operate. 69 * @param { AsyncCallback<void> } callback - Indicates the callback when dataChange. 70 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 71 * @FAModelOnly 72 * @since 7 73 */ 74 on(type: 'dataChange', uri: string, callback: AsyncCallback<void>): void; 75 76 /** 77 * Deregisters all observers used for monitoring data specified by the given uri. 78 * 79 * @param { 'dataChange' } type - dataChange. 80 * @param { string } uri - Indicates the path of the data to operate. 81 * @param { AsyncCallback<void> } [callback] - Indicates the registered callback. 82 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 83 * @FAModelOnly 84 * @since 7 85 */ 86 off(type: 'dataChange', uri: string, callback?: AsyncCallback<void>): void; 87 88 /** 89 * Obtains the MIME type of the date specified by the given URI. 90 * 91 * @param { string } uri - Indicates the path of the data to operate. 92 * @param { AsyncCallback<string> } callback - Indicates the callback method for obtaining the type of media resource, 93 * returning the media resource type that matches the uri pointing data. 94 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 95 * @FAModelOnly 96 * @since 7 97 */ 98 getType(uri: string, callback: AsyncCallback<string>): void; 99 100 /** 101 * Obtains the MIME type of the date specified by the given URI. 102 * 103 * @param { string } uri - Indicates the path of the data to operate. 104 * @returns { Promise<string> } Returns the MIME type that matches the data specified by uri. 105 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 106 * @FAModelOnly 107 * @since 7 108 */ 109 getType(uri: string): Promise<string>; 110 111 /** 112 * Obtains the MIME types of files supported. 113 * 114 * @param { string } uri - Indicates the path of the files to obtain. 115 * @param { string } mimeTypeFilter - Indicates the MIME types of the files to obtain. 116 * @param { AsyncCallback<Array<string>> } callback - Indicates the callback method for obtaining media resource 117 * types, returning an array of matching media resource types. 118 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 119 * @FAModelOnly 120 * @since 7 121 */ 122 getFileTypes(uri: string, mimeTypeFilter: string, callback: AsyncCallback<Array<string>>): void; 123 124 /** 125 * Obtains the MIME types of files supported. 126 * 127 * @param { string } uri - Indicates the path of the files to obtain. 128 * @param { string } mimeTypeFilter - Indicates the MIME types of the files to obtain. 129 * @returns { Promise<Array<string>> } Returns the matched MIME types Array. 130 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 131 * @FAModelOnly 132 * @since 7 133 */ 134 getFileTypes(uri: string, mimeTypeFilter: string): Promise<Array<string>>; 135 136 /** 137 * Converts the given uri that refers to the Data ability into a normalized uri. 138 * 139 * @param { string } uri - Indicates the uri object to normalize. 140 * @param { AsyncCallback<string> } callback - Indicates the callback method for uri normalization, and if the data 141 * function supports uri normalization, returns the normalized uri object; 142 * Otherwise return null. 143 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 144 * @FAModelOnly 145 * @since 7 146 */ 147 normalizeUri(uri: string, callback: AsyncCallback<string>): void; 148 149 /** 150 * Converts the given uri that refers to the Data ability into a normalized uri. 151 * 152 * @param { string } uri - Indicates the uri object to normalize. 153 * @returns { Promise<string> } Returns normalized uri object if Data ability supports URI normalization or null. 154 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 155 * @FAModelOnly 156 * @since 7 157 */ 158 normalizeUri(uri: string): Promise<string>; 159 160 /** 161 * Converts the given normalized uri generated by normalizeUri(uri) into a denormalized one. 162 * 163 * @param { string } uri - Indicates the uri object to normalize. 164 * @param { AsyncCallback<string> } callback - Indicates the callback method of denormalization uri.If 165 * denormalization succeeds,the denormalization uri object is returned. 166 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 167 * @FAModelOnly 168 * @since 7 169 */ 170 denormalizeUri(uri: string, callback: AsyncCallback<string>): void; 171 172 /** 173 * Converts the given normalized uri generated by normalizeUri(uri) into a denormalized one. 174 * 175 * @param { string } uri - Indicates the uri object to normalize. 176 * @returns { Promise<string> } Returns the denormalized uri object if the denormalization is successful. 177 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 178 * @FAModelOnly 179 * @since 7 180 */ 181 denormalizeUri(uri: string): Promise<string>; 182 183 /** 184 * Notifies the registered observers of a change to the data resource specified by uri. 185 * 186 * @param { string } uri - Indicates the path of the data to operate. 187 * @param { AsyncCallback<void> } callback - callback method. 188 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 189 * @FAModelOnly 190 * @since 7 191 */ 192 notifyChange(uri: string, callback: AsyncCallback<void>): void; 193 194 /** 195 * Notifies the registered observers of a change to the data resource specified by uri. 196 * 197 * @param { string } uri - Indicates the path of the data to operate. 198 * @returns { Promise<void> } The promise returned by the function. 199 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 200 * @FAModelOnly 201 * @since 7 202 */ 203 notifyChange(uri: string): Promise<void>; 204 205 /** 206 * Inserts a single data record into the database. 207 * 208 * @param { string } uri - Indicates the path of the data to insert. 209 * @param { rdb.ValuesBucket } valuesBucket - Indicates the data record to insert. If this parameter is null, a blank 210 * row will be inserted. 211 * @param { AsyncCallback<number> } callback - Indicates the callback method for data insertion, returning the index 212 * of the inserted data record. 213 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 214 * @FAModelOnly 215 * @since 7 216 */ 217 insert(uri: string, valuesBucket: rdb.ValuesBucket, callback: AsyncCallback<number>): void; 218 219 /** 220 * Inserts a single data record into the database. 221 * 222 * @param { string } uri - Indicates the path of the data to insert. 223 * @param { rdb.ValuesBucket } valuesBucket - Indicates the data record to insert. If this parameter is null, 224 * a blank row will be inserted. 225 * @returns { Promise<number> } Returns the index of the inserted data record. 226 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 227 * @FAModelOnly 228 * @since 7 229 */ 230 insert(uri: string, valuesBucket: rdb.ValuesBucket): Promise<number>; 231 232 /** 233 * Inserts multiple data records into the database. 234 * 235 * @param { string } uri - Indicates the path of the data to batchInsert. 236 * @param { Array<rdb.ValuesBucket> } valuesBuckets - Indicates the data records to insert. 237 * @param { AsyncCallback<number> } callback - Callback method indicating batch data insertion, returning the number 238 * of inserted data records. 239 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 240 * @FAModelOnly 241 * @since 7 242 */ 243 batchInsert(uri: string, valuesBuckets: Array<rdb.ValuesBucket>, callback: AsyncCallback<number>): void; 244 245 /** 246 * Inserts multiple data records into the database. 247 * 248 * @param { string } uri - Indicates the path of the data to batchInsert. 249 * @param { Array<rdb.ValuesBucket> } valuesBuckets - Indicates the data records to insert. 250 * @returns { Promise<number> } Returns the number of data records inserted. 251 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 252 * @FAModelOnly 253 * @since 7 254 */ 255 batchInsert(uri: string, valuesBuckets: Array<rdb.ValuesBucket>): Promise<number>; 256 257 /** 258 * Deletes one or more data records from the database. 259 * 260 * @param { string } uri - Indicates the path of the data to delete. 261 * @param { dataAbility.DataAbilityPredicates } predicates - Indicates filter criteria. You should define the 262 * processing logic when this parameter is null. 263 * @param { AsyncCallback<number> } callback - A callback method that indicates data deletion, returning the number of 264 * deleted data records. 265 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 266 * @FAModelOnly 267 * @since 7 268 */ 269 delete(uri: string, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback<number>): void; 270 271 /** 272 * Deletes one or more data records from the database. 273 * 274 * @param { string } uri - Indicates the path of the data to delete. 275 * @param { dataAbility.DataAbilityPredicates } [predicates] - Indicates filter criteria. You should define the 276 * processing logic when this parameter is null. 277 * @returns { Promise<number> } Returns the number of data records deleted. 278 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 279 * @FAModelOnly 280 * @since 7 281 */ 282 delete(uri: string, predicates?: dataAbility.DataAbilityPredicates): Promise<number>; 283 284 /** 285 * Deletes one or more data records from the database. 286 * 287 * @param { string } uri - Indicates the path of the data to delete. 288 * @param { AsyncCallback<number> } callback - A callback method that indicates data deletion, returning 289 * the number of deleted data records. 290 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 291 * @FAModelOnly 292 * @since 7 293 */ 294 delete(uri: string, callback: AsyncCallback<number>): void; 295 296 /** 297 * Updates data records in the database. 298 * 299 * @param { string } uri - Indicates the path of data to update. 300 * @param { rdb.ValuesBucket } valuesBucket - Indicates the data to update. 301 * @param { dataAbility.DataAbilityPredicates } predicates - Indicates filter criteria. You should define the 302 * processing logic when this parameter is null. 303 * @param { AsyncCallback<number> } callback - A callback method that indicates data updates, returning the number of 304 * updated data records. 305 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 306 * @FAModelOnly 307 * @since 7 308 */ 309 update( 310 uri: string, 311 valuesBucket: rdb.ValuesBucket, 312 predicates: dataAbility.DataAbilityPredicates, 313 callback: AsyncCallback<number> 314 ): void; 315 316 /** 317 * Updates data records in the database. 318 * 319 * @param { string } uri - Indicates the path of data to update. 320 * @param { rdb.ValuesBucket } valuesBucket - Indicates the data to update. 321 * @param { dataAbility.DataAbilityPredicates } [predicates] - Indicates filter criteria. You should define the 322 * processing logic when this parameter is null. 323 * @returns { Promise<number> } Returns the number of data records updated. 324 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 325 * @FAModelOnly 326 * @since 7 327 */ 328 update(uri: string, valuesBucket: rdb.ValuesBucket, predicates?: dataAbility.DataAbilityPredicates): Promise<number>; 329 330 /** 331 * Updates data records in the database. 332 * 333 * @param { string } uri - Indicates the path of data to update. 334 * @param { rdb.ValuesBucket } valuesBucket - Indicates the data to update. 335 * @param { AsyncCallback<number> } callback - A callback method that indicates data updates, returning the number of 336 * updated data records. 337 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 338 * @FAModelOnly 339 * @since 7 340 */ 341 update(uri: string, valuesBucket: rdb.ValuesBucket, callback: AsyncCallback<number>): void; 342 343 /** 344 * Queries data in the database. 345 * 346 * @param { string } uri - Indicates the path of data to query. 347 * @param { Array<string> } columns - Indicates columns to query. If this parameter is null, all columns are queried. 348 * @param { dataAbility.DataAbilityPredicates } predicates - Indicates filter criteria. You should define the 349 * processing logic when this parameter is null. 350 * @param { AsyncCallback<ResultSet> } callback - Indicates the callback method for data queries, returning the 351 * number of queried data records. 352 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 353 * @FAModelOnly 354 * @since 7 355 */ 356 query( 357 uri: string, 358 columns: Array<string>, 359 predicates: dataAbility.DataAbilityPredicates, 360 callback: AsyncCallback<ResultSet> 361 ): void; 362 363 /** 364 * Queries data in the database. 365 * 366 * @param { string } uri - Indicates the path of data to query. 367 * @param { AsyncCallback<ResultSet> } callback - Indicates the callback method for data queries, returning the 368 * number of queried data records. 369 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 370 * @FAModelOnly 371 * @since 7 372 */ 373 query(uri: string, callback: AsyncCallback<ResultSet>): void; 374 375 /** 376 * Queries data in the database. 377 * 378 * @param { string } uri - Indicates the path of data to query. 379 * @param { Array<string> } columns - Indicates columns to query. If this parameter is null, all columns are queried. 380 * @param { AsyncCallback<ResultSet> } callback - Indicates the callback method for data queries, returning the 381 * number of queried data records. 382 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 383 * @FAModelOnly 384 * @since 7 385 */ 386 query(uri: string, columns: Array<string>, callback: AsyncCallback<ResultSet>): void; 387 388 /** 389 * Queries data in the database. 390 * 391 * @param { string } uri - Indicates the path of data to query. 392 * @param { dataAbility.DataAbilityPredicates } predicates - Indicates filter criteria. You should define the 393 * processing logic when this parameter is null. 394 * @param { AsyncCallback<ResultSet> } callback - Indicates the callback method for data queries, returning the 395 * number of queried data records. 396 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 397 * @FAModelOnly 398 * @since 7 399 */ 400 query(uri: string, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback<ResultSet>): void; 401 402 /** 403 * Queries data in the database. 404 * 405 * @param { string } uri - Indicates the path of data to query. 406 * @param { Array<string> } [columns] - Indicates columns to query. If this parameter is null, all columns are queried. 407 * @param { dataAbility.DataAbilityPredicates } [predicates] - Indicates filter criteria. You should define the 408 * processing logic when this parameter is null. 409 * @returns { Promise<ResultSet> } Returns the query result {@link ResultSet}. 410 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 411 * @FAModelOnly 412 * @since 7 413 */ 414 query(uri: string, columns?: Array<string>, predicates?: dataAbility.DataAbilityPredicates): Promise<ResultSet>; 415 416 /** 417 * Calls the extended API of the DataAbility. This method uses a promise to return the result. 418 * 419 * @param { string } uri - URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx" 420 * @param { string } method - Indicates the method to call. 421 * @param { string } arg - Indicates the parameter of the String type. 422 * @param { PacMap } extras - Indicates the parameter of the PacMap type. 423 * @param { AsyncCallback<PacMap> } callback - A callback method that indicates a data operation and returns the 424 * result of the operation. 425 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 426 * @FAModelOnly 427 * @since 7 428 */ 429 call(uri: string, method: string, arg: string, extras: PacMap, callback: AsyncCallback<PacMap>): void; 430 431 /** 432 * Calls the extended API of the DataAbility. This method uses a promise to return the result. 433 * 434 * @param { string } uri - URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx" 435 * @param { string } method - Indicates the method to call. 436 * @param { string } arg - Indicates the parameter of the String type. 437 * @param { PacMap } extras - Indicates the parameter of the PacMap type. 438 * @returns { Promise<PacMap> } Returns the query result {@link PacMap}. 439 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 440 * @FAModelOnly 441 * @since 7 442 */ 443 call(uri: string, method: string, arg: string, extras: PacMap): Promise<PacMap>; 444 445 /** 446 * Queries data in the database. 447 * 448 * @param { string } uri - Indicates the path of data to query. 449 * @param { Array<DataAbilityOperation> } operations - Indicates the data operation list, which can contain multiple 450 * operations on the database. 451 * @param { AsyncCallback<Array<DataAbilityResult>> } callback - Callback method indicating batch operations, 452 * returning the result of each operation in the 453 * DataAbilityResult array. 454 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 455 * @FAModelOnly 456 * @since 7 457 */ 458 executeBatch( 459 uri: string, 460 operations: Array<DataAbilityOperation>, 461 callback: AsyncCallback<Array<DataAbilityResult>> 462 ): void; 463 464 /** 465 * Queries data in the database. 466 * 467 * @param { string } uri - Indicates the path of data to query. 468 * @param { Array<DataAbilityOperation> } operations - Indicates the data operation list, which can contain multiple 469 * operations on the database. 470 * @returns { Promise<Array<DataAbilityResult>> } Returns the result of each operation, 471 * in array {@link DataAbilityResult}. 472 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 473 * @FAModelOnly 474 * @since 7 475 */ 476 executeBatch(uri: string, operations: Array<DataAbilityOperation>): Promise<Array<DataAbilityResult>>; 477} 478 479/** 480 * Defines a PacMap object for storing a series of values. 481 * 482 * @typedef PacMap 483 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 484 * @FAModelOnly 485 * @since 7 486 */ 487/** 488 * Defines a PacMap object for storing a series of values. 489 * 490 * @typedef PacMap 491 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 492 * @since 11 493 */ 494export interface PacMap { 495 /** 496 * Indicates the parameter of the PacMap type. 497 * If a custom Sequenceable object is put in the PacMap object and will be transferred across processes, 498 * you must call BasePacMap.setClassLoader(ClassLoader) to set a class loader for the custom object. 499 * If the PacMap object is to be transferred to a non-OHOS process, 500 * values of primitive types are supported, but not custom Sequenceable objects. 501 * 502 * @type { number | string | boolean | Array<string | number | boolean> | null } 503 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 504 * @FAModelOnly 505 * @since 7 506 */ 507 /** 508 * Indicates the parameter of the PacMap type. 509 * If a custom Sequenceable object is put in the PacMap object and will be transferred across processes, 510 * you must call BasePacMap.setClassLoader(ClassLoader) to set a class loader for the custom object. 511 * If the PacMap object is to be transferred to a non-OHOS process, 512 * values of primitive types are supported, but not custom Sequenceable objects. 513 * 514 * @type { number | string | boolean | Array<string | number | boolean> | null } 515 * @syscap SystemCapability.Ability.AbilityRuntime.FAModel 516 * @since 11 517 */ 518 [key: string]: number | string | boolean | Array<string | number | boolean> | null; 519} 520