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.

Storing and Retrieving Simple Type Variables

To store a variable, you must create a key-value pair. Before storing or retrieving a variable, check whether it exists using the preference_is_existing() function.

 #include <app_preference.h>
 #include <dlog.h>

 void
 manage_integer_preference(void)
 {
     const char *integer_key = "integer_key";
     int integer_value = 1;
     int integer_output;
     bool existing;
     
     // Set integer value
     preference_set_int(integer_key, integer_value);
     
     // Check if key exists
     preference_is_existing(integer_key, &existing);
     
     // Get integer value
     if (existing) {
         preference_get_int(integer_key, &integer_output);
         dlog_print(DLOG_INFO, "PREFERENCE", "Integer value: %d", integer_output);
     }
 }

 void
 manage_double_preference(void)
 {
     const char *double_key = "double_key";
     double double_value = 3.14;
     double double_output;
     
     preference_set_double(double_key, double_value);
     preference_get_double(double_key, &double_output);
 }

 void
 manage_boolean_preference(void)
 {
     const char *boolean_key = "boolean_key";
     bool boolean_value = true;
     bool boolean_output;
     
     preference_set_boolean(boolean_key, boolean_value);
     preference_get_boolean(boolean_key, &boolean_output);
 }

Storing and Retrieving String Variables

Release the value returned by the get function using the free() function.

 void
 manage_string_preference(void)
 {
     const char *string_key = "string_key";
     const char *string_value = "Sample content";
     char *string_output;
     bool existing;
     
     // Set string value
     preference_set_string(string_key, string_value);
     
     // Check if key exists
     preference_is_existing(string_key, &existing);
     
     // Get string value
     if (existing) {
         preference_get_string(string_key, &string_output);
         dlog_print(DLOG_INFO, "PREFERENCE", "String value: %s", string_output);
         free(string_output);
     }
 }

Tracking Variable Changes

You can set a different callback function to each variable. The callback function is invoked each time the variable is changed.

 void
 preference_changed_cb_impl(const char *key, void *user_data)
 {
     int ret = 0;
     int integer_output = 0;
     
     dlog_print(DLOG_DEBUG, "PREFERENCE", "[preference_changed_cb_impl]");
     preference_get_int(key, &integer_output);
     
     dlog_print(DLOG_DEBUG, "PREFERENCE", "Key: %s has changed its value to %d",
                key, integer_output);
 }

 void
 register_preference_callback(void)
 {
     const char *integer_key = "integer_key";
     void *user_data = NULL;
     
     // Register callback
     preference_set_changed_cb(integer_key, preference_changed_cb_impl, user_data);
     
     // When no longer needed, unset the callback
     // preference_unset_changed_cb(integer_key);
 }

Listing All Records

Use the foreach function to list all records. The function calls a specific callback function for each key-value pair in the database. If the callback function returns false, or if all the records have been opened, the foreach function ends.

 bool
 preference_foreach_item_cb(const char *key, void *user_data)
 {
     dlog_print(DLOG_DEBUG, "PREFERENCE", "[preference_foreach_item_cb]");
     dlog_print(DLOG_DEBUG, "PREFERENCE", "Key found: %s", key);
     
     return true;
 }

 void
 list_all_preferences(void)
 {
     preference_foreach_item(preference_foreach_item_cb, NULL);
 }

Deleting Records

To delete records one by one, use a unique key. You can also delete all records for an application using the preference_remove_all() function.

 void
 delete_preferences(void)
 {
     const char *key = "integer_key";
     
     // Remove a single key-value pair
     preference_remove(key);
     
     // Remove all preferences (use with caution)
     // preference_remove_all();
 }

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().

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]	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, 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

enum preference_error_e

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

enum preference_type_e

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]	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, otherwise `false`

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.

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]	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()

Required Header

Overview

Storing and Retrieving Simple Type Variables

Storing and Retrieving String Variables

Tracking Variable Changes

Listing All Records

Deleting Records

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation