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