1/* 2 * Copyright (c) 2021 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, Callback } from './basic'; 17/** 18 * Providers interfaces to creat a {@link KVManager} istances. 19 * @since 7 20 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 21 * @import N/A 22 */ 23 24declare namespace distributedData { 25 /** 26 * Provides configuration information for {@link KVManager} instances, 27 * including the caller's package name and distributed network type. 28 * @since 7 29 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 30 * @import N/A 31 */ 32 interface KVManagerConfig { 33 /** 34 * Indicates the user information 35 * @since 7 36 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 37 * @import N/A 38 */ 39 userInfo: UserInfo; 40 41 /** 42 * Indicates the bundleName 43 * @since 7 44 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 45 * @import N/A 46 */ 47 bundleName: string; 48 } 49 50 /** 51 * Manages user information. 52 * 53 * <p>This class provides methods for obtaining the user ID and type, setting the user ID and type, 54 * and checking whether two users are the same. 55 * 56 * @since 7 57 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 58 * @import N/A 59 */ 60 interface UserInfo { 61 /** 62 * Indicates the user ID to set 63 * @since 7 64 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 65 * @import N/A 66 */ 67 userId?: string; 68 69 /** 70 * Indicates the user type to set 71 * @since 7 72 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 73 * @import N/A 74 */ 75 userType?: UserType; 76 } 77 78 /** 79 * Enumerates user types. 80 * 81 * @since 7 82 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 83 * @import N/A 84 */ 85 enum UserType { 86 /** 87 * Indicates a user that logs in to different devices using the same account. 88 * @since 7 89 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 90 * @import N/A 91 */ 92 SAME_USER_ID = 0 93 } 94 95 /** 96 * KVStore constants 97 * @since 7 98 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 99 * @import N/A 100 */ 101 namespace Constants { 102 /** 103 * max key length. 104 * @since 7 105 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 106 * @import N/A 107 */ 108 const MAX_KEY_LENGTH = 1024; 109 110 /** 111 * max value length. 112 * @since 7 113 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 114 * @import N/A 115 */ 116 const MAX_VALUE_LENGTH = 4194303; 117 118 /** 119 * max device coordinate key length. 120 * @since 7 121 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 122 * @import N/A 123 */ 124 const MAX_KEY_LENGTH_DEVICE = 896; 125 126 /** 127 * max store id length. 128 * @since 7 129 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 130 * @import N/A 131 */ 132 const MAX_STORE_ID_LENGTH = 128; 133 134 /** 135 * max query length. 136 * @since 7 137 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 138 * @import N/A 139 */ 140 const MAX_QUERY_LENGTH = 512000; 141 142 /** 143 * max batch operation size. 144 * @since 7 145 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 146 * @import N/A 147 */ 148 const MAX_BATCH_SIZE = 128; 149 } 150 151 /** 152 * Indicates the {@code ValueType}. 153 * 154 * <p>{@code ValueType} is obtained based on the value. 155 * 156 * @since 7 157 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 158 * @import N/A 159 */ 160 enum ValueType { 161 /** 162 * Indicates that the value type is string. 163 * @since 7 164 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 165 * @import N/A 166 */ 167 STRING = 0, 168 169 /** 170 * Indicates that the value type is int. 171 * @since 7 172 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 173 * @import N/A 174 */ 175 INTEGER = 1, 176 177 /** 178 * Indicates that the value type is float. 179 * @since 7 180 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 181 * @import N/A 182 */ 183 FLOAT = 2, 184 185 /** 186 * Indicates that the value type is byte array. 187 * @since 7 188 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 189 * @import N/A 190 * */ 191 BYTE_ARRAY = 3, 192 193 /** 194 * Indicates that the value type is boolean. 195 * @since 7 196 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 197 * @import N/A 198 * */ 199 BOOLEAN = 4, 200 201 /** 202 * Indicates that the value type is double. 203 * @since 7 204 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 205 * @import N/A 206 */ 207 DOUBLE = 5 208 } 209 210 /** 211 * Obtains {@code Value} objects stored in a {@link KVStore} database. 212 * 213 * @since 7 214 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 215 * @import N/A 216 */ 217 interface Value { 218 /** 219 * Indicates value type 220 * @since 7 221 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 222 * @import N/A 223 * @see ValueType 224 * @type {number} 225 * @memberof Value 226 */ 227 type: ValueType; 228 /** 229 * Indicates value 230 * @since 7 231 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 232 * @import N/A 233 */ 234 value: Uint8Array | string | number | boolean; 235 } 236 237 /** 238 * Provides key-value pairs stored in the distributed database. 239 * 240 * @since 7 241 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 242 * @import N/A 243 */ 244 interface Entry { 245 /** 246 * Indicates key 247 * @since 7 248 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 249 * @import N/A 250 */ 251 key: string; 252 /** 253 * Indicates value 254 * @since 7 255 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 256 * @import N/A 257 */ 258 value: Value; 259 } 260 261 /** 262 * Receives notifications of all data changes, including data insertion, update, and deletion. 263 * 264 * <p>If you have subscribed to {@code KVStore}, you will receive data change notifications and obtain the changed data 265 * from the parameters in callback methods upon data insertion, update, or deletion. 266 * 267 * @since 7 268 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 269 * @import N/A 270 */ 271 interface ChangeNotification { 272 /** 273 * Indicates data addition records. 274 * @since 7 275 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 276 * @import N/A 277 */ 278 insertEntries: Entry[]; 279 /** 280 * Indicates data update records. 281 * @since 7 282 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 283 * @import N/A 284 */ 285 updateEntries: Entry[]; 286 /** 287 * Indicates data deletion records. 288 * @since 7 289 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 290 * @import N/A 291 */ 292 deleteEntries: Entry[]; 293 /** 294 * Indicates from device id. 295 * @since 7 296 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 297 * @import N/A 298 */ 299 deviceId: string; 300 } 301 302 /** 303 * Indicates the database synchronization mode. 304 * 305 * @since 7 306 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 307 * @import N/A 308 */ 309 enum SyncMode { 310 /** 311 * Indicates that data is only pulled from the remote end. 312 * @since 7 313 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 314 * @import N/A 315 */ 316 PULL_ONLY = 0, 317 /** 318 * Indicates that data is only pushed from the local end. 319 * @since 7 320 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 321 * @import N/A 322 */ 323 PUSH_ONLY = 1, 324 /** 325 * Indicates that data is pushed from the local end, and then pulled from the remote end. 326 * @since 7 327 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 328 * @import N/A 329 */ 330 PUSH_PULL = 2 331 } 332 333 /** 334 * Describes the subscription type. 335 * 336 * @since 7 337 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 338 * @import N/A 339 */ 340 enum SubscribeType { 341 /** 342 * Subscription to local data changes 343 * @since 7 344 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 345 * @import N/A 346 */ 347 SUBSCRIBE_TYPE_LOCAL = 0, 348 349 /** 350 * Subscription to remote data changes 351 * @since 7 352 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 353 * @import N/A 354 */ 355 SUBSCRIBE_TYPE_REMOTE = 1, 356 357 /** 358 * Subscription to both local and remote data changes 359 * @since 7 360 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 361 * @import N/A 362 */ 363 SUBSCRIBE_TYPE_ALL = 2, 364 } 365 366 /** 367 * Describes the {@code KVStore} type. 368 * 369 * @since 7 370 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 371 * @import N/A 372 */ 373 enum KVStoreType { 374 /** 375 * Device-collaborated database, as specified by {@code DeviceKVStore} 376 * @since 7 377 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 378 * @import N/A 379 */ 380 DEVICE_COLLABORATION = 0, 381 382 /** 383 * Single-version database, as specified by {@code SingleKVStore} 384 * @since 7 385 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 386 * @import N/A 387 */ 388 SINGLE_VERSION = 1, 389 390 /** 391 * Multi-version database, as specified by {@code MultiKVStore} 392 * @since 7 393 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 394 * @import N/A 395 */ 396 MULTI_VERSION = 2, 397 } 398 399 /** 400 * Describes the {@code KVStore} type. 401 * 402 * @since 7 403 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 404 * @import N/A 405 */ 406 enum SecurityLevel { 407 /** 408 * NO_LEVEL: mains not set the security level. 409 * 410 * @since 7 411 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 412 * @import N/A 413 */ 414 NO_LEVEL = 0, 415 416 /** 417 * S0: mains the db is public. 418 * There is no impact even if the data is leaked. 419 * 420 * @since 7 421 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 422 * @import N/A 423 */ 424 S0 = 1, 425 426 /** 427 * S1: mains the db is low level security 428 * There are some low impact, when the data is leaked. 429 * 430 * @since 7 431 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 432 * @import N/A 433 */ 434 S1 = 2, 435 436 /** 437 * S2: mains the db is middle level security 438 * There are some major impact, when the data is leaked. 439 * 440 * @since 7 441 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 442 * @import N/A 443 */ 444 S2 = 3, 445 446 /** 447 * S3: mains the db is high level security 448 * There are some severity impact, when the data is leaked. 449 * 450 * @since 7 451 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 452 * @import N/A 453 */ 454 S3 = 5, 455 456 /** 457 * S4: mains the db is critical level security 458 * There are some critical impact, when the data is leaked. 459 * 460 * @since 7 461 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 462 * @import N/A 463 */ 464 S4 = 6, 465 } 466 467 /** 468 * Provides configuration options for creating a {@code KVStore}. 469 * 470 * <p>You can determine whether to create another database if a {@code KVStore} database is missing, 471 * whether to encrypt the database, and the database type. 472 * 473 * @since 7 474 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 475 * @import N/A 476 */ 477 interface Options { 478 /** 479 * Indicates whether to createa database when the database file does not exist 480 * @since 7 481 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 482 * @import N/A 483 */ 484 createIfMissing?: boolean; 485 /** 486 * Indicates setting whether database files are encrypted 487 * @since 7 488 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 489 * @import N/A 490 */ 491 encrypt?: boolean; 492 /** 493 * Indicates setting whether to back up database files 494 * @since 7 495 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 496 * @import N/A 497 */ 498 backup?: boolean; 499 /** 500 * Indicates setting whether database files are automatically synchronized 501 * @since 7 502 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 503 * @permission ohos.permission.DISTRIBUTED_DATASYNC 504 * @import N/A 505 */ 506 autoSync?: boolean; 507 /** 508 * Indicates setting the databse type 509 * @since 7 510 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 511 * @import N/A 512 */ 513 kvStoreType?: KVStoreType; 514 /** 515 * Indicates setting the database security level 516 * @since 7 517 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 518 * @import N/A 519 */ 520 securityLevel?: SecurityLevel; 521 /** 522 * Indicates schema object 523 * @since 8 524 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 525 * @import N/A 526 */ 527 schema?: Schema; 528 } 529 530 /** 531 * Represents the database schema. 532 * 533 * You can create Schema objects and put them in Options when creating or opening the database. 534 * 535 * @since 8 536 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 537 * @import N/A 538 */ 539 class Schema { 540 /** 541 * A constructor used to create a Schema instance. 542 * 543 * @note N/A 544 * @since 8 545 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 546 */ 547 constructor() 548 /** 549 * Indicates the root json object. 550 * 551 * @note N/A 552 * @since 8 553 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 554 */ 555 root: FieldNode; 556 /** 557 * Indicates the string array of json. 558 * 559 * @note N/A 560 * @since 8 561 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 562 */ 563 indexes: Array<string>; 564 /** 565 * Indicates the mode of schema. 566 * 567 * @note N/A 568 * @since 8 569 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 570 */ 571 mode: number; 572 /** 573 * Indicates the skipsize of schema. 574 * 575 * @note N/A 576 * @since 8 577 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 578 */ 579 skip: number; 580 } 581 582 /** 583 * Represents a node of a {@link Schema} instance. 584 * 585 * <p>Through the {@link Schema} instance, you can define the fields contained in the values stored in a database. 586 * 587 * <p>A FieldNode of the {@link Schema} instance is either a leaf or a non-leaf node. 588 * 589 * <p>The leaf node must have a value; the non-leaf node must have a child {@code FieldNode}. 590 * 591 * @since 8 592 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 593 * @import N/A 594 */ 595 class FieldNode { 596 /** 597 * A constructor used to create a FieldNode instance with the specified field. 598 * name Indicates the field node name. 599 * 600 * @note N/A 601 * @since 8 602 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 603 */ 604 constructor(name: string) 605 /** 606 * Adds a child node to this {@code FieldNode}. 607 * 608 * <p>Adding a child node makes this node a non-leaf node. Field value will be ignored if it has child node. 609 * 610 * @note N/A 611 * @since 8 612 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 613 * @param child The field node to append. 614 * @returns Returns true if the child node is successfully added to this {@code FieldNode}; returns false otherwise. 615 */ 616 appendChild(child: FieldNode): boolean; 617 /** 618 * Indicates the default value of fieldnode. 619 * 620 * @note N/A 621 * @since 8 622 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 623 */ 624 default: string; 625 /** 626 * Indicates the nullable of database field. 627 * 628 * @note N/A 629 * @since 8 630 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 631 */ 632 nullable: boolean; 633 /** 634 * Indicates the type of value. 635 * 636 * @note N/A 637 * @since 8 638 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 639 */ 640 type: number; 641 } 642 643 /** 644 * Provide methods to obtain the result set of the {@code KvStore} database. 645 * 646 * <p>The result set is created by using the {@code getResultSet} method in the {@code DeviceKVStore} class. This interface also provides 647 * methods for moving the data read position in the result set. 648 * 649 * @since 7 650 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 651 * @import N/A 652 */ 653 interface KvStoreResultSet { 654 /** 655 * Obtains the number of lines in a result set. 656 * 657 * @note N/A 658 * @since 8 659 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 660 * @returns Returns the number of lines. 661 */ 662 getCount(): number; 663 /** 664 * Obtains the current read position in a result set. 665 * 666 * @note N/A 667 * @since 8 668 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 669 * @returns Returns the current read position. The read position starts with 0. 670 */ 671 getPosition(): number; 672 /** 673 * Moves the read position to the first line. 674 * 675 * <p>If the result set is empty, false is returned. 676 * @note N/A 677 * @since 8 678 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 679 * @returns Returns true if the operation succeeds; return false otherwise. 680 */ 681 moveToFirst(): boolean; 682 /** 683 * Moves the read position to the last line. 684 * 685 * <p>If the result set is empty, false is returned. 686 * @note N/A 687 * @since 8 688 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 689 * @returns Returns true if the operation succeeds; return false otherwise. 690 */ 691 moveToLast(): boolean; 692 /** 693 * Moves the read position to the next line. 694 * 695 * <p>If the result set is empty or the data in the last line is being read, false is returned. 696 * @note N/A 697 * @since 8 698 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 699 * @returns Returns true if the operation succeeds; return false otherwise. 700 */ 701 moveToNext(): boolean; 702 /** 703 * Moves the read position to the previous line. 704 * 705 * <p>If the result set is empty or the data in the first line is being read, false is returned. 706 * @note N/A 707 * @since 8 708 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 709 * @returns Returns true if the operation succeeds; return false otherwise. 710 */ 711 moveToPrevious(): boolean; 712 /** 713 * Moves the read position by a relative offset to the current position. 714 * 715 * @note N/A 716 * @since 8 717 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 718 * @param offset Indicates the relative offset to the current position. Anegative offset indicates moving backwards, and a 719 * positive offset indicates moving forewards. Forexample, if the current position is entry 1 and thisoffset is 2, 720 * the destination position will be entry 3; ifthe current position is entry 3 and this offset is -2, 721 * the destination position will be entry 1. The valid final position after moving forwards starts with 0. If the 722 * final position is invalid, false will be returned. 723 * @returns Returns true if the operation succeeds; return false otherwise. 724 */ 725 move(offset: number): boolean; 726 /** 727 * Moves the read position from 0 to an absolute position. 728 * 729 * @note N/A 730 * @since 8 731 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 732 * @param position Indicates the absolute position. 733 * @returns Returns true if the operation succeeds; return false otherwise. 734 */ 735 moveToPosition(position: number): boolean; 736 /** 737 * Checks whether the read position is the first line. 738 * 739 * @note N/A 740 * @since 8 741 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 742 743 * @returns Returns true if the read position is the first line; returns false otherwise. 744 */ 745 isFirst(): boolean; 746 /** 747 * Checks whether the read position is the last line. 748 * 749 * @since 8 750 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 751 * @returns Returns true if the read position is the last line; returns false otherwise. 752 */ 753 isLast(): boolean; 754 /** 755 * Checks whether the read position is before the last line. 756 * 757 * @since 8 758 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 759 * @returns Returns true if the read position is before the first line; returns false otherwise. 760 */ 761 isBeforeFirst(): boolean; 762 /** 763 * Checks whether the read position is after the last line. 764 * 765 * @since 8 766 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 767 * @returns Returns true if the read position is after the last line; returns false otherwise. 768 */ 769 isAfterLast(): boolean; 770 /** 771 * Obtains a key-value pair. 772 * 773 * @since 8 774 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 775 * @returns Returns a key-value pair. 776 */ 777 getEntry(): Entry; 778 } 779 780 /** 781 * Represents a database query using a predicate. 782 * 783 * <p>This class provides a constructor used to create a {@code Query} instance, which is used to query data matching specified 784 * conditions in the database. 785 * 786 * <p>This class also provides methods for adding predicates to the {@code Query} instance. 787 * 788 * @since 8 789 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 790 * @import N/A 791 */ 792 class Query { 793 /** 794 * A constructor used to create a Query instance. 795 * 796 * @note N/A 797 * @since 8 798 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 799 */ 800 constructor() 801 /** 802 * Resets this {@code Query} object. 803 * 804 * @since 8 805 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 806 * @import N/A 807 * @returns Returns the reset {@code Query} object. 808 */ 809 reset(): Query; 810 /** 811 * Constructs a {@code Query} object to query entries with the specified field whose value is equal to the specified long value. 812 * 813 * @since 8 814 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 815 * @import N/A 816 * @param field Indicates the field, which must start with $. and cannot contain ^. 817 * @param value IIndicates the long value. 818 * @returns Returns the {@coed Query} object. 819 * @throws Throws this exception if input is invalid. 820 */ 821 equalTo(field: string, value: number|string|boolean): Query; 822 /** 823 * Constructs a {@code Query} object to query entries with the specified field whose value is not equal to the specified int value. 824 * 825 * @since 8 826 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 827 * @import N/A 828 * @param field Indicates the field, which must start with $. and cannot contain ^. 829 * @param value Indicates the int value. 830 * @returns Returns the {@coed Query} object. 831 * @throws Throws this exception if input is invalid. 832 */ 833 notEqualTo(field: string, value: number|string|boolean): Query; 834 /** 835 * Constructs a {@code Query} object to query entries with the specified field whose value is greater than or equal to the 836 * specified int value. 837 * 838 * @since 8 839 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 840 * @import N/A 841 * @param field Indicates the field, which must start with $. and cannot contain ^. 842 * @param value Indicates the int value. 843 * @returns Returns the {@coed Query} object. 844 * @throws Throws this exception if input is invalid. 845 */ 846 greaterThan(field: string, value: number|string|boolean): Query; 847 /** 848 * Constructs a {@code Query} object to query entries with the specified field whose value is less than the specified int value. 849 * 850 * @since 8 851 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 852 * @import N/A 853 * @param field Indicates the field, which must start with $. and cannot contain ^. 854 * @param value Indicates the int value. 855 * @returns Returns the {@coed Query} object. 856 * @throws Throws this exception if input is invalid. 857 */ 858 lessThan(field: string, value: number|string): Query; 859 /** 860 * Constructs a {@code Query} object to query entries with the specified field whose value is greater than or equal to the 861 * specified int value. 862 * @since 8 863 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 864 * @import N/A 865 * @param field Indicates the field, which must start with $. and cannot contain ^. 866 * @param value Indicates the int value. 867 * @returns Returns the {@coed Query} object. 868 * @throws Throws this exception if input is invalid. 869 */ 870 greaterThanOrEqualTo(field: string, value: number|string): Query; 871 /** 872 * Constructs a {@code Query} object to query entries with the specified field whose value is less than or equal to the 873 * specified int value. 874 * 875 * @since 8 876 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 877 * @import N/A 878 * @param field Indicates the field, which must start with $. and cannot contain ^. 879 * @param value Indicates the int value. 880 * @returns Returns the {@coed Query} object. 881 * @throws Throws this exception if input is invalid. 882 */ 883 lessThanOrEqualTo(field: string, value: number|string): Query; 884 /** 885 * Constructs a {@code Query} object to query entries with the specified field whose value is null. 886 * 887 * @since 8 888 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 889 * @import N/A 890 * @param field Indicates the field, which must start with $. and cannot contain ^. 891 * @returns Returns the {@coed Query} object. 892 * @throws Throws this exception if input is invalid. 893 */ 894 isNull(field: string): Query; 895 /** 896 * Constructs a {@code Query} object to query entries with the specified field whose value is within the specified int value list. 897 * 898 * @since 8 899 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 900 * @import N/A 901 * @param field Indicates the field, which must start with $. and cannot contain ^. 902 * @param valueList Indicates the int value list. 903 * @returns Returns the {@coed Query} object. 904 * @throws Throws this exception if input is invalid. 905 */ 906 inNumber(field: string, valueList: number[]): Query; 907 /** 908 * Constructs a {@code Query} object to query entries with the specified field whose value is within the specified string value list. 909 * @since 8 910 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 911 912 * @import N/A 913 * @param field Indicates the field, which must start with $. and cannot contain ^. 914 * @param valueList Indicates the string value list. 915 * @returns Returns the {@coed Query} object. 916 * @throws Throws this exception if input is invalid. 917 */ 918 inString(field: string, valueList: string[]): Query; 919 /** 920 * Constructs a {@code Query} object to query entries with the specified field whose value is not within the specified int value list. 921 * @since 8 922 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 923 * @import N/A 924 * @param field Indicates the field, which must start with $. and cannot contain ^. 925 * @param valueList Indicates the int value list. 926 * @returns Returns the {@coed Query} object. 927 * @throws Throws this exception if input is invalid. 928 */ 929 notInNumber(field: string, valueList: number[]): Query; 930 /** 931 * Constructs a {@code Query} object to query entries with the specified field whose value is not within the specified string value list. 932 * 933 * @since 8 934 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 935 * @import N/A 936 * @param field Indicates the field, which must start with $. and cannot contain ^. 937 * @param valueList Indicates the string value list. 938 * @returns Returns the {@coed Query} object. 939 * @throws Throws this exception if input is invalid. 940 */ 941 notInString(field: string, valueList: string[]): Query; 942 /** 943 * Constructs a {@code Query} object to query entries with the specified field whose value is similar to the specified string value. 944 * 945 * @since 8 946 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 947 * @import N/A 948 * @param field Indicates the field, which must start with $. and cannot contain ^. 949 * @param value Indicates the string value. 950 * @returns Returns the {@coed Query} object. 951 * @throws Throws this exception if input is invalid. 952 */ 953 like(field: string, value: string): Query; 954 /** 955 * Constructs a {@code Query} object to query entries with the specified field whose value is not similar to the specified string value. 956 * 957 * @since 8 958 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 959 * @import N/A 960 * @param field Indicates the field, which must start with $. and cannot contain ^. 961 * @param value Indicates the string value. 962 * @returns Returns the {@coed Query} object. 963 * @throws Throws this exception if input is invalid. 964 */ 965 unlike(field: string, value: string): Query; 966 /** 967 * Constructs a {@code Query} object with the and condition. 968 * 969 * <p>Multiple predicates should be connected using the and or or condition. 970 * 971 * @since 8 972 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 973 * @import N/A 974 * @returns Returns the {@coed Query} object. 975 */ 976 and(): Query; 977 /** 978 * Constructs a {@code Query} object with the or condition. 979 * 980 * <p>Multiple predicates should be connected using the and or or condition. 981 * 982 * @since 8 983 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 984 * @import N/A 985 * @returns Returns the {@coed Query} object. 986 */ 987 or(): Query; 988 /** 989 * Constructs a {@code Query} object to sort the query results in ascending order. 990 * 991 * @since 8 992 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 993 * @import N/A 994 * @param field Indicates the field, which must start with $. and cannot contain ^. 995 * @returns Returns the {@coed Query} object. 996 * @throws Throws this exception if input is invalid. 997 */ 998 orderByAsc(field: string): Query; 999 /** 1000 * Constructs a {@code Query} object to sort the query results in descending order. 1001 * 1002 * @since 8 1003 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1004 * @import N/A 1005 * @param field Indicates the field, which must start with $. and cannot contain ^. 1006 * @returns Returns the {@coed Query} object. 1007 * @throws Throws this exception if input is invalid. 1008 */ 1009 orderByDesc(field: string): Query; 1010 /** 1011 * Constructs a {@code Query} object to specify the number of results and the start position. 1012 * 1013 * @since 8 1014 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1015 * @import N/A 1016 * @param total Indicates the number of results. 1017 * @param offset Indicates the start position. 1018 * @returns Returns the {@coed Query} object. 1019 */ 1020 limit(total: number, offset: number): Query; 1021 /** 1022 * Creates a {@code query} condition with a specified field that is not null. 1023 * 1024 * @since 8 1025 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1026 * @import N/A 1027 * @param field Indicates the specified field. 1028 * @returns Returns the {@coed Query} object. 1029 * @throws Throws this exception if input is invalid. 1030 */ 1031 isNotNull(field: string): Query; 1032 /** 1033 * Creates a query condition group with a left bracket. 1034 * 1035 * <p>Multiple query conditions in an {@code Query} object can be grouped. The query conditions in a group can be used as a 1036 * whole to combine with other query conditions. 1037 * 1038 * @since 8 1039 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1040 * @import N/A 1041 * @returns Returns the {@coed Query} object. 1042 */ 1043 beginGroup(): Query; 1044 /** 1045 * Creates a query condition group with a right bracket. 1046 * 1047 * <p>Multiple query conditions in an {@code Query} object can be grouped. The query conditions in a group can be used as a 1048 * whole to combine with other query conditions. 1049 * 1050 * @since 8 1051 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1052 * @import N/A 1053 * @returns Returns the {@coed Query} object. 1054 */ 1055 endGroup(): Query; 1056 /** 1057 * Creates a query condition with a specified key prefix. 1058 * 1059 * @since 8 1060 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1061 * @import N/A 1062 * @param prefix Indicates the specified key prefix. 1063 * @returns Returns the {@coed Query} object. 1064 * @throws Throws this exception if input is invalid. 1065 */ 1066 prefixKey(prefix: string): Query; 1067 /** 1068 * Sets a specified index that will be preferentially used for query. 1069 * 1070 * @since 8 1071 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1072 * @import N/A 1073 * @param index Indicates the index to set. 1074 * @returns Returns the {@coed Query} object. 1075 * @throws Throws this exception if input is invalid. 1076 */ 1077 setSuggestIndex(index: string): Query; 1078 /** 1079 * Add device ID key prefix.Used by {@code DeviceKVStore}. 1080 * 1081 * @since 8 1082 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1083 * @import N/A 1084 * @param deviceId Specify device id to query from. 1085 * @return Returns the {@code Query} object with device ID prefix added. 1086 * @throw Throws this exception if input is invalid. 1087 */ 1088 deviceId(deviceId:string):Query; 1089 /** 1090 * Get a String that repreaents this {@code Query}. 1091 * 1092 * <p>The String would be parsed to DB query format. 1093 * The String length should be no longer than 500kb. 1094 * 1095 * @since 8 1096 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1097 * @import N/A 1098 * @return String representing this {@code Query}. 1099 */ 1100 getSqlLike():string; 1101 } 1102 1103 /** 1104 * Represents a key-value distributed database and provides methods for adding, deleting, modifying, querying, 1105 * and subscribing to distributed data. 1106 * 1107 * <p>You can create distributed databases of different types by {@link KVManager#getKVStore (Options, String)} 1108 * with input parameter {@code Options}. Distributed database types are defined in {@code KVStoreType}, 1109 * including {@code SingleKVStore}. 1110 * 1111 * @since 7 1112 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1113 * @import N/A 1114 * @version 1 1115 */ 1116 interface KVStore { 1117 /** 1118 * Writes a key-value pair of the string type into the {@code KvStore} database. 1119 * 1120 * <p>If you do not want to synchronize this key-value pair to other devices, set the write option in the local database. 1121 * 1122 * @note N/A 1123 * @since 7 1124 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1125 * @param key Indicates the key. The length must be less than {@code MAX_KEY_LENGTH}. 1126 * Spaces before and after the key will be cleared. 1127 * @param value Indicates the string value, which must be less than 4 MB as a UTF-8 byte array. 1128 * @throws Throws this exception if any of the following errors 1129 * occurs: {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, and 1130 * {@code DB_ERROR}. 1131 */ 1132 put(key: string, value: Uint8Array | string | number | boolean, callback: AsyncCallback<void>): void; 1133 put(key: string, value: Uint8Array | string | number | boolean): Promise<void>; 1134 1135 /** 1136 * Deletes the key-value pair based on a specified key. 1137 * 1138 * @note N/A 1139 * @since 7 1140 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1141 * @param key Indicates the key. The length must be less than {@code MAX_KEY_LENGTH}. 1142 * Spaces before and after the key will be cleared. 1143 * @throws Throws this exception if any of the following errors 1144 * occurs: {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, and 1145 * {@code DB_ERROR}, and {@code KEY_NOT_FOUND}. 1146 */ 1147 delete(key: string, callback: AsyncCallback<void>): void; 1148 delete(key: string): Promise<void>; 1149 1150 /** 1151 * Registers a {@code KvStoreObserver} for the database. When data in the distributed database changes, the callback in 1152 * {@code KvStoreObserver} will be invoked. 1153 * 1154 * @note N/A 1155 * @since 7 1156 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1157 * @param type Indicates the subscription type, which is defined in {@code SubscribeType}. 1158 * @param observer Indicates the observer of data change events in the distributed database. 1159 * @throws Throws this exception if any of the following errors 1160 * occurs: {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, 1161 * {@code DB_ERROR}, and {@code STORE_ALREADY_SUBSCRIBE}. 1162 */ 1163 on(event: 'dataChange', type: SubscribeType, observer: Callback<ChangeNotification>): void; 1164 1165 /** 1166 * Subscribes from the {@code KvStore} database based on the specified subscribeType and {@code KvStoreObserver}. 1167 * 1168 * @note N/A 1169 * @since 7 1170 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1171 * @throws Throws this exception if any of the following errors 1172 * occurs: {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, 1173 * {@code DB_ERROR}, and {@code STORE_ALREADY_SUBSCRIBE}. 1174 */ 1175 on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void; 1176 1177 /** 1178 * Unsubscribes from the {@code KvStore} database based on the specified subscribeType and {@code KvStoreObserver}. 1179 * 1180 * @note N/A 1181 * @since 8 1182 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1183 * @param observer Indicates the data change observer registered by {#subscribe(SubscribeType, KvStoreObserver)}. 1184 * @throws Throws this exception if any of the following errors 1185 * occurs: {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, 1186 * {@code DB_ERROR}, and {@code STORE_ALREADY_SUBSCRIBE}. 1187 */ 1188 off(event:'dataChange', observer?: Callback<ChangeNotification>): void; 1189 1190 /** 1191 * Inserts key-value pairs into the {@code KvStore} database in batches. 1192 * 1193 * @note N/A 1194 * @since 8 1195 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1196 * @param entries Indicates the key-value pairs to be inserted in batches. 1197 * @throws Throws this exception if a database error occurs. 1198 */ 1199 putBatch(entries: Entry[], callback: AsyncCallback<void>): void; 1200 putBatch(entries: Entry[]): Promise<void>; 1201 1202 /** 1203 * Deletes key-value pairs in batches from the {@code KvStore} database. 1204 * 1205 * @note N/A 1206 * @since 8 1207 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1208 * @param keys Indicates the key-value pairs to be deleted in batches. 1209 * @throws Throws this exception if a database error occurs. 1210 */ 1211 deleteBatch(keys: string[], callback: AsyncCallback<void>): void; 1212 deleteBatch(keys: string[]): Promise<void>; 1213 1214 /** 1215 * Starts a transaction operation in the {@code KvStore} database. 1216 * 1217 * <p>After the database transaction is started, you can submit or roll back the operation. 1218 * 1219 * @note N/A 1220 * @since 8 1221 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1222 * @throws Throws this exception if a database error occurs. 1223 */ 1224 startTransaction(callback: AsyncCallback<void>): void; 1225 startTransaction(): Promise<void>; 1226 1227 /** 1228 * Submits a transaction operation in the {@code KvStore} database. 1229 * 1230 * @note N/A 1231 * @since 8 1232 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1233 * @param callback 1234 * @throws Throws this exception if a database error occurs. 1235 */ 1236 commit(callback: AsyncCallback<void>): void; 1237 commit(): Promise<void>; 1238 1239 /** 1240 * Rolls back a transaction operation in the {@code KvStore} database. 1241 * 1242 * @note N/A 1243 * @since 8 1244 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1245 * @throws Throws this exception if a database error occurs. 1246 */ 1247 rollback(callback: AsyncCallback<void>): void; 1248 rollback(): Promise<void>; 1249 1250 /** 1251 * Sets whether to enable synchronization. 1252 * 1253 * @note N/A 1254 * @since 8 1255 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1256 * @param enabled Specifies whether to enable synchronization. The value true means to enable 1257 * synchronization, and false means the opposite. 1258 * @throws Throws this exception if an internal service error occurs. 1259 */ 1260 enableSync(enabled: boolean, callback: AsyncCallback<void>): void; 1261 enableSync(enabled: boolean): Promise<void>; 1262 1263 /** 1264 * Sets synchronization range labels. 1265 * 1266 * <p>The labels determine the devices with which data will be synchronized. 1267 * 1268 * @note N/A 1269 * @since 8 1270 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1271 * @param localLabels Indicates the synchronization labels of the local device. 1272 * @param remoteSupportLabels Indicates the labels of the devices with which data will be synchronized. 1273 * @throws Throws this exception if an internal service error occurs. 1274 */ 1275 setSyncRange(localLabels: string[], remoteSupportLabels: string[], callback: AsyncCallback<void>): void; 1276 setSyncRange(localLabels: string[], remoteSupportLabels: string[]): Promise<void>; 1277 } 1278 1279 /** 1280 * Provides methods related to single-version distributed databases. 1281 * 1282 * <p>To create a {@code SingleKVStore} database, 1283 * you can use the {@link data.distributed.common.KVManager#getKVStore(Options, String)} method 1284 * with {@code KVStoreType} set to {@code SINGLE_VERSION} for the input parameter {@code Options}. 1285 * This database synchronizes data to other databases in time sequence. 1286 * The {@code SingleKVStore} database does not support 1287 * synchronous transactions, or data search using snapshots. 1288 * 1289 * @since 7 1290 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1291 * @import N/A 1292 * @version 1 1293 */ 1294 interface SingleKVStore extends KVStore { 1295 /** 1296 * Obtains the {@code String} value of a specified key. 1297 * 1298 * @since 7 1299 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1300 * @import N/A 1301 * @param key Indicates the key of the boolean value to be queried. 1302 * @throws Throws this exception if any of the following errors occurs:{@code INVALID_ARGUMENT}, 1303 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, {@code DB_ERROR}, and {@code KEY_NOT_FOUND}. 1304 */ 1305 get(key: string, callback: AsyncCallback<Uint8Array | string | boolean | number>): void; 1306 get(key: string): Promise<Uint8Array | string | boolean | number>; 1307 1308 /** 1309 * Obtains all key-value pairs that match a specified key prefix. 1310 * 1311 * @since 8 1312 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1313 * @import N/A 1314 * @param keyPrefix Indicates the key prefix to match. 1315 * @returns Returns the list of all key-value pairs that match the specified key prefix. 1316 * @throws Throws this exception if any of the following errors occurs:{@code INVALID_ARGUMENT}, 1317 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, and {@code DB_ERROR}. 1318 */ 1319 getEntries(keyPrefix: string, callback: AsyncCallback<Entry[]>): void; 1320 getEntries(keyPrefix: string): Promise<Entry[]>; 1321 1322 /** 1323 * Obtains the list of key-value pairs matching the specified {@code Query} object. 1324 * 1325 * @since 8 1326 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1327 * @import N/A 1328 * @param query Indicates the {@code Query} object. 1329 * @returns Returns the list of key-value pairs matching the specified {@code Query} object. 1330 * @throws Throws this exception if any of the following errors occurs: {@code INVALID_ARGUMENT}, 1331 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, and {@code DB_ERROR}. 1332 */ 1333 getEntries(query: Query, callback: AsyncCallback<Entry[]>): void; 1334 getEntries(query: Query): Promise<Entry[]>; 1335 1336 /** 1337 * Obtains the result sets with a specified prefix from a {@code KvStore} database. The {@code KvStoreResultSet} object can be used to 1338 * query all key-value pairs that meet the search criteria. Each {@code KvStore} instance can have a maximum of four 1339 * {@code KvStoreResultSet} objects at the same time. If you have created four objects, calling this method will return a 1340 * failure. Therefore, you are advised to call the closeResultSet method to close unnecessary {@code KvStoreResultSet} objects 1341 * in a timely manner. 1342 * 1343 * @since 8 1344 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1345 * @import N/A 1346 * @param keyPrefix Indicates the key prefix to match. 1347 * @throws Throws this exception if any of the following errors occurs:{@code INVALID_ARGUMENT}, 1348 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, and {@code DB_ERROR}. 1349 */ 1350 getResultSet(keyPrefix: string, callback: AsyncCallback<KvStoreResultSet>): void; 1351 getResultSet(keyPrefix: string): Promise<KvStoreResultSet>; 1352 1353 /** 1354 * Obtains the {@code KvStoreResultSet} object matching the specified {@code Query} object. 1355 * 1356 * @since 8 1357 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1358 * @import N/A 1359 * @param query Indicates the {@code Query} object. 1360 * @throws Throws this exception if any of the following errors occurs:{@code INVALID_ARGUMENT}, 1361 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, and {@code DB_ERROR}. 1362 */ 1363 getResultSet(query: Query, callback: AsyncCallback<KvStoreResultSet>): void; 1364 getResultSet(query: Query): Promise<KvStoreResultSet>; 1365 1366 /** 1367 * Closes a {@code KvStoreResultSet} object returned by getResultSet. 1368 * 1369 * @since 8 1370 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1371 * @import N/A 1372 * @param resultSet Indicates the {@code KvStoreResultSet} object to close. 1373 * @throws Throws this exception if any of the following errors occurs:{@code INVALID_ARGUMENT}, 1374 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, and {@code DB_ERROR}. 1375 */ 1376 closeResultSet(resultSet: KvStoreResultSet, callback: AsyncCallback<void>): void; 1377 closeResultSet(resultSet: KvStoreResultSet): Promise<void>; 1378 1379 /** 1380 * Obtains the number of results matching the specified {@code Query} object. 1381 * 1382 * @since 8 1383 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1384 * @import N/A 1385 * @param query Indicates the {@code Query} object. 1386 * @returns Returns the number of results matching the specified {@code Query} object. 1387 * @throws Throws this exception if any of the following errors occurs:{@code INVALID_ARGUMENT}, 1388 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, and {@code DB_ERROR}. 1389 */ 1390 getResultSize(query: Query, callback: AsyncCallback<number>): void; 1391 getResultSize(query: Query): Promise<number>; 1392 1393 /** 1394 * void removeDeviceData({@link String} deviceId) throws {@link KvStoreException} 1395 * 1396 * @since 8 1397 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1398 * @import N/A 1399 */ 1400 removeDeviceData(deviceId: string, callback: AsyncCallback<void>): void; 1401 removeDeviceData(deviceId: string): Promise<void>; 1402 1403 /** 1404 * Synchronizes the database to the specified devices with the specified delay allowed. 1405 * 1406 * @note N/A 1407 * @since 7 1408 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1409 * @param deviceIdList Indicates the list of devices to which to synchronize the database. 1410 * @param mode Indicates the synchronization mode. The value can be {@code PUSH}, {@code PULL}, or {@code PUSH_PULL}. 1411 * @param allowedDelayMs Indicates the delay allowed for the synchronization, in milliseconds. 1412 * @throws Throws this exception if any of the following errors 1413 * @permission ohos.permission.DISTRIBUTED_DATASYNC 1414 * occurs: {@code INVALID_ARGUMENT}, 1415 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, and {@code DB_ERROR}. 1416 */ 1417 sync(deviceIdList: string[], mode: SyncMode, allowedDelayMs?: number): void; 1418 1419 /** 1420 * Register Synchronizes SingleKvStore databases callback. 1421 * 1422 * <p> Sync result is returned through asynchronous callback. 1423 * @note N/A 1424 * @since 8 1425 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1426 * @param syncCallback Indicates the callback used to send the synchronization result to the caller. 1427 * @throws Throws this exception if no {@code SingleKvStore} database is available. 1428 */ 1429 on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void; 1430 1431 /** 1432 * UnRegister Synchronizes SingleKvStore databases callback. 1433 * @note N/A 1434 * @since 8 1435 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1436 * @throws Throws this exception if no {@code SingleKvStore} database is available. 1437 */ 1438 off(event: 'syncComplete', syncCallback?: Callback<Array<[string, number]>>): void; 1439 1440 1441 /** 1442 * Sets the default delay allowed for database synchronization 1443 * 1444 * @note N/A 1445 * @since 8 1446 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1447 * @param defaultAllowedDelayMs Indicates the default delay allowed for the database synchronization, in milliseconds. 1448 * @throws Throws this exception if any of the following errors occurs:{@code INVALID_ARGUMENT}, 1449 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, and {@code DB_ERROR}. 1450 */ 1451 setSyncParam(defaultAllowedDelayMs: number, callback: AsyncCallback<void>): void; 1452 setSyncParam(defaultAllowedDelayMs: number): Promise<void>; 1453 1454 /** 1455 * Get the security level of the database. 1456 * 1457 * @note N/A 1458 * @since 8 1459 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1460 * @returns SecurityLevel {@code SecurityLevel} the security level of the database. 1461 * @throws Throws this exception if any of the following errors occurs:{@code SERVER_UNAVAILABLE}, 1462 * {@code IPC_ERROR}, and {@code DB_ERROR}. 1463 */ 1464 getSecurityLevel(callback: AsyncCallback<SecurityLevel>): void; 1465 getSecurityLevel(): Promise<SecurityLevel>; 1466 } 1467 1468 /** 1469 * Manages distributed data by device in a distributed system. 1470 * 1471 * <p>To create a {@code DeviceKVStore} database, you can use the {@link data.distributed.common.KVManager.getKvStore(Options, String)} 1472 * method with {@code KvStoreType} set to {@code DEVICE_COLLABORATION} for the input parameter Options. This database manages distributed 1473 * data by device, and cannot modify data synchronized from remote devices. When an application writes a key-value pair entry 1474 * into the database, the system automatically adds the ID of the device running the application to the key. 1475 * 1476 * @since 8 1477 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1478 * @import N/A 1479 */ 1480 interface DeviceKVStore extends KVStore { 1481 /** 1482 * Obtains the {@code String} value matching a specified device ID and key. 1483 * 1484 * @note N/A 1485 * @since 8 1486 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1487 * @param deviceId Indicates the device to be queried. 1488 * @param key Indicates the key of the value to be queried. 1489 * @return Returns the value matching the given criteria. 1490 * @throws Throws this exception if any of the following errors occurs: {@code INVALID_ARGUMENT}, 1491 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, {@code DB_ERROR}, and {@code KEY_NOT_FOUND}. 1492 */ 1493 get(deviceId: string, key: string, callback: AsyncCallback<boolean|string|number|Uint8Array>): void; 1494 get(deviceId: string, key: string): Promise<boolean|string|number|Uint8Array>; 1495 1496 /** 1497 * Obtains all key-value pairs matching a specified device ID and key prefix. 1498 * 1499 * @note N/A 1500 * @since 8 1501 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1502 * @param deviceId Identifies the device whose data is to be queried. 1503 * @param keyPrefix Indicates the key prefix to match. 1504 * @returns Returns the list of all key-value pairs meeting the given criteria. 1505 * @throws Throws this exception if any of the following errors occurs: {@code INVALID_ARGUMENT}, 1506 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, {@code DB_ERROR}. 1507 */ 1508 getEntries(deviceId: string, keyPrefix: string, callback: AsyncCallback<Entry[]>): void; 1509 getEntries(deviceId: string, keyPrefix: string): Promise<Entry[]>; 1510 1511 /** 1512 * Obtains the list of key-value pairs matching the specified {@code Query} object. 1513 * 1514 * @note N/A 1515 * @since 8 1516 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1517 * @param query Indicates the {@code Query} object. 1518 * @returns Returns the list of key-value pairs matching the specified {@code Query} object. 1519 * @throws Throws this exception if any of the following errors occurs: {@code INVALID_ARGUMENT}, 1520 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, {@code DB_ERROR}. 1521 */ 1522 getEntries(query: Query, callback: AsyncCallback<Entry[]>): void; 1523 getEntries(query: Query): Promise<Entry[]>; 1524 1525 /** 1526 * Obtains the list of key-value pairs matching a specified device ID and {@code Query} object. 1527 * 1528 * @note N/A 1529 * @since 8 1530 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1531 * @param deviceId Indicates the ID of the device to which the key-value pairs belong. 1532 * @param query Indicates the {@code Query} object. 1533 * @returns Returns the list of key-value pairs matching the specified {@code Query} object. 1534 */ 1535 getEntries(deviceId: string, query: Query, callback: AsyncCallback<Entry[]>): void; 1536 getEntries(deviceId: string, query: Query): Promise<Entry[]>; 1537 1538 /** 1539 * Obtains the {@code KvStoreResultSet} object matching the specified device ID and key prefix. 1540 * 1541 * <p>The {@code KvStoreResultSet} object can be used to query all key-value pairs that meet the search criteria. Each {@code KvStore} 1542 * instance can have a maximum of four {@code KvStoreResultSet} objects at the same time. If you have created four objects, 1543 * calling this method will return a failure. Therefore, you are advised to call the closeResultSet method to close unnecessary 1544 * {@code KvStoreResultSet} objects in a timely manner. 1545 * 1546 * @note N/A 1547 * @since 8 1548 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1549 * @param deviceId Identifies the device whose data is to be queried. 1550 * @param keyPrefix Indicates the key prefix to match. 1551 * @returns Returns the {@code KvStoreResultSet} objects. 1552 * @throws Throws this exception if any of the following errors occurs: {@code INVALID_ARGUMENT}, 1553 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, {@code DB_ERROR}. 1554 */ 1555 getResultSet(deviceId: string, keyPrefix: string, callback: AsyncCallback<KvStoreResultSet>): void; 1556 getResultSet(deviceId: string, keyPrefix: string): Promise<KvStoreResultSet>; 1557 1558 /** 1559 * Obtains the {@code KvStoreResultSet} object matching the specified {@code Query} object. 1560 * 1561 * @note N/A 1562 * @since 8 1563 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1564 * @param query Indicates the {@code Query} object. 1565 * @returns Returns the {@code KvStoreResultSet} object matching the specified {@code Query} object. 1566 * @throws Throws this exception if any of the following errors occurs: {@code INVALID_ARGUMENT}, 1567 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, {@code DB_ERROR}. 1568 */ 1569 getResultSet(query: Query, callback: AsyncCallback<KvStoreResultSet>): void; 1570 getResultSet(query: Query): Promise<KvStoreResultSet>; 1571 1572 /** 1573 * Obtains the {@code KvStoreResultSet} object matching a specified device ID and {@code Query} object. 1574 * 1575 * @note N/A 1576 * @since 8 1577 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1578 * @param deviceId Indicates the ID of the device to which the {@code KvStoreResultSet} object belongs. 1579 * @param query Indicates the {@code Query} object. 1580 * @returns Returns the {@code KvStoreResultSet} object matching the specified {@code Query} object. 1581 */ 1582 getResultSet(deviceId: string, query: Query, callback: AsyncCallback<KvStoreResultSet>): void; 1583 getResultSet(deviceId: string, query: Query): Promise<KvStoreResultSet>; 1584 1585 /** 1586 * Closes a {@code KvStoreResultSet} object returned by getResultSet. 1587 * 1588 * @note N/A 1589 * @since 8 1590 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1591 * @param resultSet Indicates the {@code KvStoreResultSet} object to close. 1592 * @throws Throws this exception if any of the following errors occurs: {@code INVALID_ARGUMENT}, 1593 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, {@code DB_ERROR}. 1594 */ 1595 closeResultSet(resultSet: KvStoreResultSet, callback: AsyncCallback<void>): void; 1596 closeResultSet(resultSet: KvStoreResultSet): Promise<void>; 1597 1598 /** 1599 * Obtains the number of results matching the specified {@code Query} object. 1600 * 1601 * @note N/A 1602 * @since 8 1603 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1604 * @param query Indicates the {@code Query} object. 1605 * @returns Returns the number of results matching the specified {@code Query} object. 1606 * @throws Throws this exception if any of the following errors occurs: {@code INVALID_ARGUMENT}, 1607 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, {@code DB_ERROR}. 1608 */ 1609 getResultSize(query: Query, callback: AsyncCallback<number>): void; 1610 getResultSize(query: Query): Promise<number>; 1611 1612 /** 1613 * Obtains the number of results matching a specified device ID and {@code Query} object. 1614 * 1615 * @note N/A 1616 * @since 8 1617 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1618 * @param deviceId Indicates the ID of the device to which the results belong. 1619 * @param query Indicates the {@code Query} object. 1620 * @returns Returns the number of results matching the specified {@code Query} object. 1621 */ 1622 getResultSize(deviceId: string, query: Query, callback: AsyncCallback<number>): void; 1623 getResultSize(deviceId: string, query: Query): Promise<number>; 1624 1625 /** 1626 * Removes data of a specified device from the current database. This method is used to remove only the data 1627 * synchronized from remote devices. This operation does not synchronize data to other databases or affect 1628 * subsequent data synchronization. 1629 * 1630 * @note N/A 1631 * @since 8 1632 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1633 * @param deviceId Identifies the device whose data is to be removed. The value cannot be the current device ID. 1634 * @throws Throws this exception if any of the following errors occurs: {@code INVALID_ARGUMENT}, 1635 * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, {@code DB_ERROR}. 1636 */ 1637 removeDeviceData(deviceId: string, callback: AsyncCallback<void>): void; 1638 removeDeviceData(deviceId: string): Promise<void>; 1639 1640 /** 1641 * Synchronizes {@code DeviceKVStore} databases. 1642 * 1643 * <p>This method returns immediately and sync result will be returned through asynchronous callback. 1644 * @note N/A 1645 * @since 8 1646 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1647 * @param deviceIdList Indicates the list of IDs of devices whose 1648 * {@code DeviceKVStore} databases are to be synchronized. 1649 * @param mode Indicates the synchronization mode, {@code PUSH}, {@code PULL}, or 1650 * {@code PUSH_PULL}. 1651 * @permission ohos.permission.DISTRIBUTED_DATASYNC 1652 * @throws Throws this exception if no DeviceKVStore database is available. 1653 */ 1654 sync(deviceIdList: string[], mode: SyncMode, allowedDelayMs?: number): void; 1655 1656 /** 1657 * Register Synchronizes DeviceKVStore databases callback. 1658 * 1659 * <p>Sync result is returned through asynchronous callback. 1660 * @note N/A 1661 * @since 8 1662 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1663 * @param syncCallback Indicates the callback used to send the synchronization result to the caller. 1664 * @throws Throws this exception if no DeviceKVStore database is available. 1665 */ 1666 on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void; 1667 1668 /** 1669 * UnRegister Synchronizes DeviceKVStore databases callback. 1670 * @note N/A 1671 * @since 8 1672 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1673 * @throws Throws this exception if no DeviceKVStore database is available. 1674 */ 1675 off(event: 'syncComplete', syncCallback?: Callback<Array<[string, number]>>): void; 1676 } 1677 1678 /** 1679 * Creates a {@link KVManager} instance based on the configuration information. 1680 * 1681 * <p>You must pass {@link KVManagerConfig} to provide configuration information 1682 * for creating the {@link KVManager} instance. 1683 * 1684 * @note N/A 1685 * @since 7 1686 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1687 * @param config Indicates the {@link KVStore} configuration information, 1688 * including the user information and package name. 1689 * @return Returns the {@code KVManager} instance. 1690 * @throws Throws exception if input is invalid. 1691 */ 1692 function createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager>): void; 1693 function createKVManager(config: KVManagerConfig): Promise<KVManager>; 1694 1695 /** 1696 * Provides interfaces to manage a {@code KVStore} database, including obtaining, closing, and deleting the {@code KVStore}. 1697 * 1698 * @since 7 1699 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1700 * @import N/A 1701 * @version 1 1702 */ 1703 interface KVManager { 1704 /** 1705 * Creates and obtains a {@code KVStore} database by specifying {@code Options} and {@code storeId}. 1706 * 1707 * @note N/A 1708 * @since 7 1709 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1710 * @param options Indicates the options used for creating and obtaining the {@code KVStore} database, 1711 * including {@code isCreateIfMissing}, {@code isEncrypt}, and {@code KVStoreType}. 1712 * @param storeId Identifies the {@code KVStore} database. 1713 * The value of this parameter must be unique for the same application, 1714 * and different applications can share the same value. 1715 * @return Returns a {@code KVStore}, or {@code SingleKVStore}. 1716 */ 1717 getKVStore<T extends KVStore>(storeId: string, options: Options): Promise<T>; 1718 getKVStore<T extends KVStore>(storeId: string, options: Options, callback: AsyncCallback<T>): void; 1719 1720 /** 1721 * Closes the {@code KvStore} database. 1722 * 1723 * <p>Warning: This method is not thread-safe. If you call this method to stop a KvStore database that is running, your 1724 * thread may crash. 1725 * 1726 * <p>The {@code KvStore} database to close must be an object created by using the {@code getKvStore} method. Before using this 1727 * method, release the resources created for the database, for example, {@code KvStoreResultSet} for {@code SingleKvStore}, 1728 * otherwise closing the database will fail. If you are attempting to close a database that is already closed, an error 1729 * will be returned. 1730 * 1731 * @note N/A 1732 * @since 8 1733 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1734 * @param kvStore Indicates the {@code KvStore} database to close. 1735 * @throws Throws this exception if any of the following errors 1736 * occurs:{@code INVALID_ARGUMENT}, {@code ERVER_UNAVAILABLE}, 1737 * {@code STORE_NOT_OPEN}, {@code STORE_NOT_FOUND}, {@code DB_ERROR}, 1738 * {@code PERMISSION_DENIED}, and {@code IPC_ERROR}. 1739 */ 1740 closeKVStore(appId: string, storeId: string, kvStore: KVStore, callback: AsyncCallback<void>): void; 1741 closeKVStore(appId: string, storeId: string, kvStore: KVStore): Promise<void>; 1742 1743 /** 1744 * Deletes the {@code KvStore} database identified by storeId. 1745 * 1746 * <p>Before using this method, close all {@code KvStore} instances in use that are identified by the same storeId. 1747 * 1748 * <p>You can use this method to delete a {@code KvStore} database not in use. After the database is deleted, all its data will be 1749 * lost. 1750 * @note N/A 1751 * @since 8 1752 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1753 * @param storeId Identifies the {@code KvStore} database to delete. 1754 * @throws Throws this exception if any of the following errors 1755 * occurs: {@code INVALID_ARGUMENT}, 1756 * {@code SERVER_UNAVAILABLE}, {@code STORE_NOT_FOUND}, 1757 * {@code DB_ERROR}, {@code PERMISSION_DENIED}, and {@code IPC_ERROR}. 1758 */ 1759 deleteKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void; 1760 deleteKVStore(appId: string, storeId: string): Promise<void>; 1761 1762 /** 1763 * Obtains the storeId of all {@code KvStore} databases that are created by using the {@code getKvStore} method and not deleted by 1764 * calling the {@code deleteKvStore} method. 1765 * 1766 * @note N/A 1767 * @since 8 1768 * @syscap SystemCapability.DistributedDataManager.KVStore.Core 1769 * @returns Returns the storeId of all created {@code KvStore} databases. 1770 * @throws Throws this exception if any of the following errors 1771 * occurs: {@code SERVER_UNAVAILABLE}, {@code DB_ERROR}, 1772 * {@code PERMISSION_DENIED}, and {@code IPC_ERROR}. 1773 */ 1774 getAllKVStoreId(appId: string, callback: AsyncCallback<string[]>): void; 1775 getAllKVStoreId(appId: string): Promise<string[]>; 1776 1777 /** 1778 * register DeviceChangeCallback to get notification when device's status changed 1779 * 1780 * @note N/A 1781 * @since 8 1782 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1783 * @param deathCallback device change callback {@code DeviceChangeCallback} 1784 * @throws exception maybe occurs. 1785 */ 1786 on(event: 'distributedDataServiceDie', deathCallback: Callback<void>): void; 1787 1788 /** 1789 * unRegister DeviceChangeCallback and can not receive notification 1790 * 1791 * @note N/A 1792 * @since 8 1793 * @syscap SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 1794 * @param deathCallback device change callback {@code DeviceChangeCallback} which has been registered. 1795 * @throws exception maybe occurs. 1796 */ 1797 off(event: 'distributedDataServiceDie', deathCallback?: Callback<void>): void; 1798 } 1799} 1800 1801export default distributedData;