oh_preferences.h

Overview

Provides APIs and structs for accessing the Preferences object.

File to include: <database/preferences/oh_preferences.h>

Library: libohpreferences.so

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Since: 13

Related module: Preferences

Summary

Structs

Name	typedef Keyword	Description
OH_Preferences	OH_Preferences	Defines a struct for a Preferences object.

Functions

Name	typedef Keyword	Description
typedef void (OH_PreferencesDataObserver)(void context, const OH_PreferencesPair *pairs, uint32_t count)	OH_PreferencesDataObserver	Defines a struct for the callback for data changes.
OH_Preferences OH_Preferences_Open(OH_PreferencesOption option, int *errCode)	-	Opens a Preferences instance and creates a pointer to it. If this pointer is no longer required, use OH_Preferences_Close to close the instance.
int OH_Preferences_Close(OH_Preferences *preference)	-	Closes a Preferences instance.
int OH_Preferences_GetInt(OH_Preferences preference, const char key, int *value)	-	Obtains an integer corresponding to the specified key in a Preferences instance.
int OH_Preferences_GetBool(OH_Preferences preference, const char key, bool *value)	-	Obtains a Boolean value corresponding to the specified key in a Preferences instance.
int OH_Preferences_GetString(OH_Preferences preference, const char key, char *value, uint32_t valueLen)	-	Obtains a string corresponding to the specified key in a Preferences instance.
void OH_Preferences_FreeString(char *string)	-	Releases a string obtained from a Preferences instance.
int OH_Preferences_SetInt(OH_Preferences preference, const char key, int value)	-	Sets an integer based on the specified key in a Preferences instance.
int OH_Preferences_SetBool(OH_Preferences preference, const char key, bool value)	-	Sets a Boolean value based on the specified key in a Preferences instance.
int OH_Preferences_SetString(OH_Preferences preference, const char key, const char *value)	-	Sets a string based on the specified key in a Preferences instance.
int OH_Preferences_Delete(OH_Preferences preference, const char key)	-	Deletes the KV data corresponding to the specified key from a Preferences instance.
int OH_Preferences_RegisterDataObserver(OH_Preferences preference, void context,OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount)	-	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.
int OH_Preferences_UnregisterDataObserver(OH_Preferences preference, void context,OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount)	-	Unsubscribes from data changes of the specified keys.
int OH_Preferences_IsStorageTypeSupported(Preferences_StorageType type, bool *isSupported)	-	Checks whether the specified storage type is supported.
int OH_Preferences_DeletePreferences(OH_PreferencesOption *option)	-	Deletes the specified Preferences object.
int OH_Preferences_SetValue(OH_Preferences preference, const char key, OH_PreferencesValue *value)	-	Sets OH_PreferencesValue in the Preferences object.
int OH_Preferences_GetValue(OH_Preferences preference, const char key, OH_PreferencesValue **value)	-	Obtains the value from the Preferences object based on the given key.
int OH_Preferences_GetAll(OH_Preferences preference, OH_PreferencesPair pairs, uint32_t count)	-	Obtains all the values from the Preferences object.
bool OH_Preferences_HasKey(OH_Preferences preference, const char key)	-	Checks whether the Preferences object contains KV data matching the specified key. Returns true if present, and false otherwise.
int OH_Preferences_Flush(OH_Preferences *preference)	-	Saves the cache of the OH_Preferences object to an XML file.
int OH_Preferences_ClearCache(OH_Preferences *preference)	-	Clears all values in the cache of the OH_Preferences object.
int OH_Preferences_RegisterMultiProcessDataObserver(OH_Preferences preference, void context, OH_PreferencesDataObserver observer)	-	Registers a multi-process data observer for the Preferences object.
int OH_Preferences_UnregisterMultiProcessDataObserver(OH_Preferences preference, void context, OH_PreferencesDataObserver observer)	-	Unregisters the multi-process data observer of the Preferences object.

Function Description

OH_PreferencesDataObserver()

typedef void (*OH_PreferencesDataObserver)(void *context, const OH_PreferencesPair *pairs, uint32_t count)

Description

Defines a struct for the callback for data changes.

Since: 13

Parameters

Name	Description
void *context	Pointer to the application context.
const OH_PreferencesPair *pairs	Pointer to the changed KV data.
uint32_t count	Number of KV pairs changed.

OH_Preferences_Open()

OH_Preferences *OH_Preferences_Open(OH_PreferencesOption *option, int *errCode)

Description

Opens a Preferences instance and creates a pointer to it.
If this pointer is no longer required, use OH_Preferences_Close to close the instance.

Since: 13

Parameters

Name

Description

OH_PreferencesOption *option

Pointer to the OH_PreferencesOption instance.

int *errCode

Pointer to the error code returned. For details, see OH_Preferences_ErrCode.
PREFERENCES_OK indicates the operation is successful.
PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified.
PREFERENCES_ERROR_NOT_SUPPORTED indicates the system capability is not supported.
PREFERENCES_ERROR_DELETE_FILE indicates the file fails to be deleted.
PREFERENCES_ERROR_STORAGE indicates the storage is abnormal.
PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation.

Returns

Type	Description
OH_Preferences	Returns a pointer to the OH_Preferences instance opened if the operation is successful; returns a null pointer otherwise.

OH_Preferences_Close()

int OH_Preferences_Close(OH_Preferences *preference)

Description

Closes a Preferences instance.

Since: 13

Parameters

Name	Description
OH_Preferences *preference	Pointer to the OH_Preferences instance to close.

Returns

Type	Description
int	Returns an error code. For details, see OH_Preferences_ErrCode. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates the storage is abnormal. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation.

OH_Preferences_GetInt()

int OH_Preferences_GetInt(OH_Preferences *preference, const char *key, int *value)

Description

Obtains an integer corresponding to the specified key in a Preferences instance.

Since: 13

Parameters

Name	Description
OH_Preferences *preference	Pointer to the OH_Preferences instance.
const char *key	Pointer to the key of the value to obtain.
int *value	Pointer to the integer value obtained.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates the storage is abnormal. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation. PREFERENCES_ERROR_KEY_NOT_FOUND indicates the specified key does not exist.

OH_Preferences_GetBool()

int OH_Preferences_GetBool(OH_Preferences *preference, const char *key, bool *value)

Description

Obtains a Boolean value corresponding to the specified key in a Preferences instance.

Since: 13

Parameters

Name	Description
OH_Preferences *preference	Pointer to the OH_Preferences instance.
const char *key	Pointer to the key of the value to obtain.
bool *value	Pointer to the Boolean value obtained.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates the storage is abnormal. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation. PREFERENCES_ERROR_KEY_NOT_FOUND indicates the specified key does not exist.

OH_Preferences_GetString()

int OH_Preferences_GetString(OH_Preferences *preference, const char *key, char **value, uint32_t *valueLen)

Description

Obtains a string corresponding to the specified key in a Preferences instance.

Since: 13

Parameters

Name	Description
OH_Preferences *preference	Pointer to the OH_Preferences instance.
const char *key	Pointer to the key of the value to obtain.
char **value	Double pointer to the string obtained. If the string is not required, you can use OH_Preferences_FreeString to free the string (release the memory occupied by the string).
uint32_t *valueLen	Pointer to the length of the string obtained.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates the storage is abnormal. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation. PREFERENCES_ERROR_KEY_NOT_FOUND indicates the specified key does not exist.

OH_Preferences_FreeString()

void OH_Preferences_FreeString(char *string)

Description

Releases a string obtained from a Preferences instance.

Since: 13

Parameters

Name	Description
char *string	Pointer to the string to release.

OH_Preferences_SetInt()

int OH_Preferences_SetInt(OH_Preferences *preference, const char *key, int value)

Description

Sets an integer based on the specified key in a Preferences instance.

Since: 13

Parameters

Name	Description
OH_Preferences *preference	Pointer to the OH_Preferences instance.
const char *key	Pointer to the key of the value to set.
int value	Integer value to be set.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates the storage is abnormal. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation.

OH_Preferences_SetBool()

int OH_Preferences_SetBool(OH_Preferences *preference, const char *key, bool value)

Description

Sets a Boolean value based on the specified key in a Preferences instance.

Since: 13

Parameters

Name	Description
OH_Preferences *preference	Pointer to the OH_Preferences instance.
const char *key	Pointer to the key of the value to set.
bool value	Boolean value to be set.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates the storage is abnormal. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation.

OH_Preferences_SetString()

int OH_Preferences_SetString(OH_Preferences *preference, const char *key, const char *value)

Description

Sets a string based on the specified key in a Preferences instance.

Since: 13

Parameters

Name	Description
OH_Preferences *preference	Pointer to the OH_Preferences instance.
const char *key	Pointer to the key of the value to set.
const char *value	Pointer to the string to set.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates the storage is abnormal. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation.

OH_Preferences_Delete()

int OH_Preferences_Delete(OH_Preferences *preference, const char *key)

Description

Deletes the KV data corresponding to the specified key from a Preferences instance.

Since: 13

Parameters

Name	Description
OH_Preferences *preference	Pointer to the OH_Preferences instance.
const char *key	Pointer to the key of the KV pair to delete.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates the storage is abnormal. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation.

OH_Preferences_RegisterDataObserver()

int OH_Preferences_RegisterDataObserver(OH_Preferences *preference, void *context,OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount)

Description

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.

Since: 13

Parameters

Name	Description
OH_Preferences *preference	Pointer to the OH_Preferences instance.
void *context	Pointer to the application context.
OH_PreferencesDataObserver observer	OH_PreferencesDataObserver callback to be invoked when data changes.
const char *keys[]	Array of keys.
uint32_t keyCount	Number of keys.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates the storage is abnormal. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation. PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT indicates a failure in obtaining the data change subscription service.

Type

Description

int

Returns an error code.
PREFERENCES_OK indicates the operation is successful.
PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified.
PREFERENCES_ERROR_STORAGE indicates the storage is abnormal.
PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation.
PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT indicates a failure in obtaining the data change subscription service.

OH_Preferences_UnregisterDataObserver()

int OH_Preferences_UnregisterDataObserver(OH_Preferences *preference, void *context,OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount)

Description

Unsubscribes from data changes of the specified keys.

Since: 13

Parameters

Name	Description
OH_Preferences *preference	Pointer to the OH_Preferences instance.
void *context	Pointer to the application context.
OH_PreferencesDataObserver observer	OH_PreferencesDataObserver callback to be invoked when data changes.
const char *keys[]	Pointer to the keys whose changes are not observed.
uint32_t keyCount	Number of keys.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates the storage is abnormal. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation.

OH_Preferences_IsStorageTypeSupported()

int OH_Preferences_IsStorageTypeSupported(Preferences_StorageType type, bool *isSupported)

Since: 18

Parameters

Name	Description
Preferences_StorageType type	Storage type to check.
bool *isSupported	Pointer to the check result. The value true means the storage type is supported; the value false means the opposite.

Returns

Type	Description
int	Return an operation status code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified.

OH_Preferences_DeletePreferences()

int OH_Preferences_DeletePreferences(OH_PreferencesOption *option)

Description

Deletes the specified Preferences object.

Since: 23

Parameters

Name	Description
OH_PreferencesOption *option	Pointer to the OH_PreferencesOption instance.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_NOT_SUPPORTED indicates the system capability is not supported. PREFERENCES_ERROR_DELETE_FILE indicates the file fails to be deleted.

OH_Preferences_SetValue()

int OH_Preferences_SetValue(OH_Preferences *preference, const char *key, OH_PreferencesValue *value)

Description

Sets OH_PreferencesValue in the Preferences object.

Since: 23

Parameters

Name	Description
OH_Preferences *preference	Pointer to the target OH_Preferences instance.
const char *key	Pointer to the key of the value to set.
OH_PreferencesValue *value	Pointer to the OH_PreferencesValue value to set.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates a storage exception. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation.

OH_Preferences_GetValue()

int OH_Preferences_GetValue(OH_Preferences *preference, const char *key, OH_PreferencesValue **value)

Description

Obtains the value from the Preferences object based on the given key.

Since: 23

Parameters

Name	Description
OH_Preferences *preference	Pointer to the target OH_Preferences instance.
const char *key	Pointer to the key of the value to obtain.
OH_PreferencesValue **value	Double pointer to OH_PreferencesValue.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates a storage exception. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation. PREFERENCES_ERROR_KEY_NOT_FOUND indicates the specified key does not exist.

OH_Preferences_GetAll()

int OH_Preferences_GetAll(OH_Preferences *preference, OH_PreferencesPair **pairs, uint32_t *count)

Description

Obtains all the values from the Preferences object.

Since: 23

Parameters

Name	Description
OH_Preferences *preference	Pointer to the target OH_Preferences instance.
OH_PreferencesPair **pairs	Pointer to the KV data to obtain. When the KV data is no longer needed, call OH_Preferences_FreeString to free the memory.
uint32_t *count	Pointer to the count of all obtained values.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates a storage exception. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation. PREFERENCES_ERROR_KEY_NOT_FOUND indicates the specified key does not exist.

OH_Preferences_HasKey()

bool OH_Preferences_HasKey(OH_Preferences *preference, const char *key)

Description

Checks whether the Preferences object contains KV data matching the specified key. Returns true if present, and false otherwise.

Since: 23

Parameters

Name	Description
OH_Preferences *preference	Pointer to the target OH_Preferences instance.
const char *key	Pointer to the key to check.

Returns

Type	Description
bool	Returns true if the Preferences object contains KV data that matches the specified key; returns false otherwise.

OH_Preferences_Flush()

int OH_Preferences_Flush(OH_Preferences *preference)

Description

Saves the cache of the OH_Preferences object to an XML file.

Since: 23

Parameters

Name	Description
OH_Preferences *preference	Pointer to the target OH_Preferences instance.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_NOT_SUPPORTED indicates the system capability is not supported.

OH_Preferences_ClearCache()

int OH_Preferences_ClearCache(OH_Preferences *preference)

Description

Clears all values in the cache of the OH_Preferences object.

Since: 23

Parameters

Name	Description
OH_Preferences *preference	Pointer to the target OH_Preferences instance.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_NOT_SUPPORTED indicates the system capability is not supported.

OH_Preferences_RegisterMultiProcessDataObserver()

int OH_Preferences_RegisterMultiProcessDataObserver(OH_Preferences *preference, void *context, OH_PreferencesDataObserver observer)

Description

Registers a multi-process data observer for the Preferences object.

Since: 23

Parameters

Name	Description
OH_Preferences *preference	Pointer to the target OH_Preferences instance.
void *context	Pointer to the data observer context.
OH_PreferencesDataObserver observer	The OH_PreferencesDataObserver callback function to register.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates a storage exception. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation. PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT indicates a failure in obtaining the data change subscription service.

Type

Description

int

Returns an error code.
PREFERENCES_OK indicates the operation is successful.
PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified.
PREFERENCES_ERROR_STORAGE indicates a storage exception.
PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation.
PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT indicates a failure in obtaining the data change subscription service.

OH_Preferences_UnregisterMultiProcessDataObserver()

int OH_Preferences_UnregisterMultiProcessDataObserver(OH_Preferences *preference, void *context, OH_PreferencesDataObserver observer)

Description

Unregisters the multi-process data observer of the Preferences object.

Since: 23

Parameters

Name	Description
OH_Preferences *preference	Pointer to the target OH_Preferences instance.
void *context	Pointer to the data observer context.
OH_PreferencesDataObserver observer	The OH_PreferencesDataObserver callback function to unregister.

Returns

Type	Description
int	Returns an error code. PREFERENCES_OK indicates the operation is successful. PREFERENCES_ERROR_INVALID_PARAM indicates invalid parameters are specified. PREFERENCES_ERROR_STORAGE indicates a storage exception. PREFERENCES_ERROR_MALLOC indicates a failure in memory allocation.