conn_settings.h File Reference

---

Detailed Description

Author:

Aapo Makela <aapo.makela@nokia.com>

Jukka Rissanen <jukka.rissanen@nokia.com>

libconnsettings - Connectivity settings library.

Copyright (C) 2010 Nokia Corporation. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License version 2.1 as published by the Free Software Foundation.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Data Structures
struct	ConnSettingsValue_
	ConnSettings value. More...
Typedefs
typedef enum ConnSettingsError_	ConnSettingsError
	Error values for the library.
typedef struct ConnSettings_	ConnSettings
	ConnSettings context.
typedef enum ConnSettingsType_	ConnSettingsType
	Type of ConnSettings context.
typedef enum ConnSettingsValueType_	ConnSettingsValueType
	ConnSettings value type.
typedef struct ConnSettingsValue_	ConnSettingsValue
	ConnSettings value.
typedef void(*	ConnSettingsNotifyFunc )(ConnSettingsType type, const char *id, const char *key, ConnSettingsValue *value, void *user_data)
	This function will be called if configuration setting is modified or removed in backend.
Enumerations
enum	ConnSettingsError_ {   CONN_SETTINGS_E_INVALID_CONTEXT = -1, CONN_SETTINGS_E_DIFFERENT_TYPE = -2, CONN_SETTINGS_E_GCONF_ERROR = -3, CONN_SETTINGS_E_INVALID_PARAMETER = -4,   CONN_SETTINGS_E_NO_SUCH_KEY = -5, CONN_SETTINGS_E_INVALID_TYPE = -6, CONN_SETTINGS_E_INVALID_VALUE = -7, CONN_SETTINGS_E_NO_ERROR = 0 }
	Error values for the library. More...
enum	ConnSettingsType_ {   CONN_SETTINGS_INVALID, CONN_SETTINGS_GENERAL, CONN_SETTINGS_NETWORK_TYPE, CONN_SETTINGS_CONNECTION,   CONN_SETTINGS_SERVICE_TYPE }
	Type of ConnSettings context. More...
enum	ConnSettingsValueType_ {   CONN_SETTINGS_VALUE_INVALID, CONN_SETTINGS_VALUE_STRING, CONN_SETTINGS_VALUE_INT, CONN_SETTINGS_VALUE_DOUBLE,   CONN_SETTINGS_VALUE_BOOL, CONN_SETTINGS_VALUE_LIST, CONN_SETTINGS_VALUE_BYTE_ARRAY }
	ConnSettings value type. More...
Functions
ConnSettingsValue *	conn_settings_value_new ()
	Allocate new settings value struct.
void	conn_settings_value_destroy (ConnSettingsValue *value)
	Deallocate settings value struct.
void	conn_settings_values_destroy (ConnSettingsValue **values)
	Deallocate array of settings value structs.
char **	conn_settings_list_ids (ConnSettingsType type)
	List available Ids for a connectivity setting type.
ConnSettings *	conn_settings_open (ConnSettingsType type, const char *id)
	Open connectivity settings for given type and ID.
char **	conn_settings_list_keys (ConnSettings *ctx)
	List available keys for a given connectivity settings.
ConnSettingsValue *	conn_settings_get (ConnSettings *ctx, const char *key)
	Get value for a given key.
int	conn_settings_get_string (ConnSettings *ctx, const char *key, char **value)
	Get string value of a given key.
int	conn_settings_get_int (ConnSettings *ctx, const char *key, int *value)
	Get int value of a given key.
int	conn_settings_get_double (ConnSettings *ctx, const char *key, double *value)
	Get double value of a given key.
int	conn_settings_get_bool (ConnSettings *ctx, const char *key, int *value)
	Get bool value of a given key.
int	conn_settings_get_list (ConnSettings *ctx, const char *key, ConnSettingsValue ***value)
	Get list value of a given key.
int	conn_settings_get_byte_array (ConnSettings *ctx, const char *key, unsigned char **value, unsigned int *value_len)
	Get byte array value of a given key.
int	conn_settings_set (ConnSettings *ctx, const char *key, ConnSettingsValue *value)
	Set value for a given key.
int	conn_settings_set_string (ConnSettings *ctx, const char *key, char *value)
	Set string value for a given key.
int	conn_settings_set_int (ConnSettings *ctx, const char *key, int value)
	Set int value for a given key.
int	conn_settings_set_double (ConnSettings *ctx, const char *key, double value)
	Set double value for a given key.
int	conn_settings_set_bool (ConnSettings *ctx, const char *key, int value)
	Set boolean value for a given key.
int	conn_settings_set_list (ConnSettings *ctx, const char *key, void *list, unsigned int list_len, ConnSettingsValueType elem_type)
	Set list value for a given key.
int	conn_settings_set_byte_array (ConnSettings *ctx, const char *key, unsigned char *value, unsigned int value_len)
	Set byte array value for a given key.
int	conn_settings_unset (ConnSettings *ctx, const char *key)
	Unset / remove key.
int	conn_settings_remove (ConnSettings *ctx)
	Remove current settings.
void	conn_settings_close (ConnSettings *ctx)
	Close connectivity settings context.
const char *	conn_settings_error_text (ConnSettingsError code)
	Return error text to an error code.
int	conn_settings_add_notify (ConnSettings *ctx, ConnSettingsNotifyFunc *func, void *user_data)
	Set notification func for settings changes.
void	conn_settings_del_notify (ConnSettings *ctx)
	Remove notification func for settings changes.
char *	conn_settings_escape_string (const char *str)
	Escape a string.
int	conn_settings_id_exists (ConnSettingsType type, char *id)
	Check if the id exists.

---

Typedef Documentation

typedef struct ConnSettings_ ConnSettings

ConnSettings context.

This contains library internal data.

typedef void(* ConnSettingsNotifyFunc)(ConnSettingsType type, const char *id, const char *key, ConnSettingsValue *value, void *user_data)

This function will be called if configuration setting is modified or removed in backend.

Not all backends support this. Note that the value is freed by the library.

typedef struct ConnSettingsValue_ ConnSettingsValue

ConnSettings value.

When filling the value union, you must allocate new space for string_val, byte_array.val and list_val as the conn_settings_value_destroy() will deallocate that memory.

---

Enumeration Type Documentation

enum ConnSettingsError_

Error values for the library.

Enumerator:

CONN_SETTINGS_E_INVALID_CONTEXT	Context is not set.
CONN_SETTINGS_E_DIFFERENT_TYPE	Backend has different type for a given key.
CONN_SETTINGS_E_GCONF_ERROR	GConf error.
CONN_SETTINGS_E_INVALID_PARAMETER	Parameter not set.
CONN_SETTINGS_E_NO_SUCH_KEY	Key not found in store.
CONN_SETTINGS_E_INVALID_TYPE	Invalid type, backend does not support such a type.
CONN_SETTINGS_E_INVALID_VALUE	Value is invalid (either null or otherwise invalid).
CONN_SETTINGS_E_NO_ERROR	Last entry, no error.

enum ConnSettingsType_

Type of ConnSettings context.

Enumerator:

CONN_SETTINGS_INVALID	Invalid settings (this is an error condition).
CONN_SETTINGS_GENERAL	General connectivity settings.
CONN_SETTINGS_NETWORK_TYPE	Network type settings.
CONN_SETTINGS_CONNECTION	Connection settings.
CONN_SETTINGS_SERVICE_TYPE	Service type settings.

enum ConnSettingsValueType_

ConnSettings value type.

Enumerator:

CONN_SETTINGS_VALUE_INVALID	Invalid value.
CONN_SETTINGS_VALUE_STRING	String value.
CONN_SETTINGS_VALUE_INT	Integer value.
CONN_SETTINGS_VALUE_DOUBLE	Double value.
CONN_SETTINGS_VALUE_BOOL	Boolean value.
CONN_SETTINGS_VALUE_LIST	List of ConnSettingsValue value.
CONN_SETTINGS_VALUE_BYTE_ARRAY	Byte array.

---

Function Documentation

int conn_settings_add_notify	(	ConnSettings *	ctx,
		ConnSettingsNotifyFunc *	func,
		void *	user_data
	)

Set notification func for settings changes.

Parameters:

	ctx	Settings context
	func	Notification function to be called
	user_data	Opaque user data

Returns:

TRUE on success, FALSE on failure

void conn_settings_close

(

ConnSettings *

ctx

)

Close connectivity settings context.

Deallocates the context struct.

Parameters:

ctx

Settings context

References conn_settings_del_notify().

void conn_settings_del_notify

(

ConnSettings *

ctx

)

Remove notification func for settings changes.

Parameters:

ctx

Settings context

Referenced by conn_settings_close().

const char* conn_settings_error_text

(

ConnSettingsError

code

)

Return error text to an error code.

Parameters:

code

Error code

Returns:

Error string

References CONN_SETTINGS_E_DIFFERENT_TYPE, CONN_SETTINGS_E_GCONF_ERROR, CONN_SETTINGS_E_INVALID_CONTEXT, CONN_SETTINGS_E_INVALID_PARAMETER, CONN_SETTINGS_E_INVALID_TYPE, CONN_SETTINGS_E_INVALID_VALUE, CONN_SETTINGS_E_NO_ERROR, and CONN_SETTINGS_E_NO_SUCH_KEY.

char* conn_settings_escape_string

(

const char *

str

)

Escape a string.

Parameters:

str

String to be escaped

Returns:

Escaped string, caller should de-allocate the string

Referenced by conn_settings_id_exists().

ConnSettingsValue* conn_settings_get	(	ConnSettings *	ctx,
		const char *	key
	)

Get value for a given key.

Parameters:

	ctx	Settings context
	key	Settings name

Returns:

ConnSettingsValue or NULL if value is not found

References CONN_SETTINGS_VALUE_INVALID.

Referenced by conn_settings_get_list().

int conn_settings_get_bool	(	ConnSettings *	ctx,
		const char *	key,
		int *	value
	)

Get bool value of a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	value	Value is returned.

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_GCONF_ERROR, CONN_SETTINGS_E_INVALID_CONTEXT, CONN_SETTINGS_E_INVALID_PARAMETER, and CONN_SETTINGS_E_NO_SUCH_KEY.

int conn_settings_get_byte_array	(	ConnSettings *	ctx,
		const char *	key,
		unsigned char **	value,
		unsigned int *	value_len
	)

Get byte array value of a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	value	Value is returned. User is responsible for deallocating the returned value.
	value_len	Length of the returned value

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_DIFFERENT_TYPE, CONN_SETTINGS_E_GCONF_ERROR, CONN_SETTINGS_E_INVALID_CONTEXT, CONN_SETTINGS_E_INVALID_PARAMETER, and CONN_SETTINGS_E_NO_SUCH_KEY.

int conn_settings_get_double	(	ConnSettings *	ctx,
		const char *	key,
		double *	value
	)

Get double value of a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	value	Value is returned.

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_GCONF_ERROR, CONN_SETTINGS_E_INVALID_CONTEXT, CONN_SETTINGS_E_INVALID_PARAMETER, and CONN_SETTINGS_E_NO_SUCH_KEY.

int conn_settings_get_int	(	ConnSettings *	ctx,
		const char *	key,
		int *	value
	)

Get int value of a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	value	Value is returned.

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_GCONF_ERROR, CONN_SETTINGS_E_INVALID_CONTEXT, CONN_SETTINGS_E_INVALID_PARAMETER, and CONN_SETTINGS_E_NO_SUCH_KEY.

int conn_settings_get_list	(	ConnSettings *	ctx,
		const char *	key,
		ConnSettingsValue ***	value
	)

Get list value of a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	value	Value is returned. User is responsible for deallocating the returned value. Note that the value is array of pointers to list values, it is not a list itself

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_DIFFERENT_TYPE, CONN_SETTINGS_E_INVALID_CONTEXT, CONN_SETTINGS_E_INVALID_PARAMETER, CONN_SETTINGS_E_NO_SUCH_KEY, conn_settings_get(), conn_settings_value_destroy(), CONN_SETTINGS_VALUE_INVALID, CONN_SETTINGS_VALUE_LIST, ConnSettingsValue_::list_val, ConnSettingsValue_::type, and ConnSettingsValue_::value.

int conn_settings_get_string	(	ConnSettings *	ctx,
		const char *	key,
		char **	value
	)

Get string value of a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	value	Pointer to value is returned. User should deallocate the value after use.

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_GCONF_ERROR, CONN_SETTINGS_E_INVALID_CONTEXT, CONN_SETTINGS_E_INVALID_PARAMETER, and CONN_SETTINGS_E_NO_SUCH_KEY.

int conn_settings_id_exists	(	ConnSettingsType	type,
		char *	id
	)

Check if the id exists.

Parameters:

	type	Setting type.
	id	Id name (directory in gconf)

Returns:

TRUE if id exists, false otherwise

References CONN_SETTINGS_CONNECTION, conn_settings_escape_string(), CONN_SETTINGS_GENERAL, CONN_SETTINGS_NETWORK_TYPE, and CONN_SETTINGS_SERVICE_TYPE.

char** conn_settings_list_ids

(

ConnSettingsType

type

)

List available Ids for a connectivity setting type.

For gconf backend, this function returns corresponding directory names from gconf.

Parameters:

type

Setting type.

Returns:

List of pointers or NULL if none found

References CONN_SETTINGS_CONNECTION, CONN_SETTINGS_GENERAL, CONN_SETTINGS_NETWORK_TYPE, and CONN_SETTINGS_SERVICE_TYPE.

char** conn_settings_list_keys

(

ConnSettings *

ctx

)

List available keys for a given connectivity settings.

For gconf backend this returns keys in a defined directory

Parameters:

ctx

Settings context

Returns:

List of pointers or NULL if none found

ConnSettings* conn_settings_open	(	ConnSettingsType	type,
		const char *	id
	)

Open connectivity settings for given type and ID.

Parameters:

	type	What settings to manipulate
	id	Id of the setting (typically a gconf directory i.e., for connectivity type id is the IAP id

Returns:

ConnSettings or NULL if invalid parameters were given

References CONN_SETTINGS_CONNECTION, CONN_SETTINGS_GENERAL, CONN_SETTINGS_NETWORK_TYPE, and CONN_SETTINGS_SERVICE_TYPE.

int conn_settings_remove

(

ConnSettings *

ctx

)

Remove current settings.

For gconf backend this removes a directory tree.

Parameters:

ctx

Settings context

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_GCONF_ERROR, and CONN_SETTINGS_E_INVALID_CONTEXT.

int conn_settings_set	(	ConnSettings *	ctx,
		const char *	key,
		ConnSettingsValue *	value
	)

Set value for a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	value	Settings value to set

Returns:

ConnSettingsError return code

References ConnSettingsValue_::bool_val, ConnSettingsValue_::byte_array, CONN_SETTINGS_E_INVALID_CONTEXT, CONN_SETTINGS_E_INVALID_PARAMETER, CONN_SETTINGS_E_INVALID_TYPE, CONN_SETTINGS_E_INVALID_VALUE, conn_settings_unset(), CONN_SETTINGS_VALUE_BOOL, CONN_SETTINGS_VALUE_BYTE_ARRAY, CONN_SETTINGS_VALUE_DOUBLE, CONN_SETTINGS_VALUE_INT, CONN_SETTINGS_VALUE_LIST, CONN_SETTINGS_VALUE_STRING, ConnSettingsValue_::double_val, ConnSettingsValue_::int_val, ConnSettingsValue_::list_val, ConnSettingsValue_::string_val, ConnSettingsValue_::type, and ConnSettingsValue_::value.

Referenced by conn_settings_set_byte_array(), and conn_settings_set_list().

int conn_settings_set_bool	(	ConnSettings *	ctx,
		const char *	key,
		int	value
	)

Set boolean value for a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	value	Boolean value to set

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_DIFFERENT_TYPE, CONN_SETTINGS_E_GCONF_ERROR, CONN_SETTINGS_E_INVALID_CONTEXT, and CONN_SETTINGS_E_INVALID_PARAMETER.

int conn_settings_set_byte_array	(	ConnSettings *	ctx,
		const char *	key,
		unsigned char *	value,
		unsigned int	value_len
	)

Set byte array value for a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	value	Byte array value to set
	value_len	Length of the byte array

Returns:

ConnSettingsError return code

References ConnSettingsValue_::byte_array, CONN_SETTINGS_E_INVALID_CONTEXT, CONN_SETTINGS_E_INVALID_PARAMETER, conn_settings_set(), CONN_SETTINGS_VALUE_BYTE_ARRAY, ConnSettingsValue_::type, and ConnSettingsValue_::value.

int conn_settings_set_double	(	ConnSettings *	ctx,
		const char *	key,
		double	value
	)

Set double value for a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	value	Double value to set

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_DIFFERENT_TYPE, CONN_SETTINGS_E_GCONF_ERROR, CONN_SETTINGS_E_INVALID_CONTEXT, and CONN_SETTINGS_E_INVALID_PARAMETER.

int conn_settings_set_int	(	ConnSettings *	ctx,
		const char *	key,
		int	value
	)

Set int value for a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	value	Integer value to set

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_DIFFERENT_TYPE, CONN_SETTINGS_E_GCONF_ERROR, CONN_SETTINGS_E_INVALID_CONTEXT, and CONN_SETTINGS_E_INVALID_PARAMETER.

int conn_settings_set_list	(	ConnSettings *	ctx,
		const char *	key,
		void *	list,
		unsigned int	list_len,
		ConnSettingsValueType	elem_type
	)

Set list value for a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	list	List value to set. The list is an array of elements (the elements are not pointers)
	list_len	Length of the list (how many elements there is in the list array)
	elem_type	Type of the list element

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_INVALID_CONTEXT, CONN_SETTINGS_E_INVALID_PARAMETER, CONN_SETTINGS_E_INVALID_TYPE, CONN_SETTINGS_E_INVALID_VALUE, conn_settings_set(), CONN_SETTINGS_VALUE_BOOL, conn_settings_value_destroy(), CONN_SETTINGS_VALUE_DOUBLE, CONN_SETTINGS_VALUE_INT, CONN_SETTINGS_VALUE_LIST, CONN_SETTINGS_VALUE_STRING, ConnSettingsValue_::double_val, ConnSettingsValue_::int_val, ConnSettingsValue_::list_val, ConnSettingsValue_::string_val, and ConnSettingsValue_::value.

int conn_settings_set_string	(	ConnSettings *	ctx,
		const char *	key,
		char *	value
	)

Set string value for a given key.

Parameters:

	ctx	Settings context
	key	Settings key
	value	String value to set

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_DIFFERENT_TYPE, CONN_SETTINGS_E_GCONF_ERROR, CONN_SETTINGS_E_INVALID_CONTEXT, CONN_SETTINGS_E_INVALID_PARAMETER, and conn_settings_unset().

int conn_settings_unset	(	ConnSettings *	ctx,
		const char *	key
	)

Unset / remove key.

For gconf backend this removes one individual key.

Parameters:

	ctx	Settings context
	key	Settings key

Returns:

ConnSettingsError return code

References CONN_SETTINGS_E_GCONF_ERROR, CONN_SETTINGS_E_INVALID_CONTEXT, and CONN_SETTINGS_E_INVALID_PARAMETER.

Referenced by conn_settings_set(), and conn_settings_set_string().

void conn_settings_value_destroy

(

ConnSettingsValue *

value

)

Deallocate settings value struct.

Note that string_val, byte_array.val and list_val pointers are also freed (depeding on value type). This means that user should allocate space for those when filling up the struct value union.

Parameters:

value

Pointer to settings value struct to be deallocated.

References ConnSettingsValue_::byte_array, CONN_SETTINGS_VALUE_BOOL, CONN_SETTINGS_VALUE_BYTE_ARRAY, conn_settings_value_destroy(), CONN_SETTINGS_VALUE_DOUBLE, CONN_SETTINGS_VALUE_INT, CONN_SETTINGS_VALUE_LIST, CONN_SETTINGS_VALUE_STRING, ConnSettingsValue_::data, ConnSettingsValue_::list_val, ConnSettingsValue_::string_val, ConnSettingsValue_::type, and ConnSettingsValue_::value.

Referenced by conn_settings_get_list(), conn_settings_set_list(), conn_settings_value_destroy(), and conn_settings_values_destroy().

void conn_settings_values_destroy

(

ConnSettingsValue **

values

)

Deallocate array of settings value structs.

Note that string_val, byte_array.val and list_val pointers are also freed (depeding on value type). This means that user should allocate space for those when filling up the struct value union. This function can be used to deallocate values returned by conn_settings_get_list()

Parameters:

value

Pointer to array of settings value structs to be deallocated.

References conn_settings_value_destroy(), CONN_SETTINGS_VALUE_LIST, conn_settings_value_new(), ConnSettingsValue_::list_val, ConnSettingsValue_::type, and ConnSettingsValue_::value.