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

ConnSettingsValueconn_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.
ConnSettingsconn_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.
ConnSettingsValueconn_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  ) 

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 
)

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.


Generated on Fri Sep 3 12:39:05 2010 for Internet Connectivity Settings Library by  doxygen 1.5.6