libprofile.h File Reference

C API to profile data. More...

#include "profileval.h"
#include <dbus/dbus.h>

Typedefs

typedef void(* profile_track_profile_fn )(const char *profile)
 Profile changed callback.
typedef void(* profile_track_profile_fn_data )(const char *profile, void *user_data)
 Profile changed callback with user data.
typedef void(* profile_track_value_fn )(const char *profile, const char *key, const char *val, const char *type)
 Profile value changed callback.
typedef void(* profile_track_value_fn_data )(const char *profile, const char *key, const char *val, const char *type, void *user_data)
 Profile value changed callback with user data.
typedef void(* profile_user_data_free_fn )(void *user_data)
 Free user data callback.

Functions

Query Functions
char ** profile_get_profiles (void)
 Returns array of profile names.
void profile_free_profiles (char **profiles)
 Frees array of profile names.
char ** profile_get_keys (void)
 Returns array of profile keys.
void profile_free_keys (char **keys)
 Frees array of profile keys.
profileval_tprofile_get_values (const char *profile)
 Returns array of profile values.
void profile_free_values (profileval_t *values)
 Frees array of profile values.
int profile_has_profile (const char *profile)
 Check if a profile exists.
char * profile_get_profile (void)
 Get name of the current profile.
int profile_set_profile (const char *profile)
 Set the active profile.
int profile_has_value (const char *key)
 Check if profile key exists.
char * profile_get_value (const char *profile, const char *key)
 Get value of a profile key.
int profile_set_value (const char *profile, const char *key, const char *val)
 Set value of a profile key.
int profile_is_writable (const char *key)
 Check if a value can be modified.
char * profile_get_type (const char *key)
 Get type hint of profile value.
Tracking Functions
int profile_tracker_init (void)
 Start change tracking.
void profile_tracker_quit (void)
 Stop change tracking.
void profile_track_add_profile_cb (profile_track_profile_fn_data cb, void *user_data, profile_user_data_free_fn free_cb)
 Setup current profile chaged callback.
int profile_track_remove_profile_cb (profile_track_profile_fn_data cb, void *user_data)
 Remove current profile chaged callback.
void profile_track_add_active_cb (profile_track_value_fn_data cb, void *user_data, profile_user_data_free_fn free_cb)
 Setup value in current profile changed callback.
int profile_track_remove_active_cb (profile_track_value_fn_data cb, void *user_data)
 Remove value in current profile changed callback.
void profile_track_add_change_cb (profile_track_value_fn_data cb, void *user_data, profile_user_data_free_fn free_cb)
 Setup value in non-current profile changed callback.
int profile_track_remove_change_cb (profile_track_value_fn_data cb, void *user_data)
 Remove value in non-current profile changed callback.
void profile_connection_disable_autoconnect (void)
 Special: deny libprofile from connecting to session bus.
void profile_connection_enable_autoconnect (void)
 Special: allow libprofile to connect to session bus.
void profile_connection_set (DBusConnection *con)
 Special: get session bus connection used by libprofile.
DBusConnection * profile_connection_get (void)
 Special: set session bus connection used by libprofile.
Convenience Functions
int profile_get_value_as_bool (const char *profile, const char *key)
 Get value of profile key as boolean.
int profile_set_value_as_bool (const char *profile, const char *key, int val)
 Set value of profile key from boolean.
int profile_get_value_as_int (const char *profile, const char *key)
 Get value of profile key as integer.
int profile_set_value_as_int (const char *profile, const char *key, int val)
 Set value of profile key integer boolean.
int profile_get_value_as_double (const char *profile, const char *key)
 Get value of profile key as double.
int profile_set_value_as_double (const char *profile, const char *key, double val)
 Set value of profile key integer double.
Utility Functions
int profile_parse_bool (const char *text)
 Text to boolean value utility.
int profile_parse_int (const char *text)
 Text to integer value utility.
double profile_parse_double (const char *text)
 Text to double value utility.
Deprecated Functions
void profile_track_set_profile_cb (profile_track_profile_fn cb) __attribute__((deprecated))
 Deprecated.
void profile_track_set_profile_cb_with_data (profile_track_profile_fn_data cb, void *user_data) __attribute__((deprecated))
 Deprecated.
void profile_track_set_active_cb (profile_track_value_fn cb) __attribute__((deprecated))
 Deprecated.
void profile_track_set_active_cb_with_data (profile_track_value_fn_data cb, void *user_data) __attribute__((deprecated))
 Deprecated.
void profile_track_set_change_cb (profile_track_value_fn cb) __attribute__((deprecated))
 Deprecated.
void profile_track_set_change_cb_with_data (profile_track_value_fn_data cb, void *user_data) __attribute__((deprecated))
 Deprecated.


Detailed Description

This is the API for accessing data on profile daemon.

Copyright (C) 2008 Nokia. All rights reserved.

Author:
Simo Piiroinen <[email protected]>

Typedef Documentation

typedef void(* profile_track_profile_fn)(const char *profile)

Callback function type used for signalling when the currently active profile changes.

Parameters:
profile profile name

typedef void(* profile_track_profile_fn_data)(const char *profile, void *user_data)

Callback function type used for signalling when the currently active profile changes.

Since:
0.0.13
Parameters:
profile profile name
user_data pointer specified when the callback was added

typedef void(* profile_track_value_fn)(const char *profile, const char *key, const char *val, const char *type)

Callback function type used for signalling when the values within a profile change.

Parameters:
profile profile name
key value name
val value string
type value type

typedef void(* profile_track_value_fn_data)(const char *profile, const char *key, const char *val, const char *type, void *user_data)

Callback function type used for signalling when the values within a profile change.

Since:
0.0.13
Parameters:
profile profile name
key value name
val value string
type value type
user_data pointer specified when the callback was added

typedef void(* profile_user_data_free_fn)(void *user_data)

Callback function type used for freeing user data.

Since:
0.0.15
Parameters:
user_data data to be deallocated


Function Documentation

char** profile_get_profiles ( void   ) 

Get names of currently available profiles.

Use profile_free_profiles() to free the resulting array.

Returns:
Array of profile name strings, NULL on error

void profile_free_profiles ( char **  profiles  ) 

Free profile name string array obtained via profile_get_profiles() call.

Parameters:
profiles array of profile names

char** profile_get_keys ( void   ) 

Get names of currently available profile values.

Use profile_free_keys() to free the resulting array.

Returns:
Array of profile value name strings, NULL on error

void profile_free_keys ( char **  keys  ) 

Free profile value name string array obtained via profile_get_keys() call.

Parameters:
keys Array of key names

profileval_t* profile_get_values ( const char *  profile  ) 

Get all values for given profile.

Use profile_free_values() to free the resulting array.

Parameters:
profile profile name or NULL for current
Returns:
Array of profile values, NULL on error

void profile_free_values ( profileval_t values  ) 

Free profile value array obtained via profile_get_values() call.

Parameters:
values Array of values

int profile_has_profile ( const char *  profile  ) 

Check if given profile exists.

Parameters:
profile profile name
Returns:
non-zero value if profile exists

char* profile_get_profile ( void   ) 

Get name of the currently active profile.

Returns:
profile name, NULL on error

int profile_set_profile ( const char *  profile  ) 

Set currently active profil.

Parameters:
profile profile name
Returns:
0 on success, -1 on error

int profile_has_value ( const char *  key  ) 

Check if given profile value exists.

Parameters:
key profile value name
Returns:
non-zero value if value exists

char* profile_get_value ( const char *  profile,
const char *  key 
)

Get value from profile.

Parameters:
profile profile name or NULL for current
key value name
Returns:
profile value string, NULL on error

int profile_set_value ( const char *  profile,
const char *  key,
const char *  val 
)

Set value in profile.

Parameters:
profile profile name or NULL for current
key value name
val value
Returns:
0 on success, -1 on failure

int profile_is_writable ( const char *  key  ) 

Check if given profile value is writable.

Parameters:
key profile value name
Returns:
non-zero value if value can be modified

char* profile_get_type ( const char *  key  ) 

Get type description associated with profile value.

Parameters:
key profile value name
Returns:
type description string, NULL on error

int profile_tracker_init ( void   ) 

Start listening to profile daemon signals over dbus.

The callback functions can be assigned prior to calling this function using

profile_track_set_profile_cb() profile_track_set_active_cb() profile_track_set_change_cb()

If session bus connection status changes due to calling one of profile_connection_disable_autoconnect(), profile_connection_enable_autoconnect(), profile_connection_set() or profile_connection_get() the tracking will be, depending on the new connection state either termporarily disabled or restarted.

Returns:
0 = success, -1 = error

void profile_tracker_quit ( void   ) 

Stop listening to profile daemon signals over dbus.

void profile_track_add_profile_cb ( profile_track_profile_fn_data  cb,
void *  user_data,
profile_user_data_free_fn  free_cb 
)

Adds callback function to be called when the currently active profile changes.

User data pointer is passed to the callback.

Callbacks are called in the order that they were added. The same callback can be added several times, in which case it will be executed more than once.

The callback can be removed by calling profile_track_remove_profile_cb().

Since:
0.0.15
Parameters:
cb callback function
user_data pointer to user data
free_cb function for deallocating user_data

int profile_track_remove_profile_cb ( profile_track_profile_fn_data  cb,
void *  user_data 
)

Removes callback added via profile_track_add_profile_cb().

The most recently added callback that matches the parameters will be removed.

The free callback will be called if both user data and free callback were set non-NULL when the callback was added.

Since:
0.0.15
Parameters:
cb callback function
user_data pointer to user data
Returns:
non-zero value if callback existed

void profile_track_add_active_cb ( profile_track_value_fn_data  cb,
void *  user_data,
profile_user_data_free_fn  free_cb 
)

Adds callback function to be called when a value in the currently active profile changes.

User data pointer is passed to the callback.

Callbacks are called in the order that they were added. The same callback can be added several times, in which case it will be executed more than once.

The callback can be removed by calling profile_track_remove_active_cb().

Since:
0.0.15
Parameters:
cb callback function
user_data pointer to user data
free_cb function for deallocating user_data

int profile_track_remove_active_cb ( profile_track_value_fn_data  cb,
void *  user_data 
)

Removes callback added via profile_track_add_active_cb().

The most recently added callback that matches the parameters will be removed.

The free callback will be called if both user data and free callback were set non-NULL when the callback was added.

Since:
0.0.15
Parameters:
cb callback function
user_data pointer to user data
Returns:
non-zero value if callback existed

void profile_track_add_change_cb ( profile_track_value_fn_data  cb,
void *  user_data,
profile_user_data_free_fn  free_cb 
)

Adds callback function to be called when a value in other than the currently active profile changes.

User data pointer is passed to the callback.

Callbacks are called in the order that they were added. The same callback can be added several times, in which case it will be executed more than once.

The callback can be removed by calling profile_track_remove_change_cb().

Since:
0.0.15
Parameters:
cb callback function
user_data pointer to user data
free_cb function for deallocating user_data

int profile_track_remove_change_cb ( profile_track_value_fn_data  cb,
void *  user_data 
)

Removes callback added via profile_track_add_change_cb().

The most recently added callback that matches the parameters will be removed.

The free callback will be called if both user data and free callback were set non-NULL when the callback was added.

Since:
0.0.15
Parameters:
cb callback function
user_data pointer to user data
Returns:
non-zero value if callback existed

void profile_connection_disable_autoconnect ( void   ) 

Forbid libprofile from making session bus connection

Since:
0.0.10
Normally you do not need to call this function. The library will internally select and discover the correct bus to use.

However, there are some special cases where the address of the bus is not known at start time. In such cases you can use this function to stop libprofile from initiating the connection, setup tracking if needed, connect to the bus once you discover it and pass the connection to the profile library using profile_connection_set().

If libprofile is already connected at the time this function is called, the connection will be dropped and tracking disabled.

No communication to profile daemon is possible until either profile_connection_set() or profile_connection_enable_autoconnect() is called.

void profile_connection_enable_autoconnect ( void   ) 

Allow libprofile to make session bus connection

Since:
0.0.10
If libprofile is already connected, no changes to connection state are made.

If there is no connection and tracking has been started via profile_tracker_init(), libprofile will try to autoconnect and resume tracking.

See profile_connection_disable_autoconnect() for details.

void profile_connection_set ( DBusConnection *  con  ) 

Set the session bus connection used for communicating with the profile daemon.

Since:
0.0.10
If libprofile already had a valid session bus connection, that will be released and the one provided by this function will be used. Reference count for the connection will be increased, so the caller is free to call dbus_connection_unref() afterwards.

If profile_tracker_init() has been called previously, the tracking will continue using the provided connection.

If NULL connection is passed, libprofile will release any existing connection and stops the tracking until non-null connection is provided again.

See profile_connection_disable_autoconnect() for details.

DBusConnection* profile_connection_get ( void   ) 

Get the session bus connection used for communicating with the profile daemon.

Since:
0.0.10
Returns the session bus connection established by libprofile or provided by the application via profile_connection_set().

If no connection exists at the time of the call, libprofile will try to connect to session bus - unless blocked from doing so by call to profile_connection_disable_autoconnect().

If non NULL connection is returned, the caller must release it using dbus_connection_unref() after it is no longer needed.

Returns:
session bus connection used by libprofile, or NULL

int profile_get_value_as_bool ( const char *  profile,
const char *  key 
)

Convenience function: get profile value and convert to boolean using profile_parse_bool().

Parameters:
profile profile name or NULL for current
key value name
Returns:
1=True, 0=False

int profile_set_value_as_bool ( const char *  profile,
const char *  key,
int  val 
)

Convenience function: set profile value from boolean.

Parameters:
profile profile name or NULL for current
key value name
val zero = False, nonzero = True
Returns:
0 on success, -1 on failure

int profile_get_value_as_int ( const char *  profile,
const char *  key 
)

Convenience function: get profile value and convert to integer using profile_parse_int().

Parameters:
profile profile name or NULL for current
key value name
Returns:
integer value

int profile_set_value_as_int ( const char *  profile,
const char *  key,
int  val 
)

Convenience function: set profile value from integer.

Parameters:
profile profile name or NULL for current
key value name
val integer value
Returns:
0 on success, -1 on failure

int profile_get_value_as_double ( const char *  profile,
const char *  key 
)

Convenience function: get profile value and convert to double using profile_parse_double().

Parameters:
profile profile name or NULL for current
key value name
Returns:
double value

int profile_set_value_as_double ( const char *  profile,
const char *  key,
double  val 
)

Convenience function: set profile value from double.

Parameters:
profile profile name or NULL for current
key value name
val double value
Returns:
0 on success, -1 on failure

int profile_parse_bool ( const char *  text  ) 

Utility function for parsing boolean values from profile strings.

Parameters:
text profile value content
Returns:
1=True, 0=False

int profile_parse_int ( const char *  text  ) 

Utility function for parsing integer values from profile strings.

Parameters:
text profile value content
Returns:
integer value as from strtol()

double profile_parse_double ( const char *  text  ) 

Utility function for parsing double values from profile strings.

Parameters:
text profile value content
Returns:
double value as from strtod()

void profile_track_set_profile_cb ( profile_track_profile_fn  cb  ) 

Deprecated:
New code should use profile_track_add_profile_cb() and profile_track_remove_profile_cb().
Assign callback function to be called when active profile changes.

Parameters:
cb callback function

void profile_track_set_profile_cb_with_data ( profile_track_profile_fn_data  cb,
void *  user_data 
)

Deprecated:
New code should use profile_track_add_profile_cb() and profile_track_remove_profile_cb().
Assign callback function to be called when active profile changes. Attaches user data to the callback.

Since:
0.0.13
Parameters:
cb callback function
user_data data pointer to pass to the callback

void profile_track_set_active_cb ( profile_track_value_fn  cb  ) 

Deprecated:
New code should use profile_track_add_active_cb() and profile_track_remove_active_cb().
Assign callback function to be called when value in active profile changes.

Parameters:
cb callback function

void profile_track_set_active_cb_with_data ( profile_track_value_fn_data  cb,
void *  user_data 
)

Deprecated:
New code should use profile_track_add_active_cb() and profile_track_remove_active_cb().
Assign callback function to be called when value in active profile changes. Attaches user data to the callback.

Since:
0.0.13
Parameters:
cb callback function
user_data data pointer to pass to the callback

void profile_track_set_change_cb ( profile_track_value_fn  cb  ) 

Deprecated:
New code should use profile_track_add_change_cb() and profile_track_remove_change_cb().
Assign callback function to be called when value in non-active profile changes.

Parameters:
cb callback function

void profile_track_set_change_cb_with_data ( profile_track_value_fn_data  cb,
void *  user_data 
)

Deprecated:
New code should use profile_track_add_change_cb() and profile_track_remove_change_cb().
Assign callback function to be called when value in non-active profile changes. Attaches user data to the callback.

Since:
0.0.13
Parameters:
cb callback function
user_data data pointer to pass to the callback


Generated on Wed Oct 21 13:44:00 2009 for libprofile by  doxygen 1.5.6