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.
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.1

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.1

Remarks:: You should not free the key returned by this function.

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

enum preference_error_e

Enumeration for Preference Error.

Since :: 2.3.1

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

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.1

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.1

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.1

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.1

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.1

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_is_existing	(	const char *	key,
		bool *	existing
	)

Checks whether the given key exists in the preference.

Since :: 2.3.1

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.1

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.1

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.1

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.1

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.1

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.1

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.1

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.1

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

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation