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] key The name of the key in the preference [in] user_data The 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().
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] key The key of the value added to the preference [in] user_data The user data passed from the foreach function
- Returns:
true
to continue with the next iteration of the loop, otherwisefalse
to break out of the loop
- Precondition:
- preference_foreach_item() will invoke this callback function.
- See also:
- preference_foreach_item()
Enumeration Type Documentation
enum preference_error_e |
enum preference_type_e |
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] callback The callback function to get key value once for each key-value pair in the preference [in] user_data The user data to be passed to the callback function
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
PREFERENCE_ERROR_NONE Successful PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter PREFERENCE_ERROR_IO_ERROR Internal 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] key The name of the key to retrieve [out] value The boolean
value associated with the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
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
- 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] key The name of the key to retrieve [out] value The double
value associated with the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
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
- 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] key The name of the key to retrieve [out] value The int
value for the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
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
- 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] key The name of the key to retrieve [out] value The string
value associated with the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
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
- 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] key The name of the key [out] type The preference type
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
PREFERENCE_ERROR_NONE Successful PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter PREFERENCE_ERROR_NO_KEY Required key not available PREFERENCE_ERROR_IO_ERROR Internal I/O Error PREFERENCE_ERROR_OUT_OF_MEMORY Out 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] key The name of the key to check [out] existing If true
the key exists in the preference, otherwisefalse
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
PREFERENCE_ERROR_NONE Successful PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory PREFERENCE_ERROR_IO_ERROR Internal I/O Error
int preference_remove | ( | const char * | key | ) |
Removes any value with the given key from the preference.
- Since :
- 2.3
- Parameters:
-
[in] key The name of the key to remove
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
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
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_NONE Successful PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory PREFERENCE_ERROR_IO_ERROR Internal 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] key The name of the key to modify [in] value The new boolean
value associated with the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
PREFERENCE_ERROR_NONE Successful PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory PREFERENCE_ERROR_IO_ERROR Internal 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] key The name of the key to monitor [in] callback The callback function to register [in] user_data The user data to be passed to the callback function
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
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
- Postcondition:
- preference_changed_cb() will be invoked.
int preference_set_double | ( | const char * | key, |
double | value | ||
) |
Sets a double value in the preference.
- Since :
- 2.3
- Parameters:
-
[in] key The name of the key to modify [in] value The new double
value associated with the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
PREFERENCE_ERROR_NONE Successful PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory PREFERENCE_ERROR_IO_ERROR Internal 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] key The name of the key to modify [in] value The new int
value for the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
PREFERENCE_ERROR_NONE Successful PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory PREFERENCE_ERROR_IO_ERROR Internal 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] key The name of the key to modify [in] value The new string
value associated with the given key
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
PREFERENCE_ERROR_NONE Successful PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory PREFERENCE_ERROR_IO_ERROR Internal 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] key The name of the key to monitor
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
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
- See also:
- preference_set_changed_cb()