1# oh_preferences_option.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配置选项（PreferencesOption）的接口与数据结构。 12 13**引用文件：** <database/preferences/oh_preferences_option.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_PreferencesOption](capi-preferences-oh-preferencesoption.md) | OH_PreferencesOption | 定义Preferences配置选项的数据结构。 | 30 31### 枚举 32 33| 名称 | typedef关键字 | 描述 | 34| --------------------------------------------------- | ----------------------- | ------------------------------ | 35| [Preferences_StorageType](#preferences_storagetype) | Preferences_StorageType | 首选项配置选项的存储模式枚举。 | 36 37### 函数 38 39| 名称 | 描述 | 40| ------------------------------------------------------------ | ------------------------------------------------------------ | 41| [OH_PreferencesOption *OH_PreferencesOption_Create(void)](#oh_preferencesoption_create) | 创建一个Preferences配置选项的[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象以及指向它的指针。<br>当不再需要使用指针时，请使用[OH_PreferencesOption_Destroy](capi-oh-preferences-option-h.md#oh_preferencesoption_destroy)销毁实例对象，否则会导致内存泄漏。 | 42| [int OH_PreferencesOption_SetFileName(OH_PreferencesOption *option, const char *fileName)](#oh_preferencesoption_setfilename) | 设置Preferences配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象的文件名称。 | 43| [int OH_PreferencesOption_SetBundleName(OH_PreferencesOption *option, const char *bundleName)](#oh_preferencesoption_setbundlename) | 设置Preferences配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象的包名称。 | 44| [int OH_PreferencesOption_SetDataGroupId(OH_PreferencesOption *option, const char *dataGroupId)](#oh_preferencesoption_setdatagroupid) | 设置Preferences配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象的应用组ID。<br>设置应用组ID后，会指定在此应用组ID对应的沙箱路径下创建Preferences实例。应用组ID需要向应用市场获取，暂不支持。<br>当传入的应用组ID为空字符串时，默认在本应用沙箱目录下创建Preferences实例。 | 45| [int OH_PreferencesOption_SetStorageType(OH_PreferencesOption *option, Preferences_StorageType type)](#oh_preferencesoption_setstoragetype) | 设置Preferences实例对象的存储模式。 | 46| [int OH_PreferencesOption_Destroy(OH_PreferencesOption *option)](#oh_preferencesoption_destroy) | 销毁Preferences配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例。 | 47 48## 枚举类型说明 49 50### Preferences_StorageType 51 52``` 53enum Preferences_StorageType 54``` 55 56**描述** 57 58首选项配置选项的存储模式枚举。 59 60**起始版本：** 18 61 62| 枚举项 | 描述 | 63| --------------------------- | ------------------------------------------------------------ | 64| PREFERENCES_STORAGE_XML = 0 | XML存储模式，对数据的操作发生在内存中，调用[OH_Preferences_Close](capi-oh-preferences-h.md#oh_preferences_close)时落盘，不支持多进程。 | 65| PREFERENCES_STORAGE_GSKV | GSKV存储模式，对数据的操作实时落盘，可支持多进程 | 66 67 68## 函数说明 69 70### OH_PreferencesOption_Create() 71 72``` 73OH_PreferencesOption *OH_PreferencesOption_Create(void) 74``` 75 76**描述** 77 78创建一个Preferences配置选项的[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象以及指向它的指针。<br>当不再需要使用指针时，请使用[OH_PreferencesOption_Destroy](capi-oh-preferences-option-h.md#oh_preferencesoption_destroy)销毁实例对象，否则会导致内存泄漏。 79 80**起始版本：** 13 81 82**返回：** 83 84| 类型 | 说明 | 85| ---------------------------------------------------- | ------------------------------------------------------------ | 86| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) | 如果操作成功，返回指向Preferences配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象的指针。失败返回空指针。 | 87 88### OH_PreferencesOption_SetFileName() 89 90``` 91int OH_PreferencesOption_SetFileName(OH_PreferencesOption *option, const char *fileName) 92``` 93 94**描述** 95 96设置Preferences配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象的文件名称。 97 98**起始版本：** 13 99 100 101**参数：** 102 103| 参数项 | 描述 | 104| ------------------------------------------------------------ | ------------------------------------------------------------ | 105| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) *option | 指向Preferences配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象的指针。 | 106| const char *fileName | 需要设置的文件名称。 | 107 108**返回：** 109 110| 类型 | 说明 | 111| ---- | ------------------------------------------------------------ | 112| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 | 113 114**参考：** 115 116OH_Preferences_ErrCode 117 118### OH_PreferencesOption_SetBundleName() 119 120``` 121int OH_PreferencesOption_SetBundleName(OH_PreferencesOption *option, const char *bundleName) 122``` 123 124**描述** 125 126设置Preferences配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象的包名称。 127 128**起始版本：** 13 129 130 131**参数：** 132 133| 参数项 | 描述 | 134| ------------------------------------------------------------ | ------------------------------------------------------------ | 135| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) *option | 配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象的指针。 | 136| const char *bundleName | 需要设置的包名称。 | 137 138**返回：** 139 140| 类型 | 说明 | 141| ---- | ------------------------------------------------------------ | 142| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 | 143 144### OH_PreferencesOption_SetDataGroupId() 145 146``` 147int OH_PreferencesOption_SetDataGroupId(OH_PreferencesOption *option, const char *dataGroupId) 148``` 149 150**描述** 151 152设置Preferences配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象的应用组ID。<br>设置应用组ID后，会指定在此应用组ID对应的沙箱路径下创建Preferences实例。应用组ID需要向应用市场获取，暂不支持。<br>当传入的应用组ID为空字符串时，默认在本应用沙箱目录下创建Preferences实例。 153 154**起始版本：** 13 155 156**参数：** 157 158| 参数项 | 描述 | 159| ------------------------------------------------------------ | ------------------------------------------------------------ | 160| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) *option | 配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象的指针。 | 161| const char *dataGroupId | 需要设置的应用组ID。 | 162 163**返回：** 164 165| 类型 | 说明 | 166| ---- | ------------------------------------------------------------ | 167| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 | 168 169### OH_PreferencesOption_SetStorageType() 170 171``` 172int OH_PreferencesOption_SetStorageType(OH_PreferencesOption *option, Preferences_StorageType type) 173``` 174 175**描述** 176 177设置Preferences实例对象的存储模式。 178 179**起始版本：** 18 180 181 182**参数：** 183 184| 参数项 | 描述 | 185| ------------------------------------------------------------ | ---------------------------------- | 186| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) *option | 指向要设置存储模式的配置项的指针。 | 187| [Preferences_StorageType](#preferences_storagetype) type | 需要设置的存储模式。 | 188 189**返回：** 190 191| 类型 | 说明 | 192| ---- | ------------------------------------------------------------ | 193| int | 返回执行的错误码。<br>若错误码为PREFERENCES_OK，表示操作成功。<br>若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 | 194 195### OH_PreferencesOption_Destroy() 196 197``` 198int OH_PreferencesOption_Destroy(OH_PreferencesOption *option) 199``` 200 201**描述** 202 203销毁Preferences配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例。 204 205**起始版本：** 13 206 207 208**参数：** 209 210| 参数项 | 描述 | 211| ------------------------------------------------------------ | ------------------------------------------------------------ | 212| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) *option | 配置选项[OH_PreferencesOption](capi-preferences-oh-preferencesoption.md)实例对象的指针。 | 213 214**返回：** 215 216| 类型 | 说明 | 217| ---- | ------------------------------------------------------------ | 218| int | 返回接口操作执行的状态码。<br>PREFERENCES_OK，表示操作成功。<br>PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。 | 219 220 221 222