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