1# Preferences 2 3 4## Overview 5 6The **Preferences** module provides APIs for key-value (KV) data processing, including querying, modifying, and persisting KV data. 7 8**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 9 10**Since**: 13 11 12 13## Summary 14 15 16### Files 17 18| Name| Description| 19| -------- | -------- | 20| [oh_preferences.h](oh__preferences_8h.md) | Provides APIs and structs for accessing the **Preferences** object.| 21| [oh_preferences_option.h](oh__preferences__option_8h.md) | Provides APIs and structs for accessing the **PreferencesOption** object.| 22| [oh_preferences_value.h](oh__preferences__value_8h.md) | Provides APIs, enums, and structs for accessing the **PreferencesValue** object.| 23 24 25### Types 26 27| Name| Description| 28| -------- | -------- | 29| typedef struct [OH_Preferences](#oh_preferences) [OH_Preferences](#oh_preferences) | Defines a struct for a **Preferences** object.| 30| typedef void(\* [OH_PreferencesDataObserver](#oh_preferencesdataobserver)) (void \*context, const [OH_PreferencesPair](#oh_preferencespair) \*pairs, uint32_t count) | Defines a struct for the callback for data changes.| 31| typedef enum [OH_Preferences_ErrCode](#oh_preferences_errcode) [OH_Preferences_ErrCode](#oh_preferences_errcode) | Defines an enum for error codes.| 32| typedef struct [OH_PreferencesOption](#oh_preferencesoption) [OH_PreferencesOption](#oh_preferencesoption) | Defines a struct for **Preferences** configuration.| 33| typedef enum [Preference_ValueType](#preference_valuetype) [Preference_ValueType](#preference_valuetype) | Defines an enum for types of **PreferencesValue**.| 34| typedef struct [OH_PreferencesPair](#oh_preferencespair) [OH_PreferencesPair](#oh_preferencespair) | Defines a struct for the Preferences data in KV format.| 35| typedef struct [OH_PreferencesValue](#oh_preferencesvalue) [OH_PreferencesValue](#oh_preferencesvalue) | Defines the struct for a **PreferencesValue** object.| 36 37 38### Enums 39 40| Name| Description| 41| -------- | -------- | 42| [OH_Preferences_ErrCode](#oh_preferences_errcode-1) {<br>PREFERENCES_OK = 0, PREFERENCES_ERROR_INVALID_PARAM = 401, PREFERENCES_ERROR_NOT_SUPPORTED = 801, PREFERENCES_ERROR_BASE = 15500000,<br>PREFERENCES_ERROR_DELETE_FILE = 15500010, PREFERENCES_ERROR_STORAGE = 15500011, PREFERENCES_ERROR_MALLOC = 15500012, PREFERENCES_ERROR_KEY_NOT_FOUND = 15500013,<br>PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT = 15500019<br>} | Enumerates the error codes.| 43| [Preference_ValueType](#preference_valuetype-1) {<br>PREFERENCE_TYPE_NULL = 0, PREFERENCE_TYPE_INT, PREFERENCE_TYPE_BOOL, PREFERENCE_TYPE_STRING,<br>PREFERENCE_TYPE_BUTT<br>} | Enumerates the types of **PreferencesValue**.| 44 45 46### Functions 47 48| Name| Description| 49| -------- | -------- | 50| [OH_Preferences](#oh_preferences) \* [OH_Preferences_Open](#oh_preferences_open) ([OH_PreferencesOption](#oh_preferencesoption) \*option, int \*errCode) | Opens a **Preferences** instance and creates a pointer to it. If the pointer is no longer required, use [OH_Preferences_Close][OH_Preferences_Close](#oh_preferences_close) to close the instance.| 51| int [OH_Preferences_Close](#oh_preferences_close) ([OH_Preferences](#oh_preferences) \*preference) | Closes a **Preferences** instance.| 52| int [OH_Preferences_GetInt](#oh_preferences_getint) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, int \*value) | Obtains an integer corresponding to the specified key in a **Preferences** instance.| 53| int [OH_Preferences_GetBool](#oh_preferences_getbool) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, bool \*value) | Obtains a Boolean value corresponding to the specified key in a **Preferences** instance.| 54| int [OH_Preferences_GetString](#oh_preferences_getstring) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, char \*\*value, uint32_t \*valueLen) | Obtains a string corresponding to the specified key in a **Preferences** instance.| 55| void [OH_Preferences_FreeString](#oh_preferences_freestring) (char \*string) | Releases a string.| 56| int [OH_Preferences_SetInt](#oh_preferences_setint) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, int value) | Sets an integer based on the specified key in a **Preferences** instance.| 57| int [OH_Preferences_SetBool](#oh_preferences_setbool) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, bool value) | Sets a Boolean value based on the specified key in a **Preferences** instance.| 58| int [OH_Preferences_SetString](#oh_preferences_setstring) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, const char \*value) | Sets a string based on the specified key in a **Preferences** instance.| 59| int [OH_Preferences_Delete](#oh_preferences_delete) ([OH_Preferences](#oh_preferences) \*preference, const char \*key) | Deletes the KV data corresponding to the specified key from a **Preferences** instance.| 60| int [OH_Preferences_RegisterDataObserver](#oh_preferences_registerdataobserver) ([OH_Preferences](#oh_preferences) \*preference, void \*context, [OH_PreferencesDataObserver](#oh_preferencesdataobserver) observer, const char \*keys[], uint32_t keyCount) | Subscribes to data changes of the specified keys. If the value of the specified key changes, a callback will be invoked after **OH_Preferences_Close ()** is called.| 61| int [OH_Preferences_UnregisterDataObserver](#oh_preferences_unregisterdataobserver) ([OH_Preferences](#oh_preferences) \*preference, void \*context, [OH_PreferencesDataObserver](#oh_preferencesdataobserver) observer, const char \*keys[], uint32_t keyCount) | Unsubscribes from data changes of the specified keys.| 62| [OH_PreferencesOption](#oh_preferencesoption) \* [OH_PreferencesOption_Create](#oh_preferencesoption_create) (void) | Creates an [OH_PreferencesOption](#oh_preferencesoption) instance and a pointer to it. If this pointer is no longer required, use [OH_PreferencesOption_Destroy](#oh_preferencesoption_destroy) to destroy it. Otherwise, memory leaks may occur.| 63| int [OH_PreferencesOption_SetFileName](#oh_preferencesoption_setfilename) ([OH_PreferencesOption](#oh_preferencesoption) \*option, const char \*fileName) | Sets the file name for an [OH_PreferencesOption](#oh_preferencesoption) instance.| 64| int [OH_PreferencesOption_SetBundleName](#oh_preferencesoption_setbundlename) ([OH_PreferencesOption](#oh_preferencesoption) \*option, const char \*bundleName) | Sets the bundle name for an [OH_PreferencesOption](#oh_preferencesoption) instance.| 65| int [OH_PreferencesOption_SetDataGroupId](#oh_preferencesoption_setdatagroupid) ([OH_PreferencesOption](#oh_preferencesoption) \*option, const char \*dataGroupId) | Sets the application group ID for an [OH_PreferencesOption](#oh_preferencesoption) instance.| 66| int [OH_PreferencesOption_Destroy](#oh_preferencesoption_destroy) ([OH_PreferencesOption](#oh_preferencesoption) \*option) | Destroys an [OH_PreferencesOption](#oh_preferencesoption) instance.| 67| const char \* [OH_PreferencesPair_GetKey](#oh_preferencespair_getkey) (const [OH_PreferencesPair](#oh_preferencespair) \*pairs, uint32_t index) | Obtains the key based on the specified index from the KV data.| 68| const [OH_PreferencesValue](#oh_preferencesvalue) \* [OH_PreferencesPair_GetPreferencesValue](#oh_preferencespair_getpreferencesvalue) (const [OH_PreferencesPair](#oh_preferencespair) \*pairs, uint32_t index) | Obtains the value based on the specified index from the KV pairs.| 69| [Preference_ValueType](#preference_valuetype) [OH_PreferencesValue_GetValueType](#oh_preferencesvalue_getvaluetype) (const [OH_PreferencesValue](#oh_preferencesvalue) \*object) | Obtains the data type of a **PreferencesValue** instance.| 70| int [OH_PreferencesValue_GetInt](#oh_preferencesvalue_getint) (const [OH_PreferencesValue](#oh_preferencesvalue) \*object, int \*value) | Obtains an integer value from an [OH_PreferencesValue](#oh_preferencesvalue) instance.| 71| int [OH_PreferencesValue_GetBool](#oh_preferencesvalue_getbool) (const [OH_PreferencesValue](#oh_preferencesvalue) \*object, bool \*value) | Obtains a Boolean value from an [OH_PreferencesValue](#oh_preferencesvalue) instance.| 72| int [OH_PreferencesValue_GetString](#oh_preferencesvalue_getstring) (const [OH_PreferencesValue](#oh_preferencesvalue) \*object, char \*\*value, uint32_t \*valueLen) | Obtains a string from an [OH_PreferencesValue](#oh_preferencesvalue) instance.| 73 74 75## Type Description 76 77 78### OH_Preferences 79 80``` 81typedef struct OH_Preferences OH_Preferences 82``` 83 84**Description** 85 86Represents a **Preferences** object. 87 88**Since**: 13 89 90 91### OH_Preferences_ErrCode 92 93``` 94typedef enum OH_Preferences_ErrCode OH_Preferences_ErrCode 95``` 96 97**Description** 98 99Defines an enum for error codes. 100 101**Since**: 13 102 103 104### OH_PreferencesDataObserver 105 106``` 107typedef void(*OH_PreferencesDataObserver) (void *context, const OH_PreferencesPair *pairs, uint32_t count) 108``` 109 110**Description** 111 112Defines a struct for the callback used to return data changes. 113 114**Since**: 13 115 116**Parameters** 117 118| Name| Description| 119| -------- | -------- | 120| context | Pointer to the application context.| 121| pairs | Pointer to the changed KV data.| 122| count | Number of KV pairs changed.| 123 124**See** 125 126[OH_PreferencesPair](#oh_preferencespair) 127 128 129### OH_PreferencesOption 130 131``` 132typedef struct OH_PreferencesOption OH_PreferencesOption 133``` 134 135**Description** 136 137Defines a struct for **Preferences** configuration. 138 139**Since**: 13 140 141 142### OH_PreferencesPair 143 144``` 145typedef struct OH_PreferencesPair OH_PreferencesPair 146``` 147 148**Description** 149 150Defines a struct for the **Preferences** data in KV format. 151 152**Since**: 13 153 154 155### OH_PreferencesValue 156 157``` 158typedef struct OH_PreferencesValue OH_PreferencesValue 159``` 160 161**Description** 162 163Defines the struct for a **PreferencesValue** object. 164 165**Since**: 13 166 167 168### Preference_ValueType 169 170``` 171typedef enum Preference_ValueType Preference_ValueType 172``` 173 174**Description** 175 176Defines an enum for types of **PreferencesValue**. 177 178**Since**: 13 179 180 181## Enum Description 182 183 184### OH_Preferences_ErrCode 185 186``` 187enum OH_Preferences_ErrCode 188``` 189 190**Description** 191 192Enumerates the error codes. 193 194**Since**: 13 195 196| Enumerated Value| Description| 197| -------- | -------- | 198| PREFERENCES_OK | The operation is successful.| 199| PREFERENCES_ERROR_INVALID_PARAM | Invalid parameter.| 200| PREFERENCES_ERROR_NOT_SUPPORTED | The system capability is not supported.| 201| PREFERENCES_ERROR_BASE | Base error code.| 202| PREFERENCES_ERROR_DELETE_FILE | Failed to delete the file.| 203| PREFERENCES_ERROR_STORAGE | The storage is abnormal.| 204| PREFERENCES_ERROR_MALLOC | Failed to allocate memory.| 205| PREFERENCES_ERROR_KEY_NOT_FOUND | The key does not exist.| 206| PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT | Failed to obtain the data change subscription service.| 207 208 209### Preference_ValueType 210 211``` 212enum Preference_ValueType 213``` 214 215**Description** 216 217Enumerates the types of **PreferencesValue**. 218 219**Since**: 13 220 221| Enumerated Value| Description| 222| -------- | -------- | 223| PREFERENCE_TYPE_NULL | Null.| 224| PREFERENCE_TYPE_INT | Integer.| 225| PREFERENCE_TYPE_BOOL | Boolean.| 226| PREFERENCE_TYPE_STRING | String.| 227| PREFERENCE_TYPE_BUTT | End type.| 228 229 230## Function Description 231 232 233### OH_Preferences_Close() 234 235``` 236int OH_Preferences_Close (OH_Preferences *preference) 237``` 238 239**Description** 240 241Closes a **Preferences** instance. 242 243**Since**: 13 244 245**Parameters** 246 247| Name| Description| 248| -------- | -------- | 249| preference | Pointer to the [OH_Preferences](#oh_preferences) instance to close.| 250 251**Returns** 252 253Returns [OH_Preferences_ErrCode](#oh_preferences_errcode). 254 255Returns **PREFERENCES_OK** if the operation is successful. 256 257Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 258 259Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 260 261Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 262 263**See** 264 265[OH_Preferences](#oh_preferences) 266 267[OH_Preferences_ErrCode](#oh_preferences_errcode) 268 269 270### OH_Preferences_Delete() 271 272``` 273int OH_Preferences_Delete (OH_Preferences *preference, const char *key ) 274``` 275 276**Description** 277 278Deletes the KV data corresponding to the specified key from a **Preferences** instance. 279 280**Since**: 13 281 282**Parameters** 283 284| Name| Description| 285| -------- | -------- | 286| preference | Pointer to the target [OH_Preferences](#oh_preferences) instance.| 287| key | Pointer to the key of the KV pair to delete.| 288 289**Returns** 290 291Returns the error code. 292 293Returns **PREFERENCES_OK** if the operation is successful. 294 295Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 296 297Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 298 299Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 300 301**See** 302 303[OH_Preferences](#oh_preferences) 304 305[OH_Preferences_ErrCode](#oh_preferences_errcode) 306 307 308### OH_Preferences_FreeString() 309 310``` 311void OH_Preferences_FreeString (char *string) 312``` 313 314**Description** 315 316Releases a string. 317 318**Since**: 13 319 320**Parameters** 321 322| Name| Description| 323| -------- | -------- | 324| string | Pointer to the string to release.| 325 326**See** 327 328[OH_Preferences](#oh_preferences) 329 330 331### OH_Preferences_GetBool() 332 333``` 334int OH_Preferences_GetBool (OH_Preferences *preference, const char *key, bool *value ) 335``` 336 337**Description** 338 339Obtains a Boolean value corresponding to the specified key in a **Preferences** instance. 340 341**Since**: 13 342 343**Parameters** 344 345| Name| Description| 346| -------- | -------- | 347| preference | Pointer to the target [OH_Preferences](#oh_preferences) instance.| 348| key | Pointer to the key of the value to obtain.| 349| value | Pointer to the Boolean value obtained.| 350 351**Returns** 352 353Returns the error code. 354 355Returns **PREFERENCES_OK** if the operation is successful. 356 357Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 358 359Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 360 361Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 362 363Returns **PREFERENCES_ERROR_KEY_NOT_FOUND** if the specified key does not exist. 364 365**See** 366 367[OH_Preferences](#oh_preferences) 368 369[OH_Preferences_ErrCode](#oh_preferences_errcode) 370 371 372### OH_Preferences_GetInt() 373 374``` 375int OH_Preferences_GetInt (OH_Preferences *preference, const char *key, int *value ) 376``` 377 378**Description** 379 380Obtains an integer corresponding to the specified key in a **Preferences** instance. 381 382**Since**: 13 383 384**Parameters** 385 386| Name| Description| 387| -------- | -------- | 388| preference | Pointer to the target [OH_Preferences](#oh_preferences) instance.| 389| key | Pointer to the key of the value to obtain.| 390| value | Pointer to the integer value obtained.| 391 392**Returns** 393 394Returns the error code. 395 396Returns **PREFERENCES_OK** if the operation is successful. 397 398Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 399 400Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 401 402Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 403 404Returns **PREFERENCES_ERROR_KEY_NOT_FOUND** if the specified key does not exist. 405 406**See** 407 408[OH_Preferences](#oh_preferences) 409 410[OH_Preferences_ErrCode](#oh_preferences_errcode) 411 412 413### OH_Preferences_GetString() 414 415``` 416int OH_Preferences_GetString (OH_Preferences *preference, const char *key, char **value, uint32_t *valueLen ) 417``` 418 419**Description** 420 421Obtains a string corresponding to the specified key in a **Preferences** instance. 422 423**Since**: 13 424 425**Parameters** 426 427| Name| Description| 428| -------- | -------- | 429| preference | Pointer to the target [OH_Preferences](#oh_preferences) instance.| 430| key | Pointer to the key of the value to obtain.| 431| value | Double pointer to the string obtained. If the string is not required, you can use [OH_Preferences_FreeString](#oh_preferences_freestring) to free the string (release the memory occupied by the string).| 432| valueLen | Pointer to the length of the string obtained.| 433 434**Returns** 435 436Returns the error code. 437 438Returns **PREFERENCES_OK** if the operation is successful. 439 440Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 441 442Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 443 444Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 445 446Returns **PREFERENCES_ERROR_KEY_NOT_FOUND** if the specified key does not exist. 447 448**See** 449 450[OH_Preferences](#oh_preferences) 451 452[OH_Preferences_ErrCode](#oh_preferences_errcode) 453 454 455### OH_Preferences_Open() 456 457``` 458OH_Preferences* OH_Preferences_Open (OH_PreferencesOption *option, int *errCode ) 459``` 460 461**Description** 462 463Opens a **Preferences** instance and creates a pointer to it. If the pointer is no longer required, use [OH_Preferences_Close](#oh_preferences_close) to close the instance. 464 465**Since**: 13 466 467**Parameters** 468 469| Name| Description| 470| -------- | -------- | 471| option | Pointer to the [OH_PreferencesOption](#oh_preferencesoption) instance.| 472| errCode | Pointer to the error code returned. For details, see [OH_Preferences_ErrCode](#oh_preferences_errcode).| 473 474**Returns** 475 476Returns the [OH_Preferences](#oh_preferences) instance opened if the operation is successful; returns a null pointer otherwise. 477 478**See** 479 480[OH_Preferences](#oh_preferences) 481 482[OH_PreferencesOption](#oh_preferencesoption) 483 484[OH_Preferences_ErrCode](#oh_preferences_errcode) 485 486 487### OH_Preferences_RegisterDataObserver() 488 489``` 490int OH_Preferences_RegisterDataObserver (OH_Preferences *preference, void *context, OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount ) 491``` 492 493**Description** 494 495Subscribes to data changes of the specified keys. If the value of the specified key changes, a callback will be invoked after **OH_Preferences_Close ()** is called. 496 497**Since**: 13 498 499**Parameters** 500 501| Name| Description| 502| -------- | -------- | 503| preference | Pointer to the target [OH_Preferences](#oh_preferences) instance.| 504| context | Pointer to the application context.| 505| observer | [OH_PreferencesDataObserver](#oh_preferencesdataobserver) callback to be invoked when the data changes.| 506| keys | Pointer to the keys of the data to be observed.| 507| keyCount | Number of keys observed.| 508 509**Returns** 510 511Returns the error code. 512 513Returns **PREFERENCES_OK** if the operation is successful. 514 515Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 516 517Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 518 519Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 520 521Returns **PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT** if the data change subscription service fails to be obtained. 522 523**See** 524 525[OH_Preferences](#oh_preferences) 526 527[OH_PreferencesDataObserver](#oh_preferencesdataobserver) 528 529[OH_Preferences_ErrCode](#oh_preferences_errcode) 530 531 532### OH_Preferences_SetBool() 533 534``` 535int OH_Preferences_SetBool (OH_Preferences *preference, const char *key, bool value ) 536``` 537 538**Description** 539 540Sets a Boolean value based on the specified key in a **Preferences** instance. 541 542**Since**: 13 543 544**Parameters** 545 546| Name| Description| 547| -------- | -------- | 548| preference | Pointer to the target [OH_Preferences](#oh_preferences) instance.| 549| key | Pointer to the key of the value to set.| 550| value | Boolean value to be set.| 551 552**Returns** 553 554Returns the error code. 555 556Returns **PREFERENCES_OK** if the operation is successful. 557 558Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 559 560Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 561 562Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 563 564**See** 565 566[OH_Preferences](#oh_preferences) 567 568[OH_Preferences_ErrCode](#oh_preferences_errcode) 569 570 571### OH_Preferences_SetInt() 572 573``` 574int OH_Preferences_SetInt (OH_Preferences *preference, const char *key, int value ) 575``` 576 577**Description** 578 579Sets an integer based on the specified key in a **Preferences** instance. 580 581**Since**: 13 582 583**Parameters** 584 585| Name| Description| 586| -------- | -------- | 587| preference | Pointer to the target [OH_Preferences](#oh_preferences) instance.| 588| key | Pointer to the key of the value to set.| 589| value | Integer value to be set.| 590 591**Returns** 592 593Returns the error code. 594 595Returns **PREFERENCES_OK** if the operation is successful. 596 597Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 598 599Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 600 601Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 602 603**See** 604 605[OH_Preferences](#oh_preferences) 606 607[OH_Preferences_ErrCode](#oh_preferences_errcode) 608 609 610### OH_Preferences_SetString() 611 612``` 613int OH_Preferences_SetString (OH_Preferences *preference, const char *key, const char *value ) 614``` 615 616**Description** 617 618Sets a string based on the specified key in a **Preferences** instance. 619 620**Since**: 13 621 622**Parameters** 623 624| Name| Description| 625| -------- | -------- | 626| preference | Pointer to the target [OH_Preferences](#oh_preferences) instance.| 627| key | Pointer to the key of the value to set.| 628| value | Pointer to the string to set.| 629 630**Returns** 631 632Returns the error code. 633 634Returns **PREFERENCES_OK** if the operation is successful. 635 636Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 637 638Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 639 640Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 641 642**See** 643 644[OH_Preferences](#oh_preferences) 645 646[OH_Preferences_ErrCode](#oh_preferences_errcode) 647 648 649### OH_Preferences_UnregisterDataObserver() 650 651``` 652int OH_Preferences_UnregisterDataObserver (OH_Preferences *preference, void *context, OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount ) 653``` 654 655**Description** 656 657Unsubscribes from data changes of the specified keys. 658 659**Since**: 13 660 661**Parameters** 662 663| Name| Description| 664| -------- | -------- | 665| preference | Pointer to the target [OH_Preferences](#oh_preferences) instance.| 666| context | Pointer to the application context.| 667| observer | [OH_PreferencesDataObserver](#oh_preferencesdataobserver) callback to unregister.| 668| keys | Pointer to the keys of the values whose changes are not observed.| 669| keyCount | Number of keys.| 670 671**Returns** 672 673Returns the error code. 674 675Returns **PREFERENCES_OK** if the operation is successful. 676 677Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 678 679Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 680 681Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 682 683**See** 684 685[OH_Preferences](#oh_preferences) 686 687[OH_PreferencesDataObserver](#oh_preferencesdataobserver) 688 689[OH_Preferences_ErrCode](#oh_preferences_errcode) 690 691 692### OH_PreferencesOption_Create() 693 694``` 695OH_PreferencesOption* OH_PreferencesOption_Create (void ) 696``` 697 698**Description** 699 700Creates an [OH_PreferencesOption](#oh_preferencesoption) instance and a pointer to it. If this pointer is no longer required, use [OH_PreferencesOption_Destroy](#oh_preferencesoption_destroy) to destroy it. Otherwise, memory leaks may occur. 701 702**Since**: 13 703 704**Returns** 705 706Returns a pointer to the [OH_PreferencesOption](#oh_preferencesoption) instance created if the operation is successful; returns a null pointer otherwise. 707 708**See** 709 710[OH_PreferencesOption](#oh_preferencesoption) 711 712 713### OH_PreferencesOption_Destroy() 714 715``` 716int OH_PreferencesOption_Destroy (OH_PreferencesOption *option) 717``` 718 719**Description** 720 721Destroys an [OH_PreferencesOption](#oh_preferencesoption) instance. 722 723**Since**: 13 724 725**Parameters** 726 727| Name| Description| 728| -------- | -------- | 729| option | Pointer to the [OH_PreferencesOption](#oh_preferencesoption) instance to destroy.| 730 731**Returns** 732 733Returns the error code. Returns **PREFERENCES_OK** if the operation is successful. 734 735Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 736 737**See** 738 739[OH_PreferencesOption](#oh_preferencesoption) 740 741[OH_Preferences_ErrCode](#oh_preferences_errcode) 742 743 744### OH_PreferencesOption_SetBundleName() 745 746``` 747int OH_PreferencesOption_SetBundleName (OH_PreferencesOption *option, const char *bundleName ) 748``` 749 750**Description** 751 752Sets the bundle name for an [OH_PreferencesOption](#oh_preferencesoption) instance. 753 754**Since**: 13 755 756**Parameters** 757 758| Name| Description| 759| -------- | -------- | 760| option | Pointer to the target [OH_PreferencesOption](#oh_preferencesoption) instance.| 761| bundleName | Pointer to the bundle name to set.| 762 763**Returns** 764 765Returns the error code. 766 767Returns **PREFERENCES_OK** if the operation is successful. 768 769Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 770 771**See** 772 773[OH_PreferencesOption](#oh_preferencesoption) 774 775[OH_Preferences_ErrCode](#oh_preferences_errcode) 776 777 778### OH_PreferencesOption_SetDataGroupId() 779 780``` 781int OH_PreferencesOption_SetDataGroupId (OH_PreferencesOption *option, const char *dataGroupId ) 782``` 783 784**Description** 785 786Sets the application group ID for an [OH_PreferencesOption](#oh_preferencesoption) instance. 787 788After the application group ID is set, the **Preferences** instance will be created in the sandbox directory of the application group ID. 789 790The application group ID must be obtained from AppGallery. This parameter is not supported currently. 791 792If the application group ID is an empty string, the **Preferences** instance will be created in the sandbox directory of the current application. 793 794**Since**: 13 795 796**Parameters** 797 798| Name| Description| 799| -------- | -------- | 800| option | Pointer to the target [OH_PreferencesOption](#oh_preferencesoption) instance.| 801| dataGroupId | Pointer to the application group ID to set.| 802 803**Returns** 804 805Returns the error code. 806 807Returns **PREFERENCES_OK** if the operation is successful. 808 809Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 810 811**See** 812 813[OH_PreferencesOption](#oh_preferencesoption) 814 815[OH_Preferences_ErrCode](#oh_preferences_errcode) 816 817 818### OH_PreferencesOption_SetFileName() 819 820``` 821int OH_PreferencesOption_SetFileName (OH_PreferencesOption *option, const char *fileName ) 822``` 823 824**Description** 825 826Sets the file name for an [OH_PreferencesOption](#oh_preferencesoption) instance. 827 828**Since**: 13 829 830**Parameters** 831 832| Name| Description| 833| -------- | -------- | 834| option | Pointer to the target [OH_PreferencesOption](#oh_preferencesoption) instance.| 835| fileName | Pointer to the file name to set.| 836 837**Returns** 838 839Returns the error code. 840 841Returns **PREFERENCES_OK** if the operation is successful. 842 843Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 844 845**See** 846 847[OH_PreferencesOption](#oh_preferencesoption) 848 849[OH_Preferences_ErrCode](#oh_preferences_errcode) 850 851 852### OH_PreferencesPair_GetKey() 853 854``` 855const char* OH_PreferencesPair_GetKey (const OH_PreferencesPair *pairs, uint32_t index ) 856``` 857 858**Description** 859 860Obtains the key based on the specified index from the KV data. 861 862**Since**: 13 863 864**Parameters** 865 866| Name| Description| 867| -------- | -------- | 868| pairs | Pointer to the target [OH_PreferencesPair](#oh_preferencespair).| 869| index | Index of the target [OH_PreferencesPair](#oh_preferencespair).| 870 871**Returns** 872 873Returns the pointer to the key obtained if the operation is successful. 874 875Returns a null pointer if the operation fails or the input parameter is invalid. 876 877**See** 878 879[OH_PreferencesPair](#oh_preferencespair) 880 881 882### OH_PreferencesPair_GetPreferencesValue() 883 884``` 885const OH_PreferencesValue* OH_PreferencesPair_GetPreferencesValue (const OH_PreferencesPair *pairs, uint32_t index ) 886``` 887 888**Description** 889 890Obtains the value based on the specified index from the KV pairs. 891 892**Since**: 13 893 894**Parameters** 895 896| Name| Description| 897| -------- | -------- | 898| pairs | Pointer to the target [OH_PreferencesPair](#oh_preferencespair).| 899| index | Index of the target [OH_PreferencesPair](#oh_preferencespair).| 900 901**Returns** 902 903Returns the pointer to the value obtained if the operation is successful. 904 905Returns a null pointer if the operation fails or the input parameter is invalid. 906 907**See** 908 909[OH_PreferencesValue](#oh_preferencesvalue) 910 911 912### OH_PreferencesValue_GetBool() 913 914``` 915int OH_PreferencesValue_GetBool (const OH_PreferencesValue *object, bool *value ) 916``` 917 918**Description** 919 920Obtains a Boolean value from an [OH_PreferencesValue](#oh_preferencesvalue) instance. 921 922**Since**: 13 923 924**Parameters** 925 926| Name| Description| 927| -------- | -------- | 928| object | Pointer to the target [OH_PreferencesValue](#oh_preferencesvalue) instance.| 929| value | Pointer to the Boolean value obtained.| 930 931**Returns** 932 933Returns the error code. 934 935Returns **PREFERENCES_OK** if the operation is successful. 936 937Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 938 939Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 940 941Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 942 943**See** 944 945[OH_PreferencesValue](#oh_preferencesvalue) 946 947[OH_Preferences_ErrCode](#oh_preferences_errcode) 948 949 950### OH_PreferencesValue_GetInt() 951 952``` 953int OH_PreferencesValue_GetInt (const OH_PreferencesValue* object, int* value ) 954``` 955 956**Description** 957 958Obtains an integer from an [OH_PreferencesValue](#oh_preferencesvalue) instance. 959 960**Since**: 13 961 962**Parameters** 963 964| Name| Description| 965| -------- | -------- | 966| object | Pointer to the target [OH_PreferencesValue](#oh_preferencesvalue) instance.| 967| value | Pointer to the integer value obtained.| 968 969**Returns** 970 971Returns the error code. 972 973Returns **PREFERENCES_OK** if the operation is successful. 974 975Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 976 977Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 978 979Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 980 981**See** 982 983[OH_PreferencesValue](#oh_preferencesvalue) 984 985[OH_Preferences_ErrCode](#oh_preferences_errcode) 986 987 988### OH_PreferencesValue_GetString() 989 990``` 991int OH_PreferencesValue_GetString (const OH_PreferencesValue *object, char **value, uint32_t *valueLen ) 992``` 993 994**Description** 995 996Obtains a string from an [OH_PreferencesValue](#oh_preferencesvalue) instance. 997 998**Since**: 13 999 1000**Parameters** 1001 1002| Name| Description| 1003| -------- | -------- | 1004| object | Pointer to the target [OH_PreferencesValue](#oh_preferencesvalue) instance.| 1005| value | Double pointer to the string obtained. If the string is not required, you can use [OH_Preferences_FreeString](#oh_preferences_freestring) to free the string (release the memory occupied by the string).| 1006| valueLen | Pointer to the length of the string obtained.| 1007 1008**Returns** 1009 1010Returns the error code. 1011 1012Returns **PREFERENCES_OK** if the operation is successful. 1013 1014Returns **PREFERENCES_ERROR_INVALID_PARAM** if invalid parameters are detected. 1015 1016Returns **PREFERENCES_ERROR_STORAGE** if the storage is abnormal. 1017 1018Returns **PREFERENCES_ERROR_MALLOC** if memory allocation fails. 1019 1020**See** 1021 1022[OH_PreferencesValue](#oh_preferencesvalue) 1023 1024[OH_Preferences_ErrCode](#oh_preferences_errcode) 1025 1026 1027### OH_PreferencesValue_GetValueType() 1028 1029``` 1030Preference_ValueType OH_PreferencesValue_GetValueType (const OH_PreferencesValue *object) 1031``` 1032 1033**Description** 1034 1035Obtains the data type of a **PreferencesValue** instance. 1036 1037**Since**: 13 1038 1039**Parameters** 1040 1041| Name| Description| 1042| -------- | -------- | 1043| object | Pointer to the target [OH_PreferencesValue](#oh_preferencesvalue) instance.| 1044 1045**Returns** 1046 1047Returns the obtained data type. If **PREFERENCE_TYPE_NULL** is returned, invalid parameter is passed in. 1048 1049**See** 1050 1051[OH_PreferencesValue](#oh_preferencesvalue) 1052