1# oh_preferences.h 2 3## Overview 4 5Provides APIs and structs for accessing the **Preferences** object. 6 7**File to include**: <database/preferences/oh_preferences.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_Preferences](capi-preferences-oh-preferences.md) | OH_Preferences | Defines a struct for a **Preferences** object.| 24 25### Functions 26 27| Name | typedef Keyword | Description | 28| ------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------ | 29| [typedef void (\*OH_PreferencesDataObserver)(void *context, const OH_PreferencesPair *pairs, uint32_t count)](#oh_preferencesdataobserver) | OH_PreferencesDataObserver | Defines a struct for the callback for data changes. | 30| [OH_Preferences *OH_Preferences_Open(OH_PreferencesOption *option, int *errCode)](#oh_preferences_open) | - | Opens a **Preferences** instance and creates a pointer to it.<br>If this pointer is no longer required, use [OH_Preferences_Close](capi-oh-preferences-h.md#oh_preferences_close) to close the instance.| 31| [int OH_Preferences_Close(OH_Preferences *preference)](#oh_preferences_close) | - | Closes a **Preferences** instance. | 32| [int OH_Preferences_GetInt(OH_Preferences *preference, const char *key, int *value)](#oh_preferences_getint) | - | Obtains an integer corresponding to the specified key in a **Preferences** instance. | 33| [int OH_Preferences_GetBool(OH_Preferences *preference, const char *key, bool *value)](#oh_preferences_getbool) | - | Obtains a Boolean value corresponding to the specified key in a **Preferences** instance. | 34| [int OH_Preferences_GetString(OH_Preferences *preference, const char *key, char **value, uint32_t *valueLen)](#oh_preferences_getstring) | - | Obtains a string corresponding to the specified key in a **Preferences** instance. | 35| [void OH_Preferences_FreeString(char *string)](#oh_preferences_freestring) | - | Releases a string obtained from a **Preferences** instance. | 36| [int OH_Preferences_SetInt(OH_Preferences *preference, const char *key, int value)](#oh_preferences_setint) | - | Sets an integer based on the specified key in a **Preferences** instance. | 37| [int OH_Preferences_SetBool(OH_Preferences *preference, const char *key, bool value)](#oh_preferences_setbool) | - | Sets a Boolean value based on the specified key in a **Preferences** instance. | 38| [int OH_Preferences_SetString(OH_Preferences *preference, const char *key, const char *value)](#oh_preferences_setstring) | - | Sets a string based on the specified key in a **Preferences** instance. | 39| [int OH_Preferences_Delete(OH_Preferences *preference, const char *key)](#oh_preferences_delete) | - | Deletes the KV data corresponding to the specified key from a **Preferences** instance. | 40| [int OH_Preferences_RegisterDataObserver(OH_Preferences *preference, void *context,OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount)](#oh_preferences_registerdataobserver) | - | Subscribes to data changes of the specified keys. If the value of the specified key changes, a callback will be invoked after **OH_Preferences_Close()** is called.| 41| [int OH_Preferences_UnregisterDataObserver(OH_Preferences *preference, void *context,OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount)](#oh_preferences_unregisterdataobserver) | - | Unsubscribes from data changes of the specified keys. | 42| [int OH_Preferences_IsStorageTypeSupported(Preferences_StorageType type, bool *isSupported)](#oh_preferences_isstoragetypesupported) | - | Checks whether the specified storage type is supported. | 43 44## Function Description 45 46### OH_PreferencesDataObserver() 47 48``` 49typedef void (*OH_PreferencesDataObserver)(void *context, const OH_PreferencesPair *pairs, uint32_t count) 50``` 51 52**Description** 53 54Defines a struct for the callback for data changes. 55 56**Since**: 13 57 58 59**Parameters** 60 61| Name | Description | 62| ------------------------------------------------------------ | ------------------------ | 63| void *context | Pointer to the application context. | 64| const [OH_PreferencesPair](capi-preferences-oh-preferencespair.md) *pairs | Pointer to the changed KV data.| 65| uint32_t count | Number of KV pairs changed.| 66 67### OH_Preferences_Open() 68 69``` 70OH_Preferences *OH_Preferences_Open(OH_PreferencesOption *option, int *errCode) 71``` 72 73**Description** 74 75Opens a **Preferences** instance and creates a pointer to it.<br>If this pointer is no longer required, use [OH_Preferences_Close](capi-oh-preferences-h.md#oh_preferences_close) to close the instance. 76 77**Since**: 13 78 79 80**Parameters** 81 82| Name | Description | 83| ------------------------------------------------------------ | ------------------------------------------------------------ | 84| [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) *option | Pointer to the [OH_PreferencesOption](capi-preferences-oh-preferencesoption.md) instance.| 85| int *errCode | Pointer to the error code returned. For details, see [OH_Preferences_ErrCode](capi-oh-preferences-err-code-h.md#oh_preferences_errcode).<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_NOT_SUPPORTED** indicates the system capability is not supported.<br>**PREFERENCES_ERROR_DELETE_FILE** indicates the file fails to be deleted.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.| 86 87**Returns** 88 89| Type | Description | 90| ---------------------------------------- | ------------------------------------------------------------ | 91| [OH_Preferences](capi-preferences-oh-preferences.md) | Returns a pointer to the [OH_Preferences](capi-preferences-oh-preferences.md) instance opened if the operation is successful; returns a null pointer otherwise.| 92 93### OH_Preferences_Close() 94 95``` 96int OH_Preferences_Close(OH_Preferences *preference) 97``` 98 99**Description** 100 101Closes a **Preferences** instance. 102 103**Since**: 13 104 105 106**Parameters** 107 108| Name | Description | 109| ---------------------------------------------------- | ------------------------------------------------------------ | 110| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | Pointer to the [OH_Preferences](capi-preferences-oh-preferences.md) instance to close.| 111 112**Returns** 113 114| Type| Description | 115| ---- | ------------------------------------------------------------ | 116| int | Error code. For details, see [OH_Preferences_ErrCode](capi-oh-preferences-err-code-h.md#oh_preferences_errcode).<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.| 117 118### OH_Preferences_GetInt() 119 120``` 121int OH_Preferences_GetInt(OH_Preferences *preference, const char *key, int *value) 122``` 123 124**Description** 125 126Obtains an integer corresponding to the specified key in a **Preferences** instance. 127 128**Since**: 13 129 130 131**Parameters** 132 133| Name | Description | 134| ---------------------------------------------------- | ------------------------------------------------------------ | 135| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | Pointer to the [OH_Preferences](capi-preferences-oh-preferences.md) instance.| 136| const char *key | Pointer to the key of the value to obtain. | 137| int *value | Pointer to the integer value obtained. | 138 139**Returns** 140 141| Type| Description | 142| ---- | ------------------------------------------------------------ | 143| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.<br>**PREFERENCES_ERROR_KEY_NOT_FOUND** indicates the specified key does not exist.| 144 145### OH_Preferences_GetBool() 146 147``` 148int OH_Preferences_GetBool(OH_Preferences *preference, const char *key, bool *value) 149``` 150 151**Description** 152 153Obtains a Boolean value corresponding to the specified key in a **Preferences** instance. 154 155**Since**: 13 156 157 158**Parameters** 159 160| Name | Description | 161| ---------------------------------------------------- | ------------------------------------------------------------ | 162| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | Pointer to the [OH_Preferences](capi-preferences-oh-preferences.md) instance.| 163| const char *key | Pointer to the key of the value to obtain. | 164| bool *value | Pointer to the Boolean value obtained. | 165 166**Returns** 167 168| Type| Description | 169| ---- | ------------------------------------------------------------ | 170| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.<br>**PREFERENCES_ERROR_KEY_NOT_FOUND** indicates the specified key does not exist.| 171 172### OH_Preferences_GetString() 173 174``` 175int OH_Preferences_GetString(OH_Preferences *preference, const char *key, char **value, uint32_t *valueLen) 176``` 177 178**Description** 179 180Obtains a string corresponding to the specified key in a **Preferences** instance. 181 182**Since**: 13 183 184 185**Parameters** 186 187| Name | Description | 188| ---------------------------------------------------- | ------------------------------------------------------------ | 189| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | Pointer to the [OH_Preferences](capi-preferences-oh-preferences.md) instance.| 190| const char *key | Pointer to the key of the value to obtain. | 191| char **value | Double pointer to the string obtained. If the string is not required, you can use [OH_Preferences_FreeString](capi-oh-preferences-h.md#oh_preferences_freestring) to free the string (release the memory occupied by the string).| 192| uint32_t *valueLen | Pointer to the length of the string obtained. | 193 194**Returns** 195 196| Type| Description | 197| ---- | ------------------------------------------------------------ | 198| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.<br>**PREFERENCES_ERROR_KEY_NOT_FOUND** indicates the specified key does not exist.| 199 200### OH_Preferences_FreeString() 201 202``` 203void OH_Preferences_FreeString(char *string) 204``` 205 206**Description** 207 208Releases a string obtained from a **Preferences** instance. 209 210**Since**: 13 211 212 213**Parameters** 214 215| Name | Description | 216| ------------ | ---------------------- | 217| char *string | Pointer to the string to release.| 218 219### OH_Preferences_SetInt() 220 221``` 222int OH_Preferences_SetInt(OH_Preferences *preference, const char *key, int value) 223``` 224 225**Description** 226 227Sets an integer based on the specified key in a **Preferences** instance. 228 229**Since**: 13 230 231 232**Parameters** 233 234| Name | Description | 235| ---------------------------------------------------- | ------------------------------------------------------------ | 236| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | Pointer to the [OH_Preferences](capi-preferences-oh-preferences.md) instance.| 237| const char *key | Pointer to the key of the value to set. | 238| int value | Integer value to be set. | 239 240**Returns** 241 242| Type| Description | 243| ---- | ------------------------------------------------------------ | 244| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.| 245 246### OH_Preferences_SetBool() 247 248``` 249int OH_Preferences_SetBool(OH_Preferences *preference, const char *key, bool value) 250``` 251 252**Description** 253 254Sets a Boolean value based on the specified key in a **Preferences** instance. 255 256**Since**: 13 257 258 259**Parameters** 260 261| Name | Description | 262| ---------------------------------------------------- | ------------------------------------------------------------ | 263| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | Pointer to the [OH_Preferences](capi-preferences-oh-preferences.md) instance.| 264| const char *key | Pointer to the key of the value to set. | 265| bool value | Boolean value to be set. | 266 267**Returns** 268 269| Type| Description | 270| ---- | ------------------------------------------------------------ | 271| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.| 272 273### OH_Preferences_SetString() 274 275``` 276int OH_Preferences_SetString(OH_Preferences *preference, const char *key, const char *value) 277``` 278 279**Description** 280 281Sets a string based on the specified key in a **Preferences** instance. 282 283**Since**: 13 284 285 286**Parameters** 287 288| Name | Description | 289| ---------------------------------------------------- | ------------------------------------------------------------ | 290| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | Pointer to the [OH_Preferences](capi-preferences-oh-preferences.md) instance.| 291| const char *key | Pointer to the key of the value to set. | 292| const char *value | Pointer to the string to set. | 293 294**Returns** 295 296| Type| Description | 297| ---- | ------------------------------------------------------------ | 298| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.| 299 300### OH_Preferences_Delete() 301 302``` 303int OH_Preferences_Delete(OH_Preferences *preference, const char *key) 304``` 305 306**Description** 307 308Deletes the KV data corresponding to the specified key from a **Preferences** instance. 309 310**Since**: 13 311 312 313**Parameters** 314 315| Name | Description | 316| ---------------------------------------------------- | ------------------------------------------------------------ | 317| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | Pointer to the [OH_Preferences](capi-preferences-oh-preferences.md) instance.| 318| const char *key | Pointer to the key of the KV pair to delete. | 319 320**Returns** 321 322| Type| Description | 323| ---- | ------------------------------------------------------------ | 324| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.| 325 326**See** 327 328OH_Preferences_ErrCode 329 330### OH_Preferences_RegisterDataObserver() 331 332``` 333int OH_Preferences_RegisterDataObserver(OH_Preferences *preference, void *context,OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount) 334``` 335 336**Description** 337 338Subscribes to data changes of the specified keys. If the value of the specified key changes, a callback will be invoked after **OH_Preferences_Close()** is called. 339 340**Since**: 13 341 342 343**Parameters** 344 345| Name | Description | 346| ------------------------------------------------------------ | ------------------------------------------------------------ | 347| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | Pointer to the [OH_Preferences](capi-preferences-oh-preferences.md) instance.| 348| void *context | Pointer to the application context. | 349| [OH_PreferencesDataObserver](#oh_preferencesdataobserver) observer | [OH_PreferencesDataObserver](capi-oh-preferences-h.md#oh_preferencesdataobserver) callback to register.| 350| const char *keys[] | Pointer to the keys of the data to be observed. | 351| uint32_t keyCount | Number of keys observed. | 352 353**Returns** 354 355| Type| Description | 356| ---- | ------------------------------------------------------------ | 357| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.<br>**PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT** indicates a failure in obtaining the data change subscription service.| 358 359### OH_Preferences_UnregisterDataObserver() 360 361``` 362int OH_Preferences_UnregisterDataObserver(OH_Preferences *preference, void *context,OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount) 363``` 364 365**Description** 366 367Unsubscribes from data changes of the specified keys. 368 369**Since**: 13 370 371 372**Parameters** 373 374| Name | Description | 375| ------------------------------------------------------------ | ------------------------------------------------------------ | 376| [OH_Preferences](capi-preferences-oh-preferences.md) *preference | Pointer to the [OH_Preferences](capi-preferences-oh-preferences.md) instance.| 377| void *context | Pointer to the application context. | 378| [OH_PreferencesDataObserver](#oh_preferencesdataobserver) observer | [OH_PreferencesDataObserver](capi-oh-preferences-h.md#oh_preferencesdataobserver) callback to unregister.| 379| const char *keys[] | Pointer to the keys of the values whose changes are not observed. | 380| uint32_t keyCount | Number of keys. | 381 382**Returns** 383 384| Type| Description | 385| ---- | ------------------------------------------------------------ | 386| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.| 387 388**See** 389 390OH_Preferences_ErrCode 391 392### OH_Preferences_IsStorageTypeSupported() 393 394``` 395int OH_Preferences_IsStorageTypeSupported(Preferences_StorageType type, bool *isSupported) 396``` 397 398 399**Since**: 18 400 401 402**Parameters** 403 404| Name | Description | 405| ------------------------------------------------------------ | ------------------------------------------------------------ | 406| [Preferences_StorageType](capi-oh-preferences-option-h.md#preferences_storagetype) type | Storage type to check. | 407| bool *isSupported | Pointer to the check result. The value **true** means the storage type is supported; the value **false** means the opposite.| 408 409**Returns** 410 411| Type| Description | 412| ---- | ------------------------------------------------------------ | 413| int | Operation status code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.| 414