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.
|
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.
|
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.
Typedef Documentation
Called to get key string, once for each key-value pair in the preference.
- Since :
- 2.3
- Parameters:
-
[in] | key | The key of the value added to the preference |
[in] | value | The value associated with the key |
[in] | user_data | The 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
|
Function Documentation
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:
-
- Postcondition:
- This function invokes preference_item_cb() repeatedly to get each key-value pair in the preference.
- See also:
- preference_item_cb()
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:
-
- See also:
- preference_set_boolean()
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:
-
- See also:
- preference_set_double()
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:
-
- See also:
- preference_set_int()
Gets a string value from the preference.
- Since :
- 2.3
- 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:
-
- See also:
- preference_set_string()
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, otherwise false |
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
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:
-
Removes all key-value pairs from the preference.
- Since :
- 2.3
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
- See also:
- preference_remove()
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:
-
- See also:
- preference_get_boolean()
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:
-
- Postcondition:
- preference_changed_cb() will be invoked.
- See also:
- preference_unset_changed_cb()
-
preference_changed_cb()
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:
-
- See also:
- preference_get_double()
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:
-
- See also:
- preference_get_int()
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:
-
- See also:
- preference_get_string()
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:
-
- See also:
- preference_set_changed_cb()