1# oh_preferences.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对象的接口与数据结构。 12 13**引用文件：** <database/preferences/oh_preferences.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_Preferences](capi-preferences-oh-preferences.md) | OH_Preferences | 定义Preferences对象类型。 | 30 31### 函数 32 33| 名称 | typedef关键字 | 描述 | 34| ------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------ | 35| [typedef void (\*OH_PreferencesDataObserver)(void *context, const OH_PreferencesPair *pairs, uint32_t count)](#oh_preferencesdataobserver) | OH_PreferencesDataObserver | 定义数据变更触发的回调函数类型。 | 36| [OH_Preferences *OH_Preferences_Open(OH_PreferencesOption *option, int *errCode)](#oh_preferences_open) | - | 打开一个Preferences实例对象并创建指向它的指针。<br>当不再需要使用指针时，请使用[OH_Preferences_Close](capi-oh-preferences-h.md#oh_preferences_close)关闭实例对象。 | 37| [int OH_Preferences_Close(OH_Preferences *preference)](#oh_preferences_close) | - | 关闭一个Preferences实例对象。 | 38| [int OH_Preferences_GetInt(OH_Preferences *preference, const char *key, int *value)](#oh_preferences_getint) | - | 获取Preferences实例对象中Key对应的整型值。 | 39| [int OH_Preferences_GetBool(OH_Preferences *preference, const char *key, bool *value)](#oh_preferences_getbool) | - | 获取Preferences实例对象中Key对应的布尔值。 | 40| [int OH_Preferences_GetString(OH_Preferences *preference, const char *key, char **value, uint32_t *valueLen)](#oh_preferences_getstring) | - | 获取Preferences实例对象中Key对应的字符串。 | 41| [void OH_Preferences_FreeString(char *string)](#oh_preferences_freestring) | - | 释放从Preferences实例对象中获取的字符串。 | 42| [int OH_Preferences_SetInt(OH_Preferences *preference, const char *key, int value)](#oh_preferences_setint) | - | 根据Key设置Preferences实例对象中的整型值。 | 43| [int OH_Preferences_SetBool(OH_Preferences *preference, const char *key, bool value)](#oh_preferences_setbool) | - | 根据Key设置Preferences实例对象中的布尔值。 | 44| [int OH_Preferences_SetString(OH_Preferences *preference, const char *key, const char *value)](#oh_preferences_setstring) | - | 根据Key设置Preferences实例对象中的字符串。 | 45| [int OH_Preferences_Delete(OH_Preferences *preference, const char *key)](#oh_preferences_delete) | - | 在Preferences实例对象中删除Key对应的KV数据。 | 46| [int OH_Preferences_RegisterDataObserver(OH_Preferences *preference, void *context,OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount)](#oh_preferences_registerdataobserver) | - | 对选取的Key注册数据变更订阅。订阅的Key的值发生变更后，在调用OH_Preferences_Close()后触发回调。 | 47| [int OH_Preferences_UnregisterDataObserver(OH_Preferences *preference, void *context,OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount)](#oh_preferences_unregisterdataobserver) | - | 取消注册选取Key的数据变更订阅。 | 48| [int OH_Preferences_IsStorageTypeSupported(Preferences_StorageType type, bool *isSupported)](#oh_preferences_isstoragetypesupported) | - | 校验当前平台是否支持对应存储模式。 | 49 50## 函数说明 51 52### OH_PreferencesDataObserver() 53 54``` 55typedef void (*OH_PreferencesDataObserver)(void *context, const OH_PreferencesPair *pairs, uint32_t count) 56``` 57 58**描述** 59 60定义数据变更触发的回调函数类型。 61 62**起始版本：** 13 63 64 65**参数：** 66 67| 参数项 | 描述 | 68| ------------------------------------------------------------ | ------------------------ | 69| void *context | 应用上下文的指针。 | 70| const [OH_PreferencesPair](capi-preferences-oh-preferencespair.md) *pairs | 发生变更的KV数据的指针。 | 71| uint32_t count | 发生变更的KV数据的数量。 | 72 73### OH_Preferences_Open() 74 75``` 76OH_Preferences *OH_Preferences_Open(OH_PreferencesOption *option, int *errCode) 77``` 78 79**描述** 80 81打开一个Preferences实例对象并创建指向它的指针。<br>当不再需要使用指针时，请使用[OH_Preferences_Close](capi-oh-preferences-h.md#oh_preferences_close)关闭实例对象。 82 83**起始版本：** 13 84 85 86**参数：** 87 88| 参数项 | 描述 | 89| ------------------------------------------------------------ | ------------------------------------------------------------ | 90| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) *option | 指向Preferences配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)的指针。 | 91| int *errCode | 该参数作为出参使用，表示指向返回错误码的指针，详见[OH_Preferences_ErrCode](capi-oh-preferences-err-code-h.md#oh_preferences_errcode)。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_NOT_SUPPORTED，表示系统能力不支持。<br>若错误码为PREFERENCES_ERROR_DELETE_FILE，表示删除文件失败。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 | 92 93**返回：** 94 95| 类型 | 说明 | 96| ---------------------------------------- | ------------------------------------------------------------ | 97| [OH_Preferences](capi-preferences-oh-preferences.md) | 当操作成功时，返回指向打开的Preferences对象[OH_Preferences](capi-preferences-oh-preferences.md)实例对象的指针，失败返回空指针。 | 98 99### OH_Preferences_Close() 100 101``` 102int OH_Preferences_Close(OH_Preferences *preference) 103``` 104 105**描述** 106 107关闭一个Preferences实例对象。 108 109**起始版本：** 13 110 111 112**参数：** 113 114| 参数项 | 描述 | 115| ---------------------------------------------------- | ------------------------------------------------------------ | 116| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | 指向需要关闭的Preferences[OH_Preferences](capi-preferences-oh-preferences.md)实例对象的指针。 | 117 118**返回：** 119 120| 类型 | 说明 | 121| ---- | ------------------------------------------------------------ | 122| int | 返回执行的错误码，详见[OH_Preferences_ErrCode](capi-oh-preferences-err-code-h.md#oh_preferences_errcode)。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 | 123 124### OH_Preferences_GetInt() 125 126``` 127int OH_Preferences_GetInt(OH_Preferences *preference, const char *key, int *value) 128``` 129 130**描述** 131 132获取Preferences实例对象中Key对应的整型值。 133 134**起始版本：** 13 135 136 137**参数：** 138 139| 参数项 | 描述 | 140| ---------------------------------------------------- | ------------------------------------------------------------ | 141| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | 指向目标Preferences[OH_Preferences](capi-preferences-oh-preferences.md)实例对象的指针。 | 142| const char *key | 需要获取的Key的指针。 | 143| int *value | 该参数作为出参使用，表示指向获取到的整型值的指针。 | 144 145**返回：** 146 147| 类型 | 说明 | 148| ---- | ------------------------------------------------------------ | 149| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。<br>若错误码为PREFERENCES_ERROR_KEY_NOT_FOUND，表示查询的Key不存在。 | 150 151### OH_Preferences_GetBool() 152 153``` 154int OH_Preferences_GetBool(OH_Preferences *preference, const char *key, bool *value) 155``` 156 157**描述** 158 159获取Preferences实例对象中Key对应的布尔值。 160 161**起始版本：** 13 162 163 164**参数：** 165 166| 参数项 | 描述 | 167| ---------------------------------------------------- | ------------------------------------------------------------ | 168| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | 指向目标Preferences[OH_Preferences](capi-preferences-oh-preferences.md)实例对象的指针。 | 169| const char *key | 需要获取的Key的指针。 | 170| bool *value | 该参数作为出参使用，表示指向获取到的布尔值的指针。 | 171 172**返回：** 173 174| 类型 | 说明 | 175| ---- | ------------------------------------------------------------ | 176| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。<br>若错误码为PREFERENCES_ERROR_KEY_NOT_FOUND，表示查询的key不存在。 | 177 178### OH_Preferences_GetString() 179 180``` 181int OH_Preferences_GetString(OH_Preferences *preference, const char *key, char **value, uint32_t *valueLen) 182``` 183 184**描述** 185 186获取Preferences实例对象中Key对应的字符串。 187 188**起始版本：** 13 189 190 191**参数：** 192 193| 参数项 | 描述 | 194| ---------------------------------------------------- | ------------------------------------------------------------ | 195| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | 指向目标Preferences[OH_Preferences](capi-preferences-oh-preferences.md)实例对象的指针。 | 196| const char *key | 需要获取的Key的指针。 | 197| char **value | 该参数作为出参使用，表示指向获取到的字符串的二级指针，使用完毕后需要调用释放函数[OH_Preferences_FreeString](capi-oh-preferences-h.md#oh_preferences_freestring)释放内存。 | 198| uint32_t *valueLen | 该参数作为出参使用，表示获取到的字符串长度的指针。 | 199 200**返回：** 201 202| 类型 | 说明 | 203| ---- | ------------------------------------------------------------ | 204| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。<br>若错误码为PREFERENCES_ERROR_KEY_NOT_FOUND，表示查询的Key不存在。 | 205 206### OH_Preferences_FreeString() 207 208``` 209void OH_Preferences_FreeString(char *string) 210``` 211 212**描述** 213 214释放从Preferences实例对象中获取的字符串。 215 216**起始版本：** 13 217 218 219**参数：** 220 221| 参数项 | 描述 | 222| ------------ | ---------------------- | 223| char *string | 需要释放的字符串指针。 | 224 225### OH_Preferences_SetInt() 226 227``` 228int OH_Preferences_SetInt(OH_Preferences *preference, const char *key, int value) 229``` 230 231**描述** 232 233根据Key设置Preferences实例对象中的整型值。 234 235**起始版本：** 13 236 237 238**参数：** 239 240| 参数项 | 描述 | 241| ---------------------------------------------------- | ------------------------------------------------------------ | 242| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | 指向目标Preferences[OH_Preferences](capi-preferences-oh-preferences.md)实例对象的指针。 | 243| const char *key | 指向需要设置的Key的指针。 | 244| int value | 需要设置的整型值。 | 245 246**返回：** 247 248| 类型 | 说明 | 249| ---- | ------------------------------------------------------------ | 250| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 | 251 252### OH_Preferences_SetBool() 253 254``` 255int OH_Preferences_SetBool(OH_Preferences *preference, const char *key, bool value) 256``` 257 258**描述** 259 260根据Key设置Preferences实例对象中的布尔值。 261 262**起始版本：** 13 263 264 265**参数：** 266 267| 参数项 | 描述 | 268| ---------------------------------------------------- | ------------------------------------------------------------ | 269| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | 指向目标Preferences[OH_Preferences](capi-preferences-oh-preferences.md)实例对象的指针。 | 270| const char *key | 指向需要设置的Key的指针。 | 271| bool value | 需要设置的布尔值。 | 272 273**返回：** 274 275| 类型 | 说明 | 276| ---- | ------------------------------------------------------------ | 277| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 | 278 279### OH_Preferences_SetString() 280 281``` 282int OH_Preferences_SetString(OH_Preferences *preference, const char *key, const char *value) 283``` 284 285**描述** 286 287根据Key设置Preferences实例对象中的字符串。 288 289**起始版本：** 13 290 291 292**参数：** 293 294| 参数项 | 描述 | 295| ---------------------------------------------------- | ------------------------------------------------------------ | 296| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | 指向目标Preferences[OH_Preferences](capi-preferences-oh-preferences.md)实例对象的指针。 | 297| const char *key | 指向需要设置的Key的指针。 | 298| const char *value | 指向需要设置的字符串指针。 | 299 300**返回：** 301 302| 类型 | 说明 | 303| ---- | ------------------------------------------------------------ | 304| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 | 305 306### OH_Preferences_Delete() 307 308``` 309int OH_Preferences_Delete(OH_Preferences *preference, const char *key) 310``` 311 312**描述** 313 314在Preferences实例对象中删除Key对应的KV数据。 315 316**起始版本：** 13 317 318 319**参数：** 320 321| 参数项 | 描述 | 322| ---------------------------------------------------- | ------------------------------------------------------------ | 323| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | 指向目标Preferences[OH_Preferences](capi-preferences-oh-preferences.md)实例对象的指针。 | 324| const char *key | 指向需要删除的Key的指针。 | 325 326**返回：** 327 328| 类型 | 说明 | 329| ---- | ------------------------------------------------------------ | 330| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 | 331 332**参考：** 333 334OH_Preferences_ErrCode 335 336### OH_Preferences_RegisterDataObserver() 337 338``` 339int OH_Preferences_RegisterDataObserver(OH_Preferences *preference, void *context,OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount) 340``` 341 342**描述** 343 344对选取的Key注册数据变更订阅。订阅的Key的值发生变更后，在调用OH_Preferences_Close()后触发回调。 345 346**起始版本：** 13 347 348 349**参数：** 350 351| 参数项 | 描述 | 352| ------------------------------------------------------------ | ------------------------------------------------------------ | 353| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | 指向目标Preferences[OH_Preferences](capi-preferences-oh-preferences.md)实例对象的指针。 | 354| void *context | 应用上下文的指针。 | 355| [OH_PreferencesDataObserver](#oh_preferencesdataobserver) observer | 订阅数据变更关联的回调函数[OH_PreferencesDataObserver](capi-oh-preferences-h.md#oh_preferencesdataobserver)。 | 356| const char *keys[] | 需要订阅的Key数组。 | 357| uint32_t keyCount | 需要订阅的Key的数量。 | 358 359**返回：** 360 361| 类型 | 说明 | 362| ---- | ------------------------------------------------------------ | 363| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。<br>若错误码为PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT，表示获取数据变更订阅服务失败。 | 364 365### OH_Preferences_UnregisterDataObserver() 366 367``` 368int OH_Preferences_UnregisterDataObserver(OH_Preferences *preference, void *context,OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount) 369``` 370 371**描述** 372 373取消注册选取Key的数据变更订阅。 374 375**起始版本：** 13 376 377 378**参数：** 379 380| 参数项 | 描述 | 381| ------------------------------------------------------------ | ------------------------------------------------------------ | 382| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | 指向目标Preferences[OH_Preferences](capi-preferences-oh-preferences.md)实例对象的指针。 | 383| void *context | 应用上下文的指针。 | 384| [OH_PreferencesDataObserver](#oh_preferencesdataobserver) observer | 订阅数据变更关联的回调函数[OH_PreferencesDataObserver](capi-oh-preferences-h.md#oh_preferencesdataobserver)。 | 385| const char *keys[] | 需要取消订阅的Key数组。 | 386| uint32_t keyCount | 需要取消订阅的Key的数量。 | 387 388**返回：** 389 390| 类型 | 说明 | 391| ---- | ------------------------------------------------------------ | 392| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。<br>若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。<br>若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 | 393 394**参考：** 395 396OH_Preferences_ErrCode 397 398### OH_Preferences_IsStorageTypeSupported() 399 400``` 401int OH_Preferences_IsStorageTypeSupported(Preferences_StorageType type, bool *isSupported) 402``` 403 404 405**起始版本：** 18 406 407 408**参数：** 409 410| 参数项 | 描述 | 411| ------------------------------------------------------------ | ------------------------------------------------------------ | 412| [Preferences_StorageType](capi-oh-preferences-option-h.md#preferences_storagetype) type | 要校验是否支持的存储模式。 | 413| bool *isSupported | 校验结果的指针，作为出参使用。true表示当前平台支持当前校验的存储模式，false表示当前平台不支持当前校验的存储模式。 | 414 415**返回：** 416 417| 类型 | 说明 | 418| ---- | ------------------------------------------------------------ | 419| int | 返回接口操作执行的状态码。<br>PREFERENCES_OK，表示操作成功。<br>PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 | 420 421