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_option.h](oh__preferences__option_8h.md) | 提供访问Preferences配置选项（PreferencesOption）的接口与数据结构。 | 22| [oh_preferences_value.h](oh__preferences__value_8h.md) | 提供访问Preferences值（PreferencesValue）对象的接口、枚举类型与数据结构。 | 23 24 25### 类型定义 26 27| 名称 | 描述 | 28| -------- | -------- | 29| typedef struct [OH_Preferences](#oh_preferences) [OH_Preferences](#oh_preferences) | 定义Preferences对象类型。 | 30| typedef void(\* [OH_PreferencesDataObserver](#oh_preferencesdataobserver)) (void \*context, const [OH_PreferencesPair](#oh_preferencespair) \*pairs, uint32_t count) | 定义数据变更触发的回调函数类型。 | 31| typedef enum [OH_Preferences_ErrCode](#oh_preferences_errcode) [OH_Preferences_ErrCode](#oh_preferences_errcode) | 错误码信息。 | 32| typedef struct [OH_PreferencesOption](#oh_preferencesoption) [OH_PreferencesOption](#oh_preferencesoption) | 定义Preferences配置选项的数据结构。 | 33| typedef enum [Preference_ValueType](#preference_valuetype) [Preference_ValueType](#preference_valuetype) | 定义PreferencesValue的数据类型。 | 34| typedef struct [OH_PreferencesPair](#oh_preferencespair) [OH_PreferencesPair](#oh_preferencespair) | 定义Preferences使用的KV数据对象类型。 | 35| typedef struct [OH_PreferencesValue](#oh_preferencesvalue) [OH_PreferencesValue](#oh_preferencesvalue) | 定义PreferencesValue对象类型。 | 36 37 38### 枚举 39 40| 名称 | 描述 | 41| -------- | -------- | 42| [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/>} | 错误码信息。 | 43| [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的数据类型。 | 44 45 46### 函数 47 48| 名称 | 描述 | 49| -------- | -------- | 50| [OH_Preferences](#oh_preferences) \* [OH_Preferences_Open](#oh_preferences_open) ([OH_PreferencesOption](#oh_preferencesoption) \*option, int \*errCode) | 打开一个Preferences实例对象并创建指向它的指针。 当不再需要使用指针时，请使用[OH_Preferences_Close](#oh_preferences_close)关闭实例对象。 | 51| int [OH_Preferences_Close](#oh_preferences_close) ([OH_Preferences](#oh_preferences) \*preference) | 关闭一个Preferences实例对象。 | 52| int [OH_Preferences_GetInt](#oh_preferences_getint) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, int \*value) | 获取Preferences实例对象中Key对应的整型值。 | 53| int [OH_Preferences_GetBool](#oh_preferences_getbool) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, bool \*value) | 获取Preferences实例对象中Key对应的布尔值。 | 54| int [OH_Preferences_GetString](#oh_preferences_getstring) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, char \*\*value, uint32_t \*valueLen) | 获取Preferences实例对象中Key对应的字符串。 | 55| void [OH_Preferences_FreeString](#oh_preferences_freestring) (char \*string) | 释放从Preferences实例对象中获取的字符串。 | 56| int [OH_Preferences_SetInt](#oh_preferences_setint) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, int value) | 根据Key设置Preferences实例对象中的整型值。 | 57| int [OH_Preferences_SetBool](#oh_preferences_setbool) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, bool value) | 根据Key设置Preferences实例对象中的布尔值。 | 58| int [OH_Preferences_SetString](#oh_preferences_setstring) ([OH_Preferences](#oh_preferences) \*preference, const char \*key, const char \*value) | 根据Key设置Preferences实例对象中的字符串。 | 59| int [OH_Preferences_Delete](#oh_preferences_delete) ([OH_Preferences](#oh_preferences) \*preference, const char \*key) | 在Preferences实例对象中删除Key对应的KV数据。 | 60| 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()后触发回调。 | 61| 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的数据变更订阅。 | 62| [OH_PreferencesOption](#oh_preferencesoption) \* [OH_PreferencesOption_Create](#oh_preferencesoption_create) (void) | 创建一个Preferences配置选项的[OH_PreferencesOption](#oh_preferencesoption)实例对象以及指向它的指针。 当不再需要使用指针时，请使用[OH_PreferencesOption_Destroy](#oh_preferencesoption_destroy)销毁实例对象，否则会导致内存泄漏。 | 63| int [OH_PreferencesOption_SetFileName](#oh_preferencesoption_setfilename) ([OH_PreferencesOption](#oh_preferencesoption) \*option, const char \*fileName) | 设置Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的文件名称。 | 64| int [OH_PreferencesOption_SetBundleName](#oh_preferencesoption_setbundlename) ([OH_PreferencesOption](#oh_preferencesoption) \*option, const char \*bundleName) | 设置Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的包名称。 | 65| int [OH_PreferencesOption_SetDataGroupId](#oh_preferencesoption_setdatagroupid) ([OH_PreferencesOption](#oh_preferencesoption) \*option, const char \*dataGroupId) | 设置Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的应用组ID。 | 66| int [OH_PreferencesOption_Destroy](#oh_preferencesoption_destroy) ([OH_PreferencesOption](#oh_preferencesoption) \*option) | 销毁Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例。 | 67| const char \* [OH_PreferencesPair_GetKey](#oh_preferencespair_getkey) (const [OH_PreferencesPair](#oh_preferencespair) \*pairs, uint32_t index) | 获取KV数据中索引对应数据的键。 | 68| const [OH_PreferencesValue](#oh_preferencesvalue) \* [OH_PreferencesPair_GetPreferencesValue](#oh_preferencespair_getpreferencesvalue) (const [OH_PreferencesPair](#oh_preferencespair) \*pairs, uint32_t index) | 获取KV数据数组中索引对应的值。 | 69| [Preference_ValueType](#preference_valuetype) [OH_PreferencesValue_GetValueType](#oh_preferencesvalue_getvaluetype) (const [OH_PreferencesValue](#oh_preferencesvalue) \*object) | 获取PreferencesValue对象的数据类型。 | 70| int [OH_PreferencesValue_GetInt](#oh_preferencesvalue_getint) (const [OH_PreferencesValue](#oh_preferencesvalue) \*object, int \*value) | 从PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)中获取一个整型值。 | 71| int [OH_PreferencesValue_GetBool](#oh_preferencesvalue_getbool) (const [OH_PreferencesValue](#oh_preferencesvalue) \*object, bool \*value) | 从PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)中获取一个布尔值。 | 72| int [OH_PreferencesValue_GetString](#oh_preferencesvalue_getstring) (const [OH_PreferencesValue](#oh_preferencesvalue) \*object, char \*\*value, uint32_t \*valueLen) | 从PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)中获取字符串。 | 73 74 75## 类型定义说明 76 77 78### OH_Preferences 79 80``` 81typedef struct OH_Preferences OH_Preferences 82``` 83 84**描述** 85 86定义Preferences对象类型。 87 88**起始版本：** 13 89 90 91### OH_Preferences_ErrCode 92 93``` 94typedef enum OH_Preferences_ErrCode OH_Preferences_ErrCode 95``` 96 97**描述** 98 99错误码信息。 100 101**起始版本：** 13 102 103 104### OH_PreferencesDataObserver 105 106``` 107typedef void(*OH_PreferencesDataObserver) (void *context, const OH_PreferencesPair *pairs, uint32_t count) 108``` 109 110**描述** 111 112定义数据变更触发的回调函数类型。 113 114**起始版本：** 13 115 116**参数:** 117 118| 名称 | 描述 | 119| -------- | -------- | 120| context | 应用上下文的指针。 | 121| pairs | 发生变更的KV数据的指针。 | 122| count | 发生变更的KV数据的数量。 | 123 124**参见：** 125 126[OH_PreferencesPair](#oh_preferencespair) 127 128 129### OH_PreferencesOption 130 131``` 132typedef struct OH_PreferencesOption OH_PreferencesOption 133``` 134 135**描述** 136 137定义Preferences配置选项的数据结构。 138 139**起始版本：** 13 140 141 142### OH_PreferencesPair 143 144``` 145typedef struct OH_PreferencesPair OH_PreferencesPair 146``` 147 148**描述** 149 150定义Preferences使用的KV数据对象类型。 151 152**起始版本：** 13 153 154 155### OH_PreferencesValue 156 157``` 158typedef struct OH_PreferencesValue OH_PreferencesValue 159``` 160 161**描述** 162 163定义PreferencesValue对象类型。 164 165**起始版本：** 13 166 167 168### Preference_ValueType 169 170``` 171typedef enum Preference_ValueType Preference_ValueType 172``` 173 174**描述** 175 176定义PreferencesValue的数据类型。 177 178**起始版本：** 13 179 180 181## 枚举类型说明 182 183 184### OH_Preferences_ErrCode 185 186``` 187enum OH_Preferences_ErrCode 188``` 189 190**描述** 191 192错误码信息。 193 194**起始版本：** 13 195 196| 枚举值 | 描述 | 197| -------- | -------- | 198| PREFERENCES_OK | 操作执行成功 | 199| PREFERENCES_ERROR_INVALID_PARAM | 参数不合法 | 200| PREFERENCES_ERROR_NOT_SUPPORTED | 系统能力不支持 | 201| PREFERENCES_ERROR_BASE | 基准错误码 | 202| PREFERENCES_ERROR_DELETE_FILE | 删除文件失败 | 203| PREFERENCES_ERROR_STORAGE | 存储异常 | 204| PREFERENCES_ERROR_MALLOC | 申请内存失败 | 205| PREFERENCES_ERROR_KEY_NOT_FOUND | Key不存在 | 206| PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT | 获取数据变更订阅服务失败 | 207 208 209### Preference_ValueType 210 211``` 212enum Preference_ValueType 213``` 214 215**描述** 216 217定义PreferencesValue的数据类型。 218 219**起始版本：** 13 220 221| 枚举值 | 描述 | 222| -------- | -------- | 223| PREFERENCE_TYPE_NULL | 空类型 | 224| PREFERENCE_TYPE_INT | 整型类型 | 225| PREFERENCE_TYPE_BOOL | 布尔类型 | 226| PREFERENCE_TYPE_STRING | 字符串类型 | 227| PREFERENCE_TYPE_BUTT | 结束类型 | 228 229 230## 函数说明 231 232 233### OH_Preferences_Close() 234 235``` 236int OH_Preferences_Close (OH_Preferences *preference) 237``` 238 239**描述** 240 241关闭一个Preferences实例对象。 242 243**起始版本：** 13 244 245**参数:** 246 247| 名称 | 描述 | 248| -------- | -------- | 249| preference | 指向需要关闭的[OH_Preferences](#oh_preferences)实例对象的指针。 | 250 251**返回：** 252 253返回执行的错误码，详见[OH_Preferences_ErrCode](#oh_preferences_errcode)。 254 255若错误码为PREFERENCES_OK，表示操作成功。 256 257若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 258 259若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 260 261若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 262 263**参见：** 264 265[OH_Preferences](#oh_preferences) 266 267[OH_Preferences_ErrCode](#oh_preferences_errcode) 268 269 270### OH_Preferences_Delete() 271 272``` 273int OH_Preferences_Delete (OH_Preferences *preference, const char *key ) 274``` 275 276**描述** 277 278在Preferences实例对象中删除Key对应的KV数据。 279 280**起始版本：** 13 281 282**参数:** 283 284| 名称 | 描述 | 285| -------- | -------- | 286| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 287| key | 指向需要删除的Key的指针。 | 288 289**返回：** 290 291返回执行的错误码。 292 293若错误码为PREFERENCES_OK，表示操作成功。 294 295若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 296 297若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 298 299若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 300 301**参见：** 302 303[OH_Preferences](#oh_preferences) 304 305[OH_Preferences_ErrCode](#oh_preferences_errcode) 306 307 308### OH_Preferences_FreeString() 309 310``` 311void OH_Preferences_FreeString (char *string) 312``` 313 314**描述** 315 316释放从Preferences实例对象中获取的字符串。 317 318**起始版本：** 13 319 320**参数:** 321 322| 名称 | 描述 | 323| -------- | -------- | 324| string | 需要释放的字符串指针。 | 325 326**参见：** 327 328[OH_Preferences](#oh_preferences) 329 330 331### OH_Preferences_GetBool() 332 333``` 334int OH_Preferences_GetBool (OH_Preferences *preference, const char *key, bool *value ) 335``` 336 337**描述** 338 339获取Preferences实例对象中Key对应的布尔值。 340 341**起始版本：** 13 342 343**参数:** 344 345| 名称 | 描述 | 346| -------- | -------- | 347| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 348| key | 需要获取的Key的指针。 | 349| value | 该参数作为出参使用，表示指向获取到的布尔值的指针。 | 350 351**返回：** 352 353返回执行的错误码。 354 355若错误码为PREFERENCES_OK，表示操作成功。 356 357若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 358 359若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 360 361若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 362 363若错误码为PREFERENCES_ERROR_KEY_NOT_FOUND，表示查询的key不存在。 364 365**参见：** 366 367[OH_Preferences](#oh_preferences) 368 369[OH_Preferences_ErrCode](#oh_preferences_errcode) 370 371 372### OH_Preferences_GetInt() 373 374``` 375int OH_Preferences_GetInt (OH_Preferences *preference, const char *key, int *value ) 376``` 377 378**描述** 379 380获取Preferences实例对象中Key对应的整型值。 381 382**起始版本：** 13 383 384**参数:** 385 386| 名称 | 描述 | 387| -------- | -------- | 388| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 389| key | 需要获取的Key的指针。 | 390| value | 该参数作为出参使用，表示指向获取到的整型值的指针。 | 391 392**返回：** 393 394返回执行的错误码。 395 396若错误码为PREFERENCES_OK，表示操作成功。 397 398若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 399 400若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 401 402若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 403 404若错误码为PREFERENCES_ERROR_KEY_NOT_FOUND，表示查询的Key不存在。 405 406**参见：** 407 408[OH_Preferences](#oh_preferences) 409 410[OH_Preferences_ErrCode](#oh_preferences_errcode) 411 412 413### OH_Preferences_GetString() 414 415``` 416int OH_Preferences_GetString (OH_Preferences *preference, const char *key, char **value, uint32_t *valueLen ) 417``` 418 419**描述** 420 421获取Preferences实例对象中Key对应的字符串。 422 423**起始版本：** 13 424 425**参数:** 426 427| 名称 | 描述 | 428| -------- | -------- | 429| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 430| key | 需要获取的Key的指针。 | 431| value | 该参数作为出参使用，表示指向获取到的字符串的二级指针，使用完毕后需要调用释放函数[OH_Preferences_FreeString](#oh_preferences_freestring)释放内存。 | 432| valueLen | 该参数作为出参使用，表示获取到的字符串长度的指针。 | 433 434**返回：** 435 436返回执行的错误码。 437 438若错误码为PREFERENCES_OK，表示操作成功。 439 440若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 441 442若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 443 444若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 445 446若错误码为PREFERENCES_ERROR_KEY_NOT_FOUND，表示查询的Key不存在。 447 448**参见：** 449 450[OH_Preferences](#oh_preferences) 451 452[OH_Preferences_ErrCode](#oh_preferences_errcode) 453 454 455### OH_Preferences_Open() 456 457``` 458OH_Preferences* OH_Preferences_Open (OH_PreferencesOption *option, int *errCode ) 459``` 460 461**描述** 462 463打开一个Preferences实例对象并创建指向它的指针。 当不再需要使用指针时，请使用[OH_Preferences_Close](#oh_preferences_close)关闭实例对象。 464 465**起始版本：** 13 466 467**参数:** 468 469| 名称 | 描述 | 470| -------- | -------- | 471| option | 指向Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)的指针。 | 472| errCode | 该参数作为出参使用，表示指向返回错误码的指针，详见[OH_Preferences_ErrCode](#oh_preferences_errcode)。 | 473 474**返回：** 475 476当操作成功时，返回指向打开的Preferences对象[OH_Preferences](#oh_preferences)实例对象的指针，失败返回空指针。 477 478**参见：** 479 480[OH_Preferences](#oh_preferences) 481 482[OH_PreferencesOption](#oh_preferencesoption) 483 484[OH_Preferences_ErrCode](#oh_preferences_errcode) 485 486 487### OH_Preferences_RegisterDataObserver() 488 489``` 490int OH_Preferences_RegisterDataObserver (OH_Preferences *preference, void *context, OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount ) 491``` 492 493**描述** 494 495对选取的Key注册数据变更订阅。订阅的Key的值发生变更后，在调用OH_Preferences_Close()后触发回调。 496 497**起始版本：** 13 498 499**参数:** 500 501| 名称 | 描述 | 502| -------- | -------- | 503| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 504| context | 应用上下文的指针。 | 505| observer | 订阅数据变更关联的回调函数[OH_PreferencesDataObserver](#oh_preferencesdataobserver)。 | 506| keys | 需要订阅的Key数组。 | 507| keyCount | 需要订阅的Key的数量。 | 508 509**返回：** 510 511返回执行的错误码。 512 513若错误码为PREFERENCES_OK，表示操作成功。 514 515若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 516 517若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 518 519若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 520 521若错误码为PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT，表示获取数据变更订阅服务失败。 522 523**参见：** 524 525[OH_Preferences](#oh_preferences) 526 527[OH_PreferencesDataObserver](#oh_preferencesdataobserver) 528 529[OH_Preferences_ErrCode](#oh_preferences_errcode) 530 531 532### OH_Preferences_SetBool() 533 534``` 535int OH_Preferences_SetBool (OH_Preferences *preference, const char *key, bool value ) 536``` 537 538**描述** 539 540根据Key设置Preferences实例对象中的布尔值。 541 542**起始版本：** 13 543 544**参数:** 545 546| 名称 | 描述 | 547| -------- | -------- | 548| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 549| key | 指向需要设置的Key的指针。 | 550| value | 需要设置的布尔值。 | 551 552**返回：** 553 554返回执行的错误码。 555 556若错误码为PREFERENCES_OK，表示操作成功。 557 558若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 559 560若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 561 562若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 563 564**参见：** 565 566[OH_Preferences](#oh_preferences) 567 568[OH_Preferences_ErrCode](#oh_preferences_errcode) 569 570 571### OH_Preferences_SetInt() 572 573``` 574int OH_Preferences_SetInt (OH_Preferences *preference, const char *key, int value ) 575``` 576 577**描述** 578 579根据Key设置Preferences实例对象中的整型值。 580 581**起始版本：** 13 582 583**参数:** 584 585| 名称 | 描述 | 586| -------- | -------- | 587| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 588| key | 指向需要设置的Key的指针。 | 589| value | 需要设置的整型值。 | 590 591**返回：** 592 593返回执行的错误码。 594 595若错误码为PREFERENCES_OK，表示操作成功。 596 597若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 598 599若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 600 601若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 602 603**参见：** 604 605[OH_Preferences](#oh_preferences) 606 607[OH_Preferences_ErrCode](#oh_preferences_errcode) 608 609 610### OH_Preferences_SetString() 611 612``` 613int OH_Preferences_SetString (OH_Preferences *preference, const char *key, const char *value ) 614``` 615 616**描述** 617 618根据Key设置Preferences实例对象中的字符串。 619 620**起始版本：** 13 621 622**参数:** 623 624| 名称 | 描述 | 625| -------- | -------- | 626| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 627| key | 指向需要设置的Key的指针。 | 628| value | 指向需要设置的字符串指针。 | 629 630**返回：** 631 632返回执行的错误码。 633 634若错误码为PREFERENCES_OK，表示操作成功。 635 636若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 637 638若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 639 640若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 641 642**参见：** 643 644[OH_Preferences](#oh_preferences) 645 646[OH_Preferences_ErrCode](#oh_preferences_errcode) 647 648 649### OH_Preferences_UnregisterDataObserver() 650 651``` 652int OH_Preferences_UnregisterDataObserver (OH_Preferences *preference, void *context, OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount ) 653``` 654 655**描述** 656 657取消注册选取Key的数据变更订阅。 658 659**起始版本：** 13 660 661**参数:** 662 663| 名称 | 描述 | 664| -------- | -------- | 665| preference | 指向目标[OH_Preferences](#oh_preferences)实例对象的指针。 | 666| context | 应用上下文的指针。 | 667| observer | 订阅数据变更关联的回调函数[OH_PreferencesDataObserver](#oh_preferencesdataobserver)。 | 668| keys | 需要取消订阅的Key数组。 | 669| keyCount | 需要取消订阅的Key的数量。 | 670 671**返回：** 672 673返回执行的错误码。 674 675若错误码为PREFERENCES_OK，表示操作成功。 676 677若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 678 679若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 680 681若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 682 683**参见：** 684 685[OH_Preferences](#oh_preferences) 686 687[OH_PreferencesDataObserver](#oh_preferencesdataobserver) 688 689[OH_Preferences_ErrCode](#oh_preferences_errcode) 690 691 692### OH_PreferencesOption_Create() 693 694``` 695OH_PreferencesOption* OH_PreferencesOption_Create (void ) 696``` 697 698**描述** 699 700创建一个Preferences配置选项的[OH_PreferencesOption](#oh_preferencesoption)实例对象以及指向它的指针。 当不再需要使用指针时，请使用[OH_PreferencesOption_Destroy](#oh_preferencesoption_destroy)销毁实例对象，否则会导致内存泄漏。 701 702**起始版本：** 13 703 704**返回：** 705 706如果操作成功，返回指向Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的指针。失败返回空指针。 707 708**参见：** 709 710[OH_PreferencesOption](#oh_preferencesoption) 711 712 713### OH_PreferencesOption_Destroy() 714 715``` 716int OH_PreferencesOption_Destroy (OH_PreferencesOption *option) 717``` 718 719**描述** 720 721销毁Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例。 722 723**起始版本：** 13 724 725**参数:** 726 727| 名称 | 描述 | 728| -------- | -------- | 729| option | Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的指针。 | 730 731**返回：** 732 733返回执行的错误码。 若错误码为PREFERENCES_OK，表示操作成功。 若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 734 735**参见：** 736 737[OH_PreferencesOption](#oh_preferencesoption) 738 739[OH_Preferences_ErrCode](#oh_preferences_errcode) 740 741 742### OH_PreferencesOption_SetBundleName() 743 744``` 745int OH_PreferencesOption_SetBundleName (OH_PreferencesOption *option, const char *bundleName ) 746``` 747 748**描述** 749 750设置Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的包名称。 751 752**起始版本：** 13 753 754**参数:** 755 756| 名称 | 描述 | 757| -------- | -------- | 758| option | Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的指针。 | 759| bundleName | 需要设置的包名称。 | 760 761**返回：** 762 763返回执行的错误码。 764 765若错误码为PREFERENCES_OK，表示操作成功。 766 767若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 768 769**参见：** 770 771[OH_PreferencesOption](#oh_preferencesoption) 772 773[OH_Preferences_ErrCode](#oh_preferences_errcode) 774 775 776### OH_PreferencesOption_SetDataGroupId() 777 778``` 779int OH_PreferencesOption_SetDataGroupId (OH_PreferencesOption *option, const char *dataGroupId ) 780``` 781 782**描述** 783 784设置Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的应用组ID。 785 786设置应用组ID后，会指定在此应用组ID对应的沙箱路径下创建Preferences实例。 787 788应用组ID需要向应用市场获取，暂不支持。 789 790当传入的应用组ID为空字符串时，默认在本应用沙箱目录下创建Preferences实例。 791 792**起始版本：** 13 793 794**参数:** 795 796| 名称 | 描述 | 797| -------- | -------- | 798| option | Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的指针。 | 799| dataGroupId | 需要设置的应用组ID。 | 800 801**返回：** 802 803返回执行的错误码。 804 805若错误码为PREFERENCES_OK，表示操作成功。 806 807若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 808 809**参见：** 810 811[OH_PreferencesOption](#oh_preferencesoption) 812 813[OH_Preferences_ErrCode](#oh_preferences_errcode) 814 815 816### OH_PreferencesOption_SetFileName() 817 818``` 819int OH_PreferencesOption_SetFileName (OH_PreferencesOption *option, const char *fileName ) 820``` 821 822**描述** 823 824设置Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的文件名称。 825 826**起始版本：** 13 827 828**参数:** 829 830| 名称 | 描述 | 831| -------- | -------- | 832| option | 指向Preferences配置选项[OH_PreferencesOption](#oh_preferencesoption)实例对象的指针。 | 833| fileName | 需要设置的文件名称。 | 834 835**返回：** 836 837返回执行的错误码。 838 839若错误码为PREFERENCES_OK，表示操作成功。 840 841若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 842 843**参见：** 844 845[OH_PreferencesOption](#oh_preferencesoption) 846 847[OH_Preferences_ErrCode](#oh_preferences_errcode) 848 849 850### OH_PreferencesPair_GetKey() 851 852``` 853const char* OH_PreferencesPair_GetKey (const OH_PreferencesPair *pairs, uint32_t index ) 854``` 855 856**描述** 857 858获取KV数据中索引对应数据的键。 859 860**起始版本：** 13 861 862**参数:** 863 864| 名称 | 描述 | 865| -------- | -------- | 866| pairs | 目标KV数据[OH_PreferencesPair](#oh_preferencespair)的指针。 | 867| index | 目标KV数据[OH_PreferencesPair](#oh_preferencespair)的索引值。 | 868 869**返回：** 870 871如果操作成功，返回获取到的键的指针。操作失败或传参不合法返回空指针。 872 873**参见：** 874 875[OH_PreferencesPair](#oh_preferencespair) 876 877 878### OH_PreferencesPair_GetPreferencesValue() 879 880``` 881const OH_PreferencesValue* OH_PreferencesPair_GetPreferencesValue (const OH_PreferencesPair *pairs, uint32_t index ) 882``` 883 884**描述** 885 886获取KV数据数组中索引对应的值。 887 888**起始版本：** 13 889 890**参数:** 891 892| 名称 | 描述 | 893| -------- | -------- | 894| pairs | 目标KV数据[OH_PreferencesPair](#oh_preferencespair)的指针。 | 895| index | 目标KV数据[OH_PreferencesPair](#oh_preferencespair)的索引值。 | 896 897**返回：** 898 899如果操作成功，返回获取到的值对象的指针。操作失败或传参不合法返回空指针。 900 901**参见：** 902 903[OH_PreferencesValue](#oh_preferencesvalue) 904 905 906### OH_PreferencesValue_GetBool() 907 908``` 909int OH_PreferencesValue_GetBool (const OH_PreferencesValue *object, bool *value ) 910``` 911 912**描述** 913 914从PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)中获取一个布尔值。 915 916**起始版本：** 13 917 918**参数:** 919 920| 名称 | 描述 | 921| -------- | -------- | 922| object | PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)的指针。 | 923| value | 该参数作为出参使用，表示指向获取到的布尔值的指针。 | 924 925**返回：** 926 927返回执行的错误码。 928 929若错误码为PREFERENCES_OK，表示操作成功。 930 931若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 932 933若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 934 935若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 936 937**参见：** 938 939[OH_PreferencesValue](#oh_preferencesvalue) 940 941[OH_Preferences_ErrCode](#oh_preferences_errcode) 942 943 944### OH_PreferencesValue_GetInt() 945 946``` 947int OH_PreferencesValue_GetInt (const OH_PreferencesValue* object, int* value ) 948``` 949 950**描述** 951 952从PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)中获取一个整型值。 953 954**起始版本：** 13 955 956**参数:** 957 958| 名称 | 描述 | 959| -------- | -------- | 960| object | PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)的指针。 | 961| value | 该参数作为出参使用，表示指向获取到的整型值的指针。 | 962 963**返回：** 964 965返回执行的错误码。 966 967若错误码为PREFERENCES_OK，表示操作成功。 968 969若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 970 971若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 972 973若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 974 975**参见：** 976 977[OH_PreferencesValue](#oh_preferencesvalue) 978 979[OH_Preferences_ErrCode](#oh_preferences_errcode) 980 981 982### OH_PreferencesValue_GetString() 983 984``` 985int OH_PreferencesValue_GetString (const OH_PreferencesValue *object, char **value, uint32_t *valueLen ) 986``` 987 988**描述** 989 990从PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)中获取字符串。 991 992**起始版本：** 13 993 994**参数:** 995 996| 名称 | 描述 | 997| -------- | -------- | 998| object | PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)的指针。 | 999| value | 该参数作为出参使用，表示指向获取到的字符串的二级指针，使用完毕后需要调用释放函数[OH_Preferences_FreeString](#oh_preferences_freestring)释放内存。 | 1000| valueLen | 该参数作为出参使用，表示指向获取到的字符串长度的指针。 | 1001 1002**返回：** 1003 1004返回执行的错误码。 1005 1006若错误码为PREFERENCES_OK，表示操作成功。 1007 1008若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 1009 1010若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。 1011 1012若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。 1013 1014**参见：** 1015 1016[OH_PreferencesValue](#oh_preferencesvalue) 1017 1018[OH_Preferences_ErrCode](#oh_preferences_errcode) 1019 1020 1021### OH_PreferencesValue_GetValueType() 1022 1023``` 1024Preference_ValueType OH_PreferencesValue_GetValueType (const OH_PreferencesValue *object) 1025``` 1026 1027**描述** 1028 1029获取PreferencesValue对象的数据类型。 1030 1031**起始版本：** 13 1032 1033**参数:** 1034 1035| 名称 | 描述 | 1036| -------- | -------- | 1037| object | PreferencesValue对象[OH_PreferencesValue](#oh_preferencesvalue)的指针。 | 1038 1039**返回：** 1040 1041返回获取到的数据类型枚举。若返回数据类型枚举为PREFERENCE_TYPE_NULL，代表传参不合法。 1042 1043**参见：** 1044 1045[OH_PreferencesValue](#oh_preferencesvalue) 1046