1# oh_preferences_value.h 2 3## Overview 4 5Provides APIs, enums, and structs for accessing the **PreferencesValue** object. 6 7**File to include**: <database/preferences/oh_preferences_value.h> 8 9**Library**: libohpreferences.so 10 11**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 12 13**Since**: 13 14 15**Related module**: [Preferences](capi-preferences.md) 16 17## Summary 18 19### Structs 20 21| Name | typedef Keyword | Description | 22| -------------------------------------------------- | ------------------- | ------------------------------------- | 23| [OH_PreferencesPair](capi-preferences-oh-preferencespair.md) | OH_PreferencesPair | Defines a struct for the **Preferences** data in KV format.| 24| [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) | OH_PreferencesValue | Defines a struct for the **PreferencesValue** object. | 25 26### Enums 27 28| Name | typedef Keyword | Description | 29| --------------------------------------------- | -------------------- | -------------------------------- | 30| [Preference_ValueType](#preference_valuetype) | Preference_ValueType | Enumerates the data types of **PreferencesValue**.| 31 32### Functions 33 34| Name | Description | 35| ------------------------------------------------------------ | ------------------------------------------------------------ | 36| [const char *OH_PreferencesPair_GetKey(const OH_PreferencesPair *pairs, uint32_t index)](#oh_preferencespair_getkey) | Obtains the key based on the specified index from the KV data. | 37| [const OH_PreferencesValue *OH_PreferencesPair_GetPreferencesValue(const OH_PreferencesPair *pairs, uint32_t index)](#oh_preferencespair_getpreferencesvalue) | Obtains the value based on the specified index from the KV pairs. | 38| [Preference_ValueType OH_PreferencesValue_GetValueType(const OH_PreferencesValue *object)](#oh_preferencesvalue_getvaluetype) | Obtains the data type of an **OH_PreferencesValue** instance. | 39| [int OH_PreferencesValue_GetInt(const OH_PreferencesValue *object, int *value)](#oh_preferencesvalue_getint) | Obtains an integer from an [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) instance.| 40| [int OH_PreferencesValue_GetBool(const OH_PreferencesValue *object, bool *value)](#oh_preferencesvalue_getbool) | Obtains a Boolean value from an [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) instance.| 41| [int OH_PreferencesValue_GetString(const OH_PreferencesValue *object, char **value, uint32_t *valueLen)](#oh_preferencesvalue_getstring) | Obtains a string from an [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) instance.| 42 43## Enum Description 44 45### Preference_ValueType 46 47``` 48enum Preference_ValueType 49``` 50 51**Description** 52 53Enumerates the data types of **PreferencesValue**. 54 55**Since**: 13 56 57| Enum Item | Description | 58| ------------------------ | ------------ | 59| PREFERENCE_TYPE_NULL = 0 | Null. | 60| PREFERENCE_TYPE_INT | Integer. | 61| PREFERENCE_TYPE_BOOL | Boolean. | 62| PREFERENCE_TYPE_STRING | String.| 63| PREFERENCE_TYPE_BUTT | End type. | 64 65 66## Function Description 67 68### OH_PreferencesPair_GetKey() 69 70``` 71const char *OH_PreferencesPair_GetKey(const OH_PreferencesPair *pairs, uint32_t index) 72``` 73 74**Description** 75 76Obtains the key based on the specified index from the KV data. 77 78**Since**: 13 79 80 81**Parameters** 82 83| Name | Description | 84| ------------------------------------------------------------ | ------------------------------------------------------------ | 85| const [OH_PreferencesPair](capi-preferences-oh-preferencespair.md) *pairs | Pointer to the target [OH_PreferencesPair](capi-preferences-oh-preferencespair.md).| 86| uint32_t index | Index of the target [OH_PreferencesPair](capi-preferences-oh-preferencespair.md).| 87 88**Returns** 89 90| Type | Description | 91| ------------ | ------------------------------------------------------------ | 92| const char * | Returns the pointer to the key obtained if the operation is successful; returns a null pointer if the operation fails or invalid parameters are specified.| 93 94### OH_PreferencesPair_GetPreferencesValue() 95 96``` 97const OH_PreferencesValue *OH_PreferencesPair_GetPreferencesValue(const OH_PreferencesPair *pairs, uint32_t index) 98``` 99 100**Description** 101 102Obtains the value based on the specified index from the KV pairs. 103 104**Since**: 13 105 106 107**Parameters** 108 109| Name | Description | 110| ------------------------------------------------------------ | ------------------------------------------------------------ | 111| const [OH_PreferencesPair](capi-preferences-oh-preferencespair.md) *pairs | Pointer to the target [OH_PreferencesPair](capi-preferences-oh-preferencespair.md).| 112| uint32_t index | Index of the target [OH_PreferencesPair](capi-preferences-oh-preferencespair.md).| 113 114**Returns** 115 116| Type | Description | 117| ------------------------------------------------------------ | ------------------------------------------------------------ | 118| const [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) | Returns the pointer to the value obtained if the operation is successful; returns a null pointer if the operation fails or invalid parameters are specified. | 119 120 121### OH_PreferencesValue_GetValueType() 122 123``` 124Preference_ValueType OH_PreferencesValue_GetValueType(const OH_PreferencesValue *object) 125``` 126 127**Description** 128 129Obtains the data type of a **PreferencesValue** instance. 130 131**Since**: 13 132 133 134**Parameters** 135 136| Name | Description | 137| ------------------------------------------------------------ | ------------------------------------------------------------ | 138| const [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) *object | Pointer to the [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) instance.| 139 140**Returns** 141 142| Type | Description | 143| --------------------------------------------- | ------------------------------------------------------------ | 144| [Preference_ValueType](#preference_valuetype) | Returns the obtained data type. If **PREFERENCE_TYPE_NULL** is returned, invalid parameters are passed in.| 145 146### OH_PreferencesValue_GetInt() 147 148``` 149int OH_PreferencesValue_GetInt(const OH_PreferencesValue *object, int *value) 150``` 151 152**Description** 153 154Obtains an integer from an [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) instance. 155 156**Since**: 13 157 158 159**Parameters** 160 161| Name | Description | 162| ------------------------------------------------------------ | ------------------------------------------------------------ | 163| const [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) *object | Pointer to the [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) instance.| 164| int *value | Pointer to the integer value obtained. | 165 166**Returns** 167 168| Type| Description | 169| ---- | ------------------------------------------------------------ | 170| int | Returns an error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.| 171 172### OH_PreferencesValue_GetBool() 173 174``` 175int OH_PreferencesValue_GetBool(const OH_PreferencesValue *object, bool *value) 176``` 177 178**Description** 179 180Obtains a Boolean value from an [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) instance. 181 182**Since**: 13 183 184 185**Parameters** 186 187| Name | Description | 188| ------------------------------------------------------------ | ------------------------------------------------------------ | 189| const [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) *object | Pointer to the [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) instance.| 190| bool *value | Pointer to the Boolean value obtained. | 191 192**Returns** 193 194| Type| Description | 195| ---- | ------------------------------------------------------------ | 196| int | Returns an error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.| 197 198### OH_PreferencesValue_GetString() 199 200``` 201int OH_PreferencesValue_GetString(const OH_PreferencesValue *object, char **value, uint32_t *valueLen) 202``` 203 204**Description** 205 206Obtains a string from an [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) instance. 207 208**Since**: 13 209 210 211**Parameters** 212 213| Name | Description | 214| ------------------------------------------------------------ | ------------------------------------------------------------ | 215| const [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) *object | Pointer to the [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) instance.| 216| char **value | Double pointer to the string obtained. If the string is not required, you can use [OH_Preferences_FreeString](capi-oh-preferences-h.md#oh_preferences_freestring) to free the string (release the memory occupied by the string).| 217| uint32_t *valueLen | Pointer to the length of the string obtained. | 218 219**Returns** 220 221| Type| Description | 222| ---- | ------------------------------------------------------------ | 223| int | Returns an error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.| 224