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