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