1# oh_preferences_value.h 2<!--Kit: ArkData--> 3<!--Subsystem: DistributedDataManager--> 4<!--Owner: @yanhuii--> 5<!--Designer: @houpengtao1--> 6<!--Tester: @yippo; @logic42--> 7<!--Adviser: @ge-yafang--> 8 9## 概述 10 11提供访问Preferences值（PreferencesValue）对象的接口、枚举类型与数据结构。 12 13**引用文件：** <database/preferences/oh_preferences_value.h> 14 15**库：** libohpreferences.so 16 17**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 18 19**起始版本：** 13 20 21**相关模块：** [Preferences](capi-preferences.md) 22 23## 汇总 24 25### 结构体 26 27| 名称 | typedef关键字 | 描述 | 28| -------------------------------------------------- | ------------------- | ------------------------------------- | 29| [OH_PreferencesPair](capi-preferences-oh-preferencespair.md) | OH_PreferencesPair | 定义Preferences使用的KV数据对象类型。 | 30| [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) | OH_PreferencesValue | 定义PreferencesValue对象类型。 | 31 32### 枚举 33 34| 名称 | typedef关键字 | 描述 | 35| --------------------------------------------- | -------------------- | -------------------------------- | 36| [Preference_ValueType](#preference_valuetype) | Preference_ValueType | 定义PreferencesValue的数据类型。 | 37 38### 函数 39 40| 名称 | 描述 | 41| ------------------------------------------------------------ | ------------------------------------------------------------ | 42| [const char *OH_PreferencesPair_GetKey(const OH_PreferencesPair *pairs, uint32_t index)](#oh_preferencespair_getkey) | 获取KV数据中索引对应数据的键。 | 43| [const OH_PreferencesValue *OH_PreferencesPair_GetPreferencesValue(const OH_PreferencesPair *pairs, uint32_t index)](#oh_preferencespair_getpreferencesvalue) | 获取KV数据数组中索引对应的值。 | 44| [Preference_ValueType OH_PreferencesValue_GetValueType(const OH_PreferencesValue *object)](#oh_preferencesvalue_getvaluetype) | 获取PreferencesValue对象的数据类型。 | 45| [int OH_PreferencesValue_GetInt(const OH_PreferencesValue *object, int *value)](#oh_preferencesvalue_getint) | 从PreferencesValue对象[OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md)中获取一个整型值。 | 46| [int OH_PreferencesValue_GetBool(const OH_PreferencesValue *object, bool *value)](#oh_preferencesvalue_getbool) | 从PreferencesValue对象[OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md)中获取一个布尔值。 | 47| [int OH_PreferencesValue_GetString(const OH_PreferencesValue *object, char **value, uint32_t *valueLen)](#oh_preferencesvalue_getstring) | 从PreferencesValue对象[OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md)中获取字符串。 | 48 49## 枚举类型说明 50 51### Preference_ValueType 52 53``` 54enum Preference_ValueType 55``` 56 57**描述** 58 59定义PreferencesValue的数据类型。 60 61**起始版本：** 13 62 63| 枚举项 | 描述 | 64| ------------------------ | ------------ | 65| PREFERENCE_TYPE_NULL = 0 | 空类型。 | 66| PREFERENCE_TYPE_INT | 整型类型。 | 67| PREFERENCE_TYPE_BOOL | 布尔类型。 | 68| PREFERENCE_TYPE_STRING | 字符串类型。 | 69| PREFERENCE_TYPE_BUTT | 结束类型。 | 70 71 72## 函数说明 73 74### OH_PreferencesPair_GetKey() 75 76``` 77const char *OH_PreferencesPair_GetKey(const OH_PreferencesPair *pairs, uint32_t index) 78``` 79 80**描述** 81 82获取KV数据中索引对应数据的键。 83 84**起始版本：** 13 85 86 87**参数：** 88 89| 参数项 | 描述 | 90| ------------------------------------------------------------ | ------------------------------------------------------------ | 91| const [OH_PreferencesPair](capi-preferences-oh-preferencespair.md) *pairs | 目标KV数据[OH_PreferencesPair](capi-preferences-oh-preferencespair.md)的指针。 | 92| uint32_t index | 目标KV数据[OH_PreferencesPair](capi-preferences-oh-preferencespair.md)的索引值。 | 93 94**返回：** 95 96| 类型 | 说明 | 97| ------------ | ------------------------------------------------------------ | 98| const char * | 如果操作成功，返回获取到的键的指针。操作失败或传参不合法返回空指针。 | 99 100### OH_PreferencesPair_GetPreferencesValue() 101 102``` 103const OH_PreferencesValue *OH_PreferencesPair_GetPreferencesValue(const OH_PreferencesPair *pairs, uint32_t index) 104``` 105 106**描述** 107 108获取KV数据数组中索引对应的值。 109 110**起始版本：** 13 111 112 113**参数：** 114 115| 参数项 | 描述 | 116| ------------------------------------------------------------ | ------------------------------------------------------------ | 117| const [OH_PreferencesPair](capi-preferences-oh-preferencespair.md) *pairs | 目标KV数据[OH_PreferencesPair](capi-preferences-oh-preferencespair.md)的指针。 | 118| uint32_t index | 目标KV数据[OH_PreferencesPair](capi-preferences-oh-preferencespair.md)的索引值。 | 119 120**返回：** 121 122| 类型 | 说明 | 123| -------------------------------------------------------- | ------------------------------------------------------------ | 124| const [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) | 如果操作成功，返回获取到的值对象的指针。操作失败或传参不合法返回空指针。 | 125 126 127### OH_PreferencesValue_GetValueType() 128 129``` 130Preference_ValueType OH_PreferencesValue_GetValueType(const OH_PreferencesValue *object) 131``` 132 133**描述** 134 135获取PreferencesValue对象的数据类型。 136 137**起始版本：** 13 138 139 140**参数：** 141 142| 参数项 | 描述 | 143| ------------------------------------------------------------ | ------------------------------------------------------------ | 144| const [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) *object | 对象[OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md)的指针。 | 145 146**返回：** 147 148| 类型 | 说明 | 149| --------------------------------------------- | ------------------------------------------------------------ | 150| [Preference_ValueType](#preference_valuetype) | 返回获取到的数据类型枚举。若返回数据类型枚举为PREFERENCE_TYPE_NULL，代表传参不合法。 | 151 152### OH_PreferencesValue_GetInt() 153 154``` 155int OH_PreferencesValue_GetInt(const OH_PreferencesValue *object, int *value) 156``` 157 158**描述** 159 160从PreferencesValue对象[OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md)中获取一个整型值。 161 162**起始版本：** 13 163 164 165**参数：** 166 167| 参数项 | 描述 | 168| ------------------------------------------------------------ | ------------------------------------------------------------ | 169| const [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) *object | 对象[OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md)的指针。 | 170| int *value | 该参数作为出参使用，表示指向获取到的整型值的指针。 | 171 172**返回：** 173 174| 类型 | 说明 | 175| ---- | ------------------------------------------------------------ | 176| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 | 177 178### OH_PreferencesValue_GetBool() 179 180``` 181int OH_PreferencesValue_GetBool(const OH_PreferencesValue *object, bool *value) 182``` 183 184**描述** 185 186从PreferencesValue对象[OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md)中获取一个布尔值。 187 188**起始版本：** 13 189 190 191**参数：** 192 193| 参数项 | 描述 | 194| ------------------------------------------------------------ | ------------------------------------------------------------ | 195| const [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) *object | 对象[OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md)的指针。 | 196| bool *value | 该参数作为出参使用，表示指向获取到的布尔值的指针。 | 197 198**返回：** 199 200| 类型 | 说明 | 201| ---- | ------------------------------------------------------------ | 202| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 | 203 204### OH_PreferencesValue_GetString() 205 206``` 207int OH_PreferencesValue_GetString(const OH_PreferencesValue *object, char **value, uint32_t *valueLen) 208``` 209 210**描述** 211 212从PreferencesValue对象[OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md)中获取字符串。 213 214**起始版本：** 13 215 216 217**参数：** 218 219| 参数项 | 描述 | 220| ------------------------------------------------------------ | ------------------------------------------------------------ | 221| const [OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md) *object | 对象[OH_PreferencesValue](capi-preferences-oh-preferencesvalue.md)的指针。 | 222| char **value | 该参数作为出参使用，表示指向获取到的字符串的二级指针，使用完毕后需要调用释放函数[OH_Preferences_FreeString](capi-oh-preferences-h.md#oh_preferences_freestring)释放内存。 | 223| uint32_t *valueLen | 该参数作为出参使用，表示指向获取到的字符串长度的指针。 | 224 225**返回：** 226 227| 类型 | 说明 | 228| ---- | ------------------------------------------------------------ | 229| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 | 230 231 232 233