Liblazy - D-Bus methods provided for convenience

Defines
#define	LIBLAZY_ERROR_GENERAL   -1
#define	LIBLAZY_ERROR_INVALID_ARGUMENT   -2
#define	LIBLAZY_ERROR_HAL_NOT_READY   -10
#define	LIBLAZY_ERROR_HAL_NO_SUCH_PROPERTY   -11
#define	LIBLAZY_ERROR_DBUS_NOT_READY   -20
#define	LIBLAZY_ERROR_DBUS_NO_REPLY   -21
#define	LIBLAZY_ERROR_DBUS_ERROR_IS_SET   -22
Functions
void	liblazy_free_string (char *string)
	free a string
void	liblazy_free_strlist (char **strlist)
	free a null terminated array of strings
int	liblazy_dbus_system_send_method_call (const char *destination, const char *path, const char *interface, const char *method, DBusMessage **reply, int first_arg_type,...)
	send a method call to the system bus
int	liblazy_dbus_session_send_method_call (const char *destination, const char *path, const char *interface, const char *method, DBusMessage **reply, int first_arg_type,...)
	send a method call to the session bus
int	liblazy_dbus_system_send_signal (const char *path, const char *interface, const char *name, int first_arg_type,...)
	send a signal over the system bus
int	liblazy_dbus_session_send_signal (const char *path, const char *interface, const char *name, int first_arg_type,...)
	send a signal over the session bus
int	liblazy_dbus_message_get_basic_arg (DBusMessage *message, int type, void *arg, int no)
	get an argument from a DBusMessage
int	liblazy_dbus_message_get_strlist_arg (DBusMessage *message, char ***strlist, int no)
	get a array argument from a DBusMessage as a string list
void	liblazy_dbus_system_use_private_connection (int use_private)
	use a private connection for system bus messages
int	liblazy_hal_get_property_int (const char *udi, const char *property, int *value)
	get integer property from HAL
int	liblazy_hal_get_property_bool (const char *udi, const char *property, int *value)
	get boolean property from HAL
int	liblazy_hal_get_property_string (const char *udi, const char *property, char **value)
	get string property from HAL
int	liblazy_hal_get_property_strlist (const char *udi, const char *property, char ***strlist)
	get string list property from HAL
int	liblazy_hal_query_capability (const char *udi, const char *capability)
	check if a device has a capability
int	liblazy_hal_find_device_by_capability (const char *capability, char ***strlist)
	find devices with a given capability
int	liblazy_hal_find_device_by_string_match (const char *key, const char *value, char ***strlist)
	find devices with given key and value
int	liblazy_hal_is_caller_privileged (const char *privilege)
	check if a user possesses a privilege

---

Define Documentation

#define LIBLAZY_ERROR_DBUS_ERROR_IS_SET   -22

Referenced by liblazy_dbus_send_method_call().

#define LIBLAZY_ERROR_DBUS_NO_REPLY   -21

#define LIBLAZY_ERROR_DBUS_NOT_READY   -20

Referenced by liblazy_dbus_send_method_call(), liblazy_dbus_send_signal(), and liblazy_hal_is_caller_privileged().

#define LIBLAZY_ERROR_GENERAL   -1

Referenced by liblazy_dbus_message_get_basic_arg(), liblazy_dbus_message_get_strlist_arg(), liblazy_dbus_send_method_call(), and liblazy_dbus_send_signal().

#define LIBLAZY_ERROR_HAL_NO_SUCH_PROPERTY   -11

Referenced by liblazy_hal_get_property_bool(), liblazy_hal_get_property_int(), liblazy_hal_get_property_string(), and liblazy_hal_get_property_strlist().

#define LIBLAZY_ERROR_HAL_NOT_READY   -10

#define LIBLAZY_ERROR_INVALID_ARGUMENT   -2

Referenced by liblazy_dbus_message_get_basic_arg(), liblazy_dbus_message_get_strlist_arg(), liblazy_dbus_send_method_call(), liblazy_dbus_send_signal(), liblazy_hal_get_property(), liblazy_hal_get_property_strlist(), liblazy_hal_is_caller_privileged(), liblazy_hal_property_exists(), and liblazy_hal_query_capability().

---

Function Documentation

int liblazy_dbus_message_get_basic_arg	(	DBusMessage *	message,
		int	type,
		void *	arg,
		int	no
	)

get an argument from a DBusMessage

Parameters:

message	the DBusMessage to get the argument from
type	the type of the argument
arg	a location to store the argument
no	a number specifying the n'th argument of the given type

Returns:

0 on success, LIBLAZY_ERROR_* on failure

References LIBLAZY_ERROR_GENERAL, and LIBLAZY_ERROR_INVALID_ARGUMENT.

Referenced by liblazy_hal_get_property(), liblazy_hal_is_caller_privileged(), and liblazy_hal_property_exists().

int liblazy_dbus_message_get_strlist_arg	(	DBusMessage *	message,
		char ***	strlist,
		int	no
	)

get a array argument from a DBusMessage as a string list

Parameters:

message	the message to get the argument from
strlist	a pointer to a string array to store the result
strlist	pointer to array of strings to store the result. Has to be freed with liblazy_free_strlist
no	a number specifying the n'th string array in the reply

Returns:

0 on success, LIBLAZY_ERROR_* on failure

References liblazy_dbus_get_strlist_from_array(), LIBLAZY_ERROR_GENERAL, and LIBLAZY_ERROR_INVALID_ARGUMENT.

Referenced by liblazy_hal_get_property_strlist(), and liblazy_hal_get_strlist_manager().

int liblazy_dbus_session_send_method_call	(	const char *	destination,
		const char *	path,
		const char *	interface,
		const char *	method,
		DBusMessage **	reply,
		int	first_arg_type,
			...
	)

send a method call to the session bus

sends a method call to the session bus. The call blocks if a reply is given. If the call shouldn't block, give NULL for the reply

Parameters:

destination	the destination to send to
path	the object path to send to
interface	the interface to send to
method	the method to send
reply	a DBusMessage to store the reply or NULL if the call shouldn't block
first_arg_type	a DBUS_TYPE_* of the fist argument
...	variable argument list finished with DBUS_TYPE_INVALID

Returns:

0 on success, LIBLAZY_ERROR_* on failure

References liblazy_dbus_send_method_call().

int liblazy_dbus_session_send_signal	(	const char *	path,
		const char *	interface,
		const char *	name,
		int	first_arg_type,
			...
	)

send a signal over the session bus

sends a signal over the session bus. The call blocks if a reply is given. If the call shouldn't block, give NULL for the reply

Parameters:

path	the object path to send to
interface	the interface to send to
name	the name of the signal
first_arg_type	a DBUS_TYPE_* of the fist argument
...	variable argument list finished with DBUS_TYPE_INVALID

Returns:

0 on success, LIBLAZY_ERROR_* on failure

References liblazy_dbus_send_signal().

int liblazy_dbus_system_send_method_call	(	const char *	destination,
		const char *	path,
		const char *	interface,
		const char *	method,
		DBusMessage **	reply,
		int	first_arg_type,
			...
	)

send a method call to the system bus

sends a method call to the system bus. The call blocks if a reply is given. If the call shouldn't block, give NULL for the reply

Parameters:

destination	the destination to send to
path	the object path to send to
interface	the interface to send to
method	the method to send
reply	a DBusMessage to store the reply or NULL if the call shouldn't block
first_arg_type	a DBUS_TYPE_* of the fist argument
...	variable argument list finished with DBUS_TYPE_INVALID

Returns:

0 on success, LIBLAZY_ERROR_* on failure

References liblazy_dbus_send_method_call().

Referenced by liblazy_hal_get_property(), liblazy_hal_get_property_strlist(), liblazy_hal_is_caller_privileged(), and liblazy_hal_property_exists().

int liblazy_dbus_system_send_signal	(	const char *	path,
		const char *	interface,
		const char *	name,
		int	first_arg_type,
			...
	)

send a signal over the system bus

sends a signal over the system bus. The call blocks if a reply is given. If the call shouldn't block, give NULL for the reply

Parameters:

path	the object path to send to
interface	the interface to send to
name	the name of the signal
first_arg_type	a DBUS_TYPE_* of the fist argument
...	variable argument list finished with DBUS_TYPE_INVALID

Returns:

0 on success, LIBLAZY_ERROR_* on failure

References liblazy_dbus_send_signal().

void liblazy_dbus_system_use_private_connection

(

int

use_private

)

use a private connection for system bus messages

Call this function with a boolean value to tell the library whether to use a private connection for system bus messages (liblazy_dbus_system*). Defaults to false. If a private connection is used, the libarary creates a new connection on _every_ call and immediately closes it. So this should be used very carefully. Only use if your application does very rare dbus calls and doesn't have a mainloop to listen if D-Bus died but still should be able to survive D-Bus restarts.

Parameters:

use_privat

1 if the library should use a private connection, 0 otherwise

References dbus_system_use_private_connection.

void liblazy_free_string

(

char *

string

)

free a string

Parameters:

string

the string to free

void liblazy_free_strlist

(

char **

strlist

)

free a null terminated array of strings

Parameters:

strlist

the string list to free

Referenced by liblazy_hal_query_capability().

int liblazy_hal_find_device_by_capability	(	const char *	capability,
		char ***	strlist
	)

find devices with a given capability

Parameters:

capability	the capability the devices should have
strlist	pointer to array of strings to store the result. Has to be freed with liblazy_free_strlist

Returns:

0 on success, LIBLAZY_ERROR_* on failure

References liblazy_hal_get_strlist_manager().

int liblazy_hal_find_device_by_string_match	(	const char *	key,
		const char *	value,
		char ***	strlist
	)

find devices with given key and value

Parameters:

key	the key to match against
value	the value to match against
strlist	pointer to array of strings to store the result. Has to be freed with liblazy_free_strlist

Returns:

0 on success, LIBLAZY_ERROR_* on failure

References liblazy_hal_get_strlist_manager().

int liblazy_hal_get_property_bool	(	const char *	udi,
		const char *	property,
		int *	value
	)

get boolean property from HAL

fetches one boolean value from HAL.

Parameters:

udi	the device to fetch the value from
property	the property to fetch
value	location to store the result

Returns:

0 on success, LIBLAZY_ERROR_* on failure

References LIBLAZY_ERROR_HAL_NO_SUCH_PROPERTY, liblazy_hal_get_property(), and liblazy_hal_property_exists().

int liblazy_hal_get_property_int	(	const char *	udi,
		const char *	property,
		int *	value
	)

get integer property from HAL

fetches one interger value from HAL.

Parameters:

udi	the device to fetch the value from
property	the property to fetch
value	location to store the result

Returns:

0 on success, LIBLAZY_ERROR_* on failure

References LIBLAZY_ERROR_HAL_NO_SUCH_PROPERTY, liblazy_hal_get_property(), and liblazy_hal_property_exists().

int liblazy_hal_get_property_string	(	const char *	udi,
		const char *	property,
		char **	value
	)

get string property from HAL

fetches one string value from HAL.

Parameters:

udi	the device to fetch the value from
property	the property to fetch
value	location to store the result

Returns:

0 on success, LIBLAZY_ERROR_* on failure

References LIBLAZY_ERROR_HAL_NO_SUCH_PROPERTY, liblazy_hal_get_property(), and liblazy_hal_property_exists().

int liblazy_hal_get_property_strlist	(	const char *	udi,
		const char *	property,
		char ***	strlist
	)

get string list property from HAL

fetches a string list value from HAL.

Parameters:

udi	the device to fetch the value from
property	the property to fetch
strlist	pointer to array of strings to store the result. Has to be freed with liblazy_free_strlist

Returns:

0 on success, LIBLAZY_ERROR_* on failure

References DBUS_HAL_DEVICE_INTERFACE, DBUS_HAL_SERVICE, liblazy_dbus_message_get_strlist_arg(), liblazy_dbus_system_send_method_call(), LIBLAZY_ERROR_HAL_NO_SUCH_PROPERTY, LIBLAZY_ERROR_INVALID_ARGUMENT, and liblazy_hal_property_exists().

Referenced by liblazy_hal_query_capability().

int liblazy_hal_is_caller_privileged

(

const char *

privilege

)

check if a user possesses a privilege

Check if the caller possesses the given privilege on the default device '/org/freedesktop/Hal/devices/computer'

Parameters:

privilege

the privilege to check for

Returns:

1 if the caller is privileged, 0 if not, and LIBLAZY_ERROR_* on failure

References DBUS_HAL_COMPUTER_PATH, DBUS_HAL_DEVICE_INTERFACE, DBUS_HAL_SERVICE, liblazy_dbus_message_get_basic_arg(), liblazy_dbus_system_send_method_call(), LIBLAZY_ERROR_DBUS_NOT_READY, and LIBLAZY_ERROR_INVALID_ARGUMENT.

int liblazy_hal_query_capability	(	const char *	udi,
		const char *	capability
	)

check if a device has a capability

Parameters:

udi	the device to query on
capability	the capability to query for

Returns:

1 if the device possesses the capability, 0 if not and LIBLAZY_ERROR_* on failure

References LIBLAZY_ERROR_INVALID_ARGUMENT, liblazy_free_strlist(), and liblazy_hal_get_property_strlist().