Tizen Native API  7.0

The Preference API provides functions to store and retrieve small pieces of data used for application preferences.

Required Header

#include <app_preference.h>

Overview

The Preference API provides a mechanism that saves data items in the form of key/value pairs for this application, and later retrieves them. A typical usecase would be for an application preference screen where the user can pick some values for some options. The Preference API has pairs of functions, one to set such a pair, another to retrieve the stored value given in the key. Keys are always text strings, but there are functions for each of the possible value types: integer, double, string, and boolean. There is also a function to clear all of the preferences. The Preference API provides a way to register a callback to get notified when a value for a particular key changes. It is useful to know when the display should be updated or some behavior is altered as a result. There is an iterator function which steps through all the data pairs, invoking a callback for each one.

Functions

int preference_set_int (const char *key, int value)
 Sets an integer value in the preference.
int preference_get_int (const char *key, int *value)
 Gets an integer value from the preference.
int preference_set_double (const char *key, double value)
 Sets a double value in the preference.
int preference_get_double (const char *key, double *value)
 Gets a double value from the preference.
int preference_set_string (const char *key, const char *value)
 Sets a string value in the preference.
int preference_get_string (const char *key, char **value)
 Gets a string value from the preference.
int preference_set_boolean (const char *key, bool value)
 Sets a boolean value in the preference.
int preference_get_boolean (const char *key, bool *value)
 Gets a boolean value from the preference.
int preference_remove (const char *key)
 Removes any value with the given key from the preference.
int preference_is_existing (const char *key, bool *existing)
 Checks whether the given key exists in the preference.
int preference_remove_all (void)
 Removes all key-value pairs from the preference.
int preference_set_changed_cb (const char *key, preference_changed_cb callback, void *user_data)
 Registers a callback function to be invoked when value of the given key in the preference changes.
int preference_unset_changed_cb (const char *key)
 Unregisters the callback function.
int preference_foreach_item (preference_item_cb callback, void *user_data)
 Retrieves all key-value pairs in the preference by invoking the callback function.
int preference_get_type (const char *key, preference_type_e *type)
 Gets the type of a preference.

Typedefs

typedef void(* preference_changed_cb )(const char *key, void *user_data)
 Called when the given key's value in the preference changes.
typedef bool(* preference_item_cb )(const char *key, void *user_data)
 Called to get key string, once for each key-value pair in the preference.

Typedef Documentation

typedef void(* preference_changed_cb)(const char *key, void *user_data)

Called when the given key's value in the preference changes.

When the key is added or removed, this callback function is skipped(only update can be handled).

Since :
2.3
Parameters:
[in]keyThe name of the key in the preference
[in]user_dataThe user data passed from the callback registration function
Precondition:
This function is invoked when the value of the key is overwritten after you register this callback using preference_set_changed_cb().
See also:
preference_set_changed_cb()
preference_unset_changed_cb()
preference_set_boolean()
preference_set_int()
preference_set_string()
preference_set_double()
typedef bool(* preference_item_cb)(const char *key, void *user_data)

Called to get key string, once for each key-value pair in the preference.

Since :
2.3
Remarks:
You should not free the key returned by this function.
Parameters:
[in]keyThe key of the value added to the preference
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop, otherwise false to break out of the loop
Precondition:
preference_foreach_item() will invoke this callback function.
See also:
preference_foreach_item()

Enumeration Type Documentation

Enumeration for Preference Error.

Since :
2.3
Enumerator:
PREFERENCE_ERROR_NONE 

Successful

PREFERENCE_ERROR_INVALID_PARAMETER 

Invalid parameter

PREFERENCE_ERROR_OUT_OF_MEMORY 

Out of memory

PREFERENCE_ERROR_NO_KEY 

Required key not available

PREFERENCE_ERROR_IO_ERROR 

Internal I/O Error

Enumeration for Preference type.

Since :
5.5
Enumerator:
PREFERENCE_TYPE_NONE 

None

PREFERENCE_TYPE_STRING 

String

PREFERENCE_TYPE_INT 

Int

PREFERENCE_TYPE_DOUBLE 

Double

PREFERENCE_TYPE_BOOLEAN 

Bool


Function Documentation

int preference_foreach_item ( preference_item_cb  callback,
void *  user_data 
)

Retrieves all key-value pairs in the preference by invoking the callback function.

Since :
2.3
Parameters:
[in]callbackThe callback function to get key value once for each key-value pair in the preference
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
Postcondition:
This function invokes preference_item_cb() repeatedly to get each key-value pair in the preference.
See also:
preference_item_cb()
int preference_get_boolean ( const char *  key,
bool *  value 
)

Gets a boolean value from the preference.

Since :
2.3
Parameters:
[in]keyThe name of the key to retrieve
[out]valueThe boolean value associated with the given key
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_NO_KEYRequired key not available
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
See also:
preference_set_boolean()
int preference_get_double ( const char *  key,
double *  value 
)

Gets a double value from the preference.

Since :
2.3
Parameters:
[in]keyThe name of the key to retrieve
[out]valueThe double value associated with the given key
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_NO_KEYRequired key not available
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
See also:
preference_set_double()
int preference_get_int ( const char *  key,
int *  value 
)

Gets an integer value from the preference.

Since :
2.3
Parameters:
[in]keyThe name of the key to retrieve
[out]valueThe int value for the given key
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_NO_KEYRequired key not available
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
See also:
preference_set_int()
int preference_get_string ( const char *  key,
char **  value 
)

Gets a string value from the preference.

Since :
2.3
Remarks:
value must be released using free().
Parameters:
[in]keyThe name of the key to retrieve
[out]valueThe string value associated with the given key
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_NO_KEYRequired key not available
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
See also:
preference_set_string()
int preference_get_type ( const char *  key,
preference_type_e type 
)

Gets the type of a preference.

Since :
5.5
Parameters:
[in]keyThe name of the key
[out]typeThe preference type
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_NO_KEYRequired key not available
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
See also:
preference_type_e
int preference_is_existing ( const char *  key,
bool *  existing 
)

Checks whether the given key exists in the preference.

Since :
2.3
Parameters:
[in]keyThe name of the key to check
[out]existingIf true the key exists in the preference, otherwise false
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
int preference_remove ( const char *  key)

Removes any value with the given key from the preference.

Since :
2.3
Parameters:
[in]keyThe name of the key to remove
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_NO_KEYRequired key not available
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
int preference_remove_all ( void  )

Removes all key-value pairs from the preference.

Since :
2.3
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
See also:
preference_remove()
int preference_set_boolean ( const char *  key,
bool  value 
)

Sets a boolean value in the preference.

Since :
2.3
Parameters:
[in]keyThe name of the key to modify
[in]valueThe new boolean value associated with the given key
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
See also:
preference_get_boolean()
int preference_set_changed_cb ( const char *  key,
preference_changed_cb  callback,
void *  user_data 
)

Registers a callback function to be invoked when value of the given key in the preference changes.

Since :
2.3
Parameters:
[in]keyThe name of the key to monitor
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_NO_KEYRequired key not available
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
Postcondition:
preference_changed_cb() will be invoked.
See also:
preference_unset_changed_cb()
preference_changed_cb()
int preference_set_double ( const char *  key,
double  value 
)

Sets a double value in the preference.

Since :
2.3
Parameters:
[in]keyThe name of the key to modify
[in]valueThe new double value associated with the given key
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
See also:
preference_get_double()
int preference_set_int ( const char *  key,
int  value 
)

Sets an integer value in the preference.

Since :
2.3
Parameters:
[in]keyThe name of the key to modify
[in]valueThe new int value for the given key
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
See also:
preference_get_int()
int preference_set_string ( const char *  key,
const char *  value 
)

Sets a string value in the preference.

It makes a deep copy of the added string value.

Since :
2.3
Parameters:
[in]keyThe name of the key to modify
[in]valueThe new string value associated with the given key
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
See also:
preference_get_string()
int preference_unset_changed_cb ( const char *  key)

Unregisters the callback function.

Since :
2.3
Parameters:
[in]keyThe name of the key to monitor
Returns:
0 on success, otherwise a negative error value
Return values:
PREFERENCE_ERROR_NONESuccessful
PREFERENCE_ERROR_INVALID_PARAMETERInvalid parameter
PREFERENCE_ERROR_OUT_OF_MEMORYOut of memory
PREFERENCE_ERROR_NO_KEYRequired key not available
PREFERENCE_ERROR_IO_ERRORInternal I/O Error
See also:
preference_set_changed_cb()