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_t *	profile_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 <simo.piiroinen@nokia.com>

---

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