1# oh_preferences_option.h 2 3## Overview 4 5Provides APIs and structs for accessing the **PreferencesOption** object. 6 7**File to include**: <database/preferences/oh_preferences_option.h> 8 9**Library**: libohpreferences.so 10 11**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 12 13**Since**: 13 14 15**Related module**: [Preferences](capi-preferences.md) 16 17## Summary 18 19### Structs 20 21| Name | typedef Keyword | Description | 22| ---------------------------------------------------- | -------------------- | ----------------------------------- | 23| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) | OH_PreferencesOption | Defines a struct for **Preferences** configuration.| 24 25### Enums 26 27| Name | typedef Keyword | Description | 28| --------------------------------------------------- | ----------------------- | ------------------------------ | 29| [Preferences_StorageType](#preferences_storagetype) | Preferences_StorageType | Enumerates the preferences storage types.| 30 31### Functions 32 33| Name | Description | 34| ------------------------------------------------------------ | ------------------------------------------------------------ | 35| [OH_PreferencesOption *OH_PreferencesOption_Create(void)](#oh_preferencesoption_create) | Creates a [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance and a pointer to it.<br>If this pointer is no longer required, use [OH_PreferencesOption_Destroy](capi-oh-preferences-option-h.md#oh_preferencesoption_destroy) to destroy it. Otherwise, memory leaks may occur.| 36| [int OH_PreferencesOption_SetFileName(OH_PreferencesOption *option, const char *fileName)](#oh_preferencesoption_setfilename) | Sets the file name for an [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance.| 37| [int OH_PreferencesOption_SetBundleName(OH_PreferencesOption *option, const char *bundleName)](#oh_preferencesoption_setbundlename) | Sets the bundle name for an [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance.| 38| [int OH_PreferencesOption_SetDataGroupId(OH_PreferencesOption *option, const char *dataGroupId)](#oh_preferencesoption_setdatagroupid) | Sets the application group ID for an [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance.<br>After the application group ID is set, the **Preferences** instance will be created in the sandbox directory of the application group ID. The application group ID must be obtained from AppGallery. This parameter is not supported currently.<br>If the application group ID is an empty string, the **Preferences** instance will be created in the sandbox directory of the current application.| 39| [int OH_PreferencesOption_SetStorageType(OH_PreferencesOption *option, Preferences_StorageType type)](#oh_preferencesoption_setstoragetype) | Sets the storage type for a **Preferences** instance. | 40| [int OH_PreferencesOption_Destroy(OH_PreferencesOption *option)](#oh_preferencesoption_destroy) | Destroys an [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance.| 41 42## Enum Description 43 44### Preferences_StorageType 45 46``` 47enum Preferences_StorageType 48``` 49 50**Description** 51 52Enumerates the preferences storage types. 53 54**Since**: 18 55 56| Enum | Description | 57| --------------------------- | ------------------------------------------------------------ | 58| PREFERENCES_STORAGE_XML = 0 | XML. In this type is used, data operations are performed in the memory and data is persisted after [OH_Preferences_Close](capi-oh-preferences-h.md#oh_preferences_close) is called. This type does not multi-processes operations.| 59| PREFERENCES_STORAGE_GSKV | CLKV. If this type is used, data operations are flushed on a real-time basis. This type supports multi-process operations. | 60 61 62## Function Description 63 64### OH_PreferencesOption_Create() 65 66``` 67OH_PreferencesOption *OH_PreferencesOption_Create(void) 68``` 69 70**Description** 71 72Creates a [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance and a pointer to it.<br>If this pointer is no longer required, use [OH_PreferencesOption_Destroy](capi-oh-preferences-option-h.md#oh_preferencesoption_destroy) to destroy it. Otherwise, memory leaks may occur. 73 74**Since**: 13 75 76**Returns** 77 78| Type | Description | 79| ---------------------------------------------------- | ------------------------------------------------------------ | 80| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) | Returns a pointer to the [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance created if the operation is successful; returns a null pointer otherwise.| 81 82### OH_PreferencesOption_SetFileName() 83 84``` 85int OH_PreferencesOption_SetFileName(OH_PreferencesOption *option, const char *fileName) 86``` 87 88**Description** 89 90Sets the file name for an [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance. 91 92**Since**: 13 93 94 95**Parameters** 96 97| Name | Description | 98| ------------------------------------------------------------ | ------------------------------------------------------------ | 99| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) *option | Pointer to the [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance.| 100| const char *fileName | Pointer to the file name to set. | 101 102**Returns** 103 104| Type| Description | 105| ---- | ------------------------------------------------------------ | 106| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.| 107 108**See** 109 110OH_Preferences_ErrCode 111 112### OH_PreferencesOption_SetBundleName() 113 114``` 115int OH_PreferencesOption_SetBundleName(OH_PreferencesOption *option, const char *bundleName) 116``` 117 118**Description** 119 120Sets the bundle name for an [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance. 121 122**Since**: 13 123 124 125**Parameters** 126 127| Name | Description | 128| ------------------------------------------------------------ | ------------------------------------------------------------ | 129| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) *option | Pointer to the [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance.| 130| const char *bundleName | Pointer to the bundle name to set. | 131 132**Returns** 133 134| Type| Description | 135| ---- | ------------------------------------------------------------ | 136| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.| 137 138### OH_PreferencesOption_SetDataGroupId() 139 140``` 141int OH_PreferencesOption_SetDataGroupId(OH_PreferencesOption *option, const char *dataGroupId) 142``` 143 144**Description** 145 146Sets the application group ID for an [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance.<br>After the application group ID is set, the **Preferences** instance will be created in the sandbox directory of the application group ID. The application group ID must be obtained from AppGallery. This parameter is not supported currently.<br>If the application group ID is an empty string, the **Preferences** instance will be created in the sandbox directory of the current application. 147 148**Since**: 13 149 150**Parameters** 151 152| Name | Description | 153| ------------------------------------------------------------ | ------------------------------------------------------------ | 154| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) *option | Pointer to the [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance.| 155| const char *dataGroupId | Pointer to the application group ID to set. | 156 157**Returns** 158 159| Type| Description | 160| ---- | ------------------------------------------------------------ | 161| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.| 162 163### OH_PreferencesOption_SetStorageType() 164 165``` 166int OH_PreferencesOption_SetStorageType(OH_PreferencesOption *option, Preferences_StorageType type) 167``` 168 169**Description** 170 171Sets the storage type for a **Preferences** instance. 172 173**Since**: 18 174 175 176**Parameters** 177 178| Name | Description | 179| ------------------------------------------------------------ | ---------------------------------- | 180| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) *option | Pointer to the configuration whose storage type is to set.| 181| [Preferences_StorageType](#preferences_storagetype) type | Storage type to set. | 182 183**Returns** 184 185| Type| Description | 186| ---- | ------------------------------------------------------------ | 187| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.| 188 189### OH_PreferencesOption_Destroy() 190 191``` 192int OH_PreferencesOption_Destroy(OH_PreferencesOption *option) 193``` 194 195**Description** 196 197Destroys an [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance. 198 199**Since**: 13 200 201 202**Parameters** 203 204| Name | Description | 205| ------------------------------------------------------------ | ------------------------------------------------------------ | 206| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) *option | Pointer to the [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance.| 207 208**Returns** 209 210| Type| Description | 211| ---- | ------------------------------------------------------------ | 212| int | Operation status code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.| 213