1# Preferences 2 3 4## 概述 5 6首选项模块（Preferences）提供Key-Value键值型数据（后续简称KV数据）的处理接口，实现对轻量级KV数据的查询、修改和持久化功能。 7 8**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 9 10**起始版本：** 13 11 12 13## 汇总 14 15 16### 文件 17 18| 名称 | 描述 | 19| -------- | -------- | 20| [oh_preferences.h](oh__preferences_8h.md) | 提供访问Preferences对象的接口与数据结构。 | 21| [oh_preferences_err_code.h](oh__preferences__err__code_8h.md) | 声明首选项模块统一使用的错误码信息。 | 22| [oh_preferences_option.h](oh__preferences__option_8h.md) | 提供访问Preferences配置选项（PreferencesOption）的接口与数据结构。 | 23| [oh_preferences_value.h](oh__preferences__value_8h.md) | 提供访问Preferences值（PreferencesValue）对象的接口、枚举类型与数据结构。 | 24 25 26### 类型定义 27 28| 名称 | 描述 | 29| -------- | -------- | 30| typedef struct [OH_Preferences](#oh_preferences) [OH_Preferences](#oh_preferences) | 定义Preferences对象类型。 | 31| typedef void(\* [OH_PreferencesDataObserver](#oh_preferencesdataobserver)) (void \*context, const [OH_PreferencesPair](#oh_preferencespair) \*pairs, uint32_t count) | 定义数据变更触发的回调函数类型。 | 32| typedef enum [OH_Preferences_ErrCode](#oh_preferences_errcode) [OH_Preferences_ErrCode](#oh_preferences_errcode) | 错误码信息。 | 33| typedef struct [OH_PreferencesOption](#oh_preferencesoption) [OH_PreferencesOption](#oh_preferencesoption) | 定义Preferences配置选项的数据结构。 | 34| typedef enum [Preference_ValueType](#preference_valuetype) [Preference_ValueType](#preference_valuetype) | 定义PreferencesValue的数据类型。 | 35| typedef struct [OH_PreferencesPair](#oh_preferencespair) [OH_PreferencesPair](#oh_preferencespair) | 定义Preferences使用的KV数据对象类型。 | 36| typedef struct [OH_PreferencesValue](#oh_preferencesvalue) [OH_PreferencesValue](#oh_preferencesvalue) | 定义PreferencesValue对象类型。 | 37| typedef enum [Preferences_StorageType](#preferences_storagetype) [Preferences_StorageType](#preferences_storagetype) | 首选项配置选项的存储模式枚举。 | 38 39 40### 枚举 41 42| 名称 | 描述 | 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/>} | 错误码信息。 | 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/>} | 定义PreferencesValue的数据类型。 | 46| [Preferences_StorageType](#preferences_storagetype-1) { PREFERENCES_STORAGE_XML = 0, PREFERENCES_STORAGE_GSKV } | 首选项配置选项的存储模式枚举。 | 47 48### 函数 49 50| 名称 | 描述 | 51| -------- | -------- | 52| int [OH_PreferencesOption_SetStorageType](#oh_preferencesoption_setstoragetype) ([OH_PreferencesOption](#oh_preferencesoption) \*option, [Preferences_StorageType](#preferences_storagetype) type) | 设置Preferences实例对象的存储模式。 | 53| int [OH_Preferences_IsStorageTypeSupported](#oh_preferences_isstoragetypesupported) ([Preferences_StorageType](#preferences_storagetype) type, bool \*isSupported) | 校验当前平台是否支持对应存储模式。 | 54| [OH_Preferences](#oh_preferences) \* [OH_Preferences_Open](#oh_preferences_open) ([OH_PreferencesOption](#oh_preferencesoption) \*option, int \*errCode) | 打开一个Preferences实例对象并创建指向它的指针。 当不再需要使用指针时，请使用[OH_Preferences_Close](#oh_preferences_close)关闭实例对象。 | 55| int [OH_Preferences_Close](#oh_preferences_close) ([OH_Preferences](#oh_preferences) \*preference) | 关闭一个Preferences实例对象。 | 56| int [OH_Preferences_GetInt](#oh_preferences_getint) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, int \*value) | 获取Preferences实例对象中Key对应的整型值。 | 57| int [OH_Preferences_GetBool](#oh_preferences_getbool) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, bool \*value) | 获取Preferences实例对象中Key对应的布尔值。 | 58| int [OH_Preferences_GetString](#oh_preferences_getstring) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, char \*\*value, uint32_t \*valueLen) | 获取Preferences实例对象中Key对应的字符串。 | 59| void [OH_Preferences_FreeString](#oh_preferences_freestring) (char \*string) | 释放从Preferences实例对象中获取的字符串。 | 60| int [OH_Preferences_SetInt](#oh_preferences_setint) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, int value) | 根据Key设置Preferences实例对象中的整型值。 | 61| int [OH_Preferences_SetBool](#oh_preferences_setbool) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, bool value) | 根据Key设置Preferences实例对象中的布尔值。 | 62| int [OH_Preferences_SetString](#oh_preferences_setstring) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, const char \*value) | 根据Key设置Preferences实例对象中的字符串。 | 63| int [OH_Preferences_Delete](#oh_preferences_delete) ([OH_Preferences](#oh_preferences) \*preference, const char \*key) | 在Preferences实例对象中删除Key对应的KV数据。 | 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) | 对选取的Key注册数据变更订阅。订阅的Key的值发生变更后，在调用OH_Preferences_Close()后触发回调。 | 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) | 取消注册选取Key的数据变更订阅。 | 66| [OH_PreferencesOption](#oh_preferencesoption) \* [OH_PreferencesOption_Create](#oh_preferencesoption_create) (void) | 创建一个Preferences配置选项的[OH_PreferencesOption](#oh_preferencesoption)实例对象以及指向它的指针。<br>当不再需要使用指针时，请使用[OH_PreferencesOption_Destroy](#oh_preferencesoption_destroy)销毁实例对象，否则会导致内存泄漏。 | 67| int [OH_PreferencesOption_SetFileName](#oh_preferencesoption_setfilename) ([OH_PreferencesOption](#oh_preferencesoption) \*option, const char \*fileName) | 设置Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的文件名称。 | 68| int [OH_PreferencesOption_SetBundleName](#oh_preferencesoption_setbundlename) ([OH_PreferencesOption](#oh_preferencesoption) \*option, const char \*bundleName) | 设置Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的包名称。 | 69| int [OH_PreferencesOption_SetDataGroupId](#oh_preferencesoption_setdatagroupid) ([OH_PreferencesOption](#oh_preferencesoption) \*option, const char \*dataGroupId) | 设置Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的应用组ID。 | 70| int [OH_PreferencesOption_Destroy](#oh_preferencesoption_destroy) ([OH_PreferencesOption](#oh_preferencesoption) \*option) | 销毁Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例。 | 71| const char \* [OH_PreferencesPair_GetKey](#oh_preferencespair_getkey) (const [OH_PreferencesPair](#oh_preferencespair) \*pairs, uint32_t index) | 获取KV数据中索引对应数据的键。 | 72| const [OH_PreferencesValue](#oh_preferencesvalue) \* [OH_PreferencesPair_GetPreferencesValue](#oh_preferencespair_getpreferencesvalue) (const [OH_PreferencesPair](#oh_preferencespair) \*pairs, uint32_t index) | 获取KV数据数组中索引对应的值。 | 73| [Preference_ValueType](#preference_valuetype) [OH_PreferencesValue_GetValueType](#oh_preferencesvalue_getvaluetype) (const [OH_PreferencesValue](#oh_preferencesvalue) \*object) | 获取PreferencesValue对象的数据类型。 | 74| int [OH_PreferencesValue_GetInt](#oh_preferencesvalue_getint) (const [OH_PreferencesValue](#oh_preferencesvalue) \*object, int \*value) | 从PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)中获取一个整型值。 | 75| int [OH_PreferencesValue_GetBool](#oh_preferencesvalue_getbool) (const [OH_PreferencesValue](#oh_preferencesvalue) \*object, bool \*value) | 从PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)中获取一个布尔值。 | 76| int [OH_PreferencesValue_GetString](#oh_preferencesvalue_getstring) (const [OH_PreferencesValue](#oh_preferencesvalue) \*object, char \*\*value, uint32_t \*valueLen) | 从PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)中获取字符串。 | 77 78 79## 类型定义说明 80 81### Preferences_StorageType 82 83``` 84typedef enum Preferences_StorageType Preferences_StorageType 85``` 86 87**描述** 88 89首选项配置选项的存储模式枚举。 90 91**起始版本：** 18 92 93### OH_Preferences 94 95``` 96typedef struct OH_Preferences OH_Preferences 97``` 98 99**描述** 100 101定义Preferences对象类型。 102 103**起始版本：** 13 104 105 106### OH_Preferences_ErrCode 107 108``` 109typedef enum OH_Preferences_ErrCode OH_Preferences_ErrCode 110``` 111 112**描述** 113 114错误码信息。 115 116**起始版本：** 13 117 118 119### OH_PreferencesDataObserver 120 121``` 122typedef void(*OH_PreferencesDataObserver) (void *context, const OH_PreferencesPair *pairs, uint32_t count) 123``` 124 125**描述** 126 127定义数据变更触发的回调函数类型。 128 129**起始版本：** 13 130 131**参数:** 132 133| 名称 | 描述 | 134| -------- | -------- | 135| context | 应用上下文的指针。 | 136| pairs | 发生变更的KV数据的指针。 | 137| count | 发生变更的KV数据的数量。 | 138 139**参见：** 140 141[OH_PreferencesPair](#oh_preferencespair) 142 143 144### OH_PreferencesOption 145 146``` 147typedef struct OH_PreferencesOption OH_PreferencesOption 148``` 149 150**描述** 151 152定义Preferences配置选项的数据结构。 153 154**起始版本：** 13 155 156 157### OH_PreferencesPair 158 159``` 160typedef struct OH_PreferencesPair OH_PreferencesPair 161``` 162 163**描述** 164 165定义Preferences使用的KV数据对象类型。 166 167**起始版本：** 13 168 169 170### OH_PreferencesValue 171 172``` 173typedef struct OH_PreferencesValue OH_PreferencesValue 174``` 175 176**描述** 177 178定义PreferencesValue对象类型。 179 180**起始版本：** 13 181 182 183### Preference_ValueType 184 185``` 186typedef enum Preference_ValueType Preference_ValueType 187``` 188 189**描述** 190 191定义PreferencesValue的数据类型。 192 193**起始版本：** 13 194 195 196## 枚举类型说明 197 198### Preferences_StorageType 199 200``` 201enum Preferences_StorageType 202``` 203 204**描述** 205 206首选项配置选项的存储模式枚举。 207 208**起始版本：** 18 209 210| 枚举值 | 描述 | 211| -------- | -------- | 212| PREFERENCES_STORAGE_XML | XML存储模式，对数据的操作发生在内存中，调用[OH_Preferences_Close](#oh_preferences_close)时落盘，不支持多进程。 | 213| PREFERENCES_STORAGE_GSKV | GSKV存储模式，对数据的操作实时落盘，可支持多进程 | 214 215### OH_Preferences_ErrCode 216 217``` 218enum OH_Preferences_ErrCode 219``` 220 221**描述** 222 223错误码信息。 224 225**起始版本：** 13 226 227| 枚举值 | 描述 | 228| -------- | -------- | 229| PREFERENCES_OK | 操作执行成功。 | 230| PREFERENCES_ERROR_INVALID_PARAM | 参数不合法。 | 231| PREFERENCES_ERROR_NOT_SUPPORTED | 系统能力不支持。 | 232| PREFERENCES_ERROR_BASE | 基准错误码。 | 233| PREFERENCES_ERROR_DELETE_FILE | 删除文件失败。 | 234| PREFERENCES_ERROR_STORAGE | 存储异常。 | 235| PREFERENCES_ERROR_MALLOC | 申请内存失败。 | 236| PREFERENCES_ERROR_KEY_NOT_FOUND | Key不存在。 | 237| PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT | 获取数据变更订阅服务失败。 | 238 239 240### Preference_ValueType 241 242``` 243enum Preference_ValueType 244``` 245 246**描述** 247 248定义PreferencesValue的数据类型。 249 250**起始版本：** 13 251 252| 枚举值 | 描述 | 253| -------- | -------- | 254| PREFERENCE_TYPE_NULL | 空类型。 | 255| PREFERENCE_TYPE_INT | 整型类型。 | 256| PREFERENCE_TYPE_BOOL | 布尔类型。 | 257| PREFERENCE_TYPE_STRING | 字符串类型。 | 258| PREFERENCE_TYPE_BUTT | 结束类型。 | 259 260 261## 函数说明 262 263 264### OH_Preferences_IsStorageTypeSupported() 265 266``` 267int OH_Preferences_IsStorageTypeSupported (Preferences_StorageType type, bool *isSupported ) 268``` 269 270**描述** 271 272校验当前平台是否支持对应存储模式。 273 274**起始版本：** 18 275 276**参数:** 277 278| 名称 | 描述 | 279| -------- | -------- | 280| type | 要校验是否支持的存储模式。 | 281| isSupported | 校验结果的指针，作为出参使用。true表示当前平台支持当前校验的存储模式，false表示当前平台不支持当前校验的存储模式。 | 282 283**返回：** 284 285返回接口操作执行的状态码。 286 287PREFERENCES_OK，表示操作成功。 288 289PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 290 291 292### OH_PreferencesOption_SetStorageType() 293 294``` 295int OH_PreferencesOption_SetStorageType (OH_PreferencesOption *option, Preferences_StorageType type ) 296``` 297 298**描述** 299 300设置Preferences实例对象的存储模式。 301 302**起始版本：** 18 303 304**参数:** 305 306| 名称 | 描述 | 307| -------- | -------- | 308| option | 指向要设置存储模式的配置项的指针。 | 309| type | 需要设置的存储模式。 | 310 311**返回：** 312 313返回执行的错误码。 314 315若错误码为PREFERENCES_OK，表示操作成功。 316 317若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 318 319**参见：** 320 321[OH_PreferencesOption](#oh_preferencesoption). 322 323 324### OH_Preferences_Close() 325 326``` 327int OH_Preferences_Close (OH_Preferences *preference) 328``` 329 330**描述** 331 332关闭一个Preferences实例对象。 333 334**起始版本：** 13 335 336**参数:** 337 338| 名称 | 描述 | 339| -------- | -------- | 340| preference | 指向需要关闭的[OH_Preferences](#oh_preferences)实例对象的指针。 | 341 342**返回：** 343 344返回执行的错误码，详见[OH_Preferences_ErrCode](#oh_preferences_errcode)。 345 346若错误码为PREFERENCES_OK，表示操作成功。 347 348若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 349 350若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 351 352若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 353 354**参见：** 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**描述** 368 369在Preferences实例对象中删除Key对应的KV数据。 370 371**起始版本：** 13 372 373**参数:** 374 375| 名称 | 描述 | 376| -------- | -------- | 377| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 378| key | 指向需要删除的Key的指针。 | 379 380**返回：** 381 382返回执行的错误码。 383 384若错误码为PREFERENCES_OK，表示操作成功。 385 386若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 387 388若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 389 390若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 391 392**参见：** 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**描述** 406 407释放从Preferences实例对象中获取的字符串。 408 409**起始版本：** 13 410 411**参数:** 412 413| 名称 | 描述 | 414| -------- | -------- | 415| string | 需要释放的字符串指针。 | 416 417**参见：** 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**描述** 429 430获取Preferences实例对象中Key对应的布尔值。 431 432**起始版本：** 13 433 434**参数:** 435 436| 名称 | 描述 | 437| -------- | -------- | 438| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 439| key | 需要获取的Key的指针。 | 440| value | 该参数作为出参使用，表示指向获取到的布尔值的指针。 | 441 442**返回：** 443 444返回执行的错误码。 445 446若错误码为PREFERENCES_OK，表示操作成功。 447 448若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 449 450若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 451 452若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 453 454若错误码为PREFERENCES_ERROR_KEY_NOT_FOUND，表示查询的key不存在。 455 456**参见：** 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**描述** 470 471获取Preferences实例对象中Key对应的整型值。 472 473**起始版本：** 13 474 475**参数:** 476 477| 名称 | 描述 | 478| -------- | -------- | 479| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 480| key | 需要获取的Key的指针。 | 481| value | 该参数作为出参使用，表示指向获取到的整型值的指针。 | 482 483**返回：** 484 485返回执行的错误码。 486 487若错误码为PREFERENCES_OK，表示操作成功。 488 489若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 490 491若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 492 493若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 494 495若错误码为PREFERENCES_ERROR_KEY_NOT_FOUND，表示查询的Key不存在。 496 497**参见：** 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**描述** 511 512获取Preferences实例对象中Key对应的字符串。 513 514**起始版本：** 13 515 516**参数:** 517 518| 名称 | 描述 | 519| -------- | -------- | 520| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 521| key | 需要获取的Key的指针。 | 522| value | 该参数作为出参使用，表示指向获取到的字符串的二级指针，使用完毕后需要调用释放函数[OH_Preferences_FreeString](#oh_preferences_freestring)释放内存。 | 523| valueLen | 该参数作为出参使用，表示获取到的字符串长度的指针。 | 524 525**返回：** 526 527返回执行的错误码。 528 529若错误码为PREFERENCES_OK，表示操作成功。 530 531若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 532 533若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 534 535若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 536 537若错误码为PREFERENCES_ERROR_KEY_NOT_FOUND，表示查询的Key不存在。 538 539**参见：** 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**描述** 553 554打开一个Preferences实例对象并创建指向它的指针。 当不再需要使用指针时，请使用[OH_Preferences_Close](#oh_preferences_close)关闭实例对象。 555 556**起始版本：** 13 557 558**参数:** 559 560| 名称 | 描述 | 561| -------- | -------- | 562| option | 指向Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)的指针。 | 563| errCode | 该参数作为出参使用，表示指向返回错误码的指针，详见[OH_Preferences_ErrCode](#oh_preferences_errcode)。 | 564 565**返回：** 566 567当操作成功时，返回指向打开的Preferences对象[OH_Preferences](#oh_preferences)实例对象的指针，失败返回空指针。 568 569**参见：** 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**描述** 585 586对选取的Key注册数据变更订阅。订阅的Key的值发生变更后，在调用OH_Preferences_Close()后触发回调。 587 588**起始版本：** 13 589 590**参数:** 591 592| 名称 | 描述 | 593| -------- | -------- | 594| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 595| context | 应用上下文的指针。 | 596| observer | 订阅数据变更关联的回调函数[OH_PreferencesDataObserver](#oh_preferencesdataobserver)。 | 597| keys | 需要订阅的Key数组。 | 598| keyCount | 需要订阅的Key的数量。 | 599 600**返回：** 601 602返回执行的错误码。 603 604若错误码为PREFERENCES_OK，表示操作成功。 605 606若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 607 608若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 609 610若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 611 612若错误码为PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT，表示获取数据变更订阅服务失败。 613 614**参见：** 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**描述** 630 631根据Key设置Preferences实例对象中的布尔值。 632 633**起始版本：** 13 634 635**参数:** 636 637| 名称 | 描述 | 638| -------- | -------- | 639| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 640| key | 指向需要设置的Key的指针。 | 641| value | 需要设置的布尔值。 | 642 643**返回：** 644 645返回执行的错误码。 646 647若错误码为PREFERENCES_OK，表示操作成功。 648 649若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 650 651若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 652 653若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 654 655**参见：** 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**描述** 669 670根据Key设置Preferences实例对象中的整型值。 671 672**起始版本：** 13 673 674**参数:** 675 676| 名称 | 描述 | 677| -------- | -------- | 678| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 679| key | 指向需要设置的Key的指针。 | 680| value | 需要设置的整型值。 | 681 682**返回：** 683 684返回执行的错误码。 685 686若错误码为PREFERENCES_OK，表示操作成功。 687 688若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 689 690若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 691 692若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 693 694**参见：** 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**描述** 708 709根据Key设置Preferences实例对象中的字符串。 710 711**起始版本：** 13 712 713**参数:** 714 715| 名称 | 描述 | 716| -------- | -------- | 717| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 718| key | 指向需要设置的Key的指针。 | 719| value | 指向需要设置的字符串指针。 | 720 721**返回：** 722 723返回执行的错误码。 724 725若错误码为PREFERENCES_OK，表示操作成功。 726 727若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 728 729若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 730 731若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 732 733**参见：** 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**描述** 747 748取消注册选取Key的数据变更订阅。 749 750**起始版本：** 13 751 752**参数:** 753 754| 名称 | 描述 | 755| -------- | -------- | 756| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 757| context | 应用上下文的指针。 | 758| observer | 订阅数据变更关联的回调函数[OH_PreferencesDataObserver](#oh_preferencesdataobserver)。 | 759| keys | 需要取消订阅的Key数组。 | 760| keyCount | 需要取消订阅的Key的数量。 | 761 762**返回：** 763 764返回执行的错误码。 765 766若错误码为PREFERENCES_OK，表示操作成功。 767 768若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 769 770若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 771 772若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 773 774**参见：** 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**描述** 790 791创建一个Preferences配置选项的[OH_PreferencesOption](#oh_preferencesoption)实例对象以及指向它的指针。<br>当不再需要使用指针时，请使用[OH_PreferencesOption_Destroy](#oh_preferencesoption_destroy)销毁实例对象，否则会导致内存泄漏。 792 793**起始版本：** 13 794 795**返回：** 796 797如果操作成功，返回指向Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的指针。失败返回空指针。 798 799**参见：** 800 801[OH_PreferencesOption](#oh_preferencesoption) 802 803 804### OH_PreferencesOption_Destroy() 805 806``` 807int OH_PreferencesOption_Destroy (OH_PreferencesOption *option) 808``` 809 810**描述** 811 812销毁Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例。 813 814**起始版本：** 13 815 816**参数:** 817 818| 名称 | 描述 | 819| -------- | -------- | 820| option | Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的指针。 | 821 822**返回：** 823 824返回执行的错误码。 若错误码为PREFERENCES_OK，表示操作成功。 若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 825 826**参见：** 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**描述** 840 841设置Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的包名称。 842 843**起始版本：** 13 844 845**参数:** 846 847| 名称 | 描述 | 848| -------- | -------- | 849| option | Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的指针。 | 850| bundleName | 需要设置的包名称。 | 851 852**返回：** 853 854返回执行的错误码。 855 856若错误码为PREFERENCES_OK，表示操作成功。 857 858若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 859 860**参见：** 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**描述** 874 875设置Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的应用组ID。 876 877设置应用组ID后，会指定在此应用组ID对应的沙箱路径下创建Preferences实例。 878 879应用组ID需要向应用市场获取，暂不支持。 880 881当传入的应用组ID为空字符串时，默认在本应用沙箱目录下创建Preferences实例。 882 883**起始版本：** 13 884 885**参数:** 886 887| 名称 | 描述 | 888| -------- | -------- | 889| option | Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的指针。 | 890| dataGroupId | 需要设置的应用组ID。 | 891 892**返回：** 893 894返回执行的错误码。 895 896若错误码为PREFERENCES_OK，表示操作成功。 897 898若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 899 900**参见：** 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**描述** 914 915设置Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的文件名称。 916 917**起始版本：** 13 918 919**参数:** 920 921| 名称 | 描述 | 922| -------- | -------- | 923| option | 指向Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的指针。 | 924| fileName | 需要设置的文件名称。 | 925 926**返回：** 927 928返回执行的错误码。 929 930若错误码为PREFERENCES_OK，表示操作成功。 931 932若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 933 934**参见：** 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**描述** 948 949获取KV数据中索引对应数据的键。 950 951**起始版本：** 13 952 953**参数:** 954 955| 名称 | 描述 | 956| -------- | -------- | 957| pairs | 目标KV数据[OH_PreferencesPair](#oh_preferencespair)的指针。 | 958| index | 目标KV数据[OH_PreferencesPair](#oh_preferencespair)的索引值。 | 959 960**返回：** 961 962如果操作成功，返回获取到的键的指针。操作失败或传参不合法返回空指针。 963 964**参见：** 965 966[OH_PreferencesPair](#oh_preferencespair) 967 968 969### OH_PreferencesPair_GetPreferencesValue() 970 971``` 972const OH_PreferencesValue* OH_PreferencesPair_GetPreferencesValue (const OH_PreferencesPair *pairs, uint32_t index ) 973``` 974 975**描述** 976 977获取KV数据数组中索引对应的值。 978 979**起始版本：** 13 980 981**参数:** 982 983| 名称 | 描述 | 984| -------- | -------- | 985| pairs | 目标KV数据[OH_PreferencesPair](#oh_preferencespair)的指针。 | 986| index | 目标KV数据[OH_PreferencesPair](#oh_preferencespair)的索引值。 | 987 988**返回：** 989 990如果操作成功，返回获取到的值对象的指针。操作失败或传参不合法返回空指针。 991 992**参见：** 993 994[OH_PreferencesValue](#oh_preferencesvalue) 995 996 997### OH_PreferencesValue_GetBool() 998 999``` 1000int OH_PreferencesValue_GetBool (const OH_PreferencesValue *object, bool *value ) 1001``` 1002 1003**描述** 1004 1005从PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)中获取一个布尔值。 1006 1007**起始版本：** 13 1008 1009**参数:** 1010 1011| 名称 | 描述 | 1012| -------- | -------- | 1013| object | PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)的指针。 | 1014| value | 该参数作为出参使用，表示指向获取到的布尔值的指针。 | 1015 1016**返回：** 1017 1018返回执行的错误码。 1019 1020若错误码为PREFERENCES_OK，表示操作成功。 1021 1022若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 1023 1024若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 1025 1026若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 1027 1028**参见：** 1029 1030[OH_PreferencesValue](#oh_preferencesvalue) 1031 1032[OH_Preferences_ErrCode](#oh_preferences_errcode) 1033 1034 1035### OH_PreferencesValue_GetInt() 1036 1037``` 1038int OH_PreferencesValue_GetInt (const OH_PreferencesValue* object, int* value ) 1039``` 1040 1041**描述** 1042 1043从PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)中获取一个整型值。 1044 1045**起始版本：** 13 1046 1047**参数:** 1048 1049| 名称 | 描述 | 1050| -------- | -------- | 1051| object | PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)的指针。 | 1052| value | 该参数作为出参使用，表示指向获取到的整型值的指针。 | 1053 1054**返回：** 1055 1056返回执行的错误码。 1057 1058若错误码为PREFERENCES_OK，表示操作成功。 1059 1060若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 1061 1062若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 1063 1064若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 1065 1066**参见：** 1067 1068[OH_PreferencesValue](#oh_preferencesvalue) 1069 1070[OH_Preferences_ErrCode](#oh_preferences_errcode) 1071 1072 1073### OH_PreferencesValue_GetString() 1074 1075``` 1076int OH_PreferencesValue_GetString (const OH_PreferencesValue *object, char **value, uint32_t *valueLen ) 1077``` 1078 1079**描述** 1080 1081从PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)中获取字符串。 1082 1083**起始版本：** 13 1084 1085**参数:** 1086 1087| 名称 | 描述 | 1088| -------- | -------- | 1089| object | PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)的指针。 | 1090| value | 该参数作为出参使用，表示指向获取到的字符串的二级指针，使用完毕后需要调用释放函数[OH_Preferences_FreeString](#oh_preferences_freestring)释放内存。 | 1091| valueLen | 该参数作为出参使用，表示指向获取到的字符串长度的指针。 | 1092 1093**返回：** 1094 1095返回执行的错误码。 1096 1097若错误码为PREFERENCES_OK，表示操作成功。 1098 1099若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 1100 1101若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 1102 1103若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 1104 1105**参见：** 1106 1107[OH_PreferencesValue](#oh_preferencesvalue) 1108 1109[OH_Preferences_ErrCode](#oh_preferences_errcode) 1110 1111 1112### OH_PreferencesValue_GetValueType() 1113 1114``` 1115Preference_ValueType OH_PreferencesValue_GetValueType (const OH_PreferencesValue *object) 1116``` 1117 1118**描述** 1119 1120获取PreferencesValue对象的数据类型。 1121 1122**起始版本：** 13 1123 1124**参数:** 1125 1126| 名称 | 描述 | 1127| -------- | -------- | 1128| object | PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)的指针。 | 1129 1130**返回：** 1131 1132返回获取到的数据类型枚举。若返回数据类型枚举为PREFERENCE_TYPE_NULL，代表传参不合法。 1133 1134**参见：** 1135 1136[OH_PreferencesValue](#oh_preferencesvalue) 1137