conn_settings.c File Reference

---

Detailed Description

libconnsettings - Connectivity settings library.

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

Contact: Jukka Rissanen <jukka.rissanen@nokia.com>

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

#include <string.h>
#include <gconf/gconf-client.h>
#include <osso-ic-gconf.h>
#include "conn_settings.h"

Data Structures
struct	ConnSettingsNotifier_
struct	ConnSettings_
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 **value)
	Deallocate array of settings value structs.
char *	conn_settings_escape_string (const char *str)
	Escape a string.
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_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_get_list (ConnSettings *ctx, const char *key, ConnSettingsValue ***value)
	Get list 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_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_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_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.
int	conn_settings_id_exists (ConnSettingsType type, char *id)
	Check if the id exists.

---

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.