dbus_new_helpers.h File Reference

WPA Supplicant / dbus-based control interface Copyright (c) 2009, Witold Sowa witol.nosp@m.d.so.nosp@m.wa@gm.nosp@m.ail..nosp@m.com More...

#include <dbus/dbus.h>

Go to the source code of this file.

Data Structures
struct	wpa_dbus_object_desc
struct	wpa_dbus_argument
struct	wpa_dbus_method_desc
	DBus method description. More...
struct	wpa_dbus_signal_desc
	DBus signal description. More...
struct	wpa_dbus_property_desc
	DBus property description. More...

Macros
#define	END_ARGS   { NULL, NULL, ARG_IN }
#define	WPAS_DBUS_OBJECT_PATH_MAX   150
#define	WPAS_DBUS_INTERFACE_MAX   150
#define	WPAS_DBUS_METHOD_SIGNAL_PROP_MAX   50
#define	WPAS_DBUS_AUTH_MODE_MAX   64
#define	WPA_DBUS_INTROSPECTION_INTERFACE   "org.freedesktop.DBus.Introspectable"
#define	WPA_DBUS_INTROSPECTION_METHOD   "Introspect"
#define	WPA_DBUS_PROPERTIES_INTERFACE   "org.freedesktop.DBus.Properties"
#define	WPA_DBUS_PROPERTIES_GET   "Get"
#define	WPA_DBUS_PROPERTIES_SET   "Set"
#define	WPA_DBUS_PROPERTIES_GETALL   "GetAll"

Typedefs
typedef DBusMessage *(*	WPADBusMethodHandler )(DBusMessage *message, void *user_data)
typedef void(*	WPADBusArgumentFreeFunction )(void *handler_arg)
typedef dbus_bool_t(*	WPADBusPropertyAccessor )(DBusMessageIter *iter, DBusError *error, void *user_data)

Enumerations
enum	dbus_arg_direction { ARG_IN, ARG_OUT }

Functions
void	free_dbus_object_desc (struct wpa_dbus_object_desc *obj_dsc)
	Frees object description data structure. More...
int	wpa_dbus_ctrl_iface_init (struct wpas_dbus_priv *iface, char *dbus_path, char *dbus_service, struct wpa_dbus_object_desc *obj_desc)
	Initialize dbus control interface. More...
int	wpa_dbus_register_object_per_iface (struct wpas_dbus_priv *ctrl_iface, const char *path, const char *ifname, struct wpa_dbus_object_desc *obj_desc)
	Register a new object with dbus. More...
int	wpa_dbus_unregister_object_per_iface (struct wpas_dbus_priv *ctrl_iface, const char *path)
	Unregisters DBus object. More...
dbus_bool_t	wpa_dbus_get_object_properties (struct wpas_dbus_priv *iface, const char *path, const char *interface, DBusMessageIter *iter)
	Put object's properties into dictionary. More...
void	wpa_dbus_flush_all_changed_properties (DBusConnection *con)
	Send all PropertiesChanged signals. More...
void	wpa_dbus_flush_object_changed_properties (DBusConnection *con, const char *path)
	Send PropertiesChanged for object. More...
void	wpa_dbus_mark_property_changed (struct wpas_dbus_priv *iface, const char *path, const char *interface, const char *property)
	Mark a property as changed and. More...
DBusMessage *	wpa_dbus_introspect (DBusMessage *message, struct wpa_dbus_object_desc *obj_dsc)
	Responds for Introspect calls on object. More...
char *	wpas_dbus_new_decompose_object_path (const char *path, const char *sep, char **item)
	Decompose an interface object path into parts. More...
DBusMessage *	wpas_dbus_reply_new_from_error (DBusMessage *message, DBusError *error, const char *fallback_name, const char *fallback_string)
	Create a new D-Bus error message from a dbus error structure. More...

Detailed Description

WPA Supplicant / dbus-based control interface Copyright (c) 2009, Witold Sowa witol.nosp@m.d.so.nosp@m.wa@gm.nosp@m.ail..nosp@m.com

Function Documentation

void free_dbus_object_desc

(

struct wpa_dbus_object_desc *

obj_dsc

)

Frees object description data structure.

Parameters

connection	DBus connection
obj_dsc	Object description to free

Frees each of properties, methods and signals description lists and the object description structure itself.

int wpa_dbus_ctrl_iface_init	(	struct wpas_dbus_priv *	iface,
		char *	dbus_path,
		char *	dbus_service,
		struct wpa_dbus_object_desc *	obj_desc
	)

Initialize dbus control interface.

Parameters

application_data	Pointer to application specific data structure
dbus_path	DBus path to interface object
dbus_service	DBus service name to register with
messageHandler	a pointer to function which will handle dbus messages coming on interface

Returns

0 on success, -1 on failure

Initialize the dbus control interface and start receiving commands from external programs over the bus.

void wpa_dbus_flush_all_changed_properties

(

DBusConnection *

con

)

Send all PropertiesChanged signals.

Parameters

con	DBus connection

Traverses through all registered objects and sends PropertiesChanged for each properties.

void wpa_dbus_flush_object_changed_properties	(	DBusConnection *	con,
		const char *	path
	)

Send PropertiesChanged for object.

Parameters

con	DBus connection
path	path to a DBus object for which PropertiesChanged will be sent.

Iterates over all properties registered with object and for each interface containing properties marked as changed, sends a PropertiesChanged signal containing names and new values of properties that have changed.

You need to call this function after wpa_dbus_mark_property_changed() if you want to send PropertiesChanged signal immediately (i.e., without waiting timeout to expire). PropertiesChanged signal for an object is sent automatically short time after first marking property as changed. All PropertiesChanged signals are sent automatically after responding on DBus message, so if you marked a property changed as a result of DBus call (e.g., param setter), you usually do not need to call this function.

dbus_bool_t wpa_dbus_get_object_properties	(	struct wpas_dbus_priv *	iface,
		const char *	path,
		const char *	interface,
		DBusMessageIter *	iter
	)

Put object's properties into dictionary.

Parameters

iface	dbus priv struct
path	path to DBus object which properties will be obtained
interface	interface name which properties will be obtained
iter	DBus message iter at which to append property dictionary.

Iterates over all properties registered with object and execute getters of those, which are readable and which interface matches interface specified as argument. Obtained properties values are stored in dict_iter dictionary.

DBusMessage* wpa_dbus_introspect	(	DBusMessage *	message,
		struct wpa_dbus_object_desc *	obj_dsc
	)

Responds for Introspect calls on object.

Parameters

message	Message with Introspect call
obj_dsc	Object description on which Introspect was called

Returns

Message with introspection result XML string as only argument

Iterates over all methods, signals and properties registered with object and generates introspection data for the object as XML string.

void wpa_dbus_mark_property_changed	(	struct wpas_dbus_priv *	iface,
		const char *	path,
		const char *	interface,
		const char *	property
	)

Mark a property as changed and.

Parameters

iface	dbus priv struct
path	path to DBus object which property has changed
interface	interface containing changed property
property	property name which has changed

Iterates over all properties registered with an object and marks the one given in parameters as changed. All parameters registered for an object within a single interface will be aggregated together and sent in one PropertiesChanged signal when function wpa_dbus_flush_object_changed_properties() is called.

int wpa_dbus_register_object_per_iface	(	struct wpas_dbus_priv *	ctrl_iface,
		const char *	path,
		const char *	ifname,
		struct wpa_dbus_object_desc *	obj_desc
	)

Register a new object with dbus.

Parameters

ctrl_iface	pointer to dbus private data
path	DBus path to object
ifname	interface name
obj_desc	description of object's methods, signals and properties

Returns

0 on success, -1 on error

Registers a new interface with dbus and assigns it a dbus object path.

int wpa_dbus_unregister_object_per_iface	(	struct wpas_dbus_priv *	ctrl_iface,
		const char *	path
	)

Unregisters DBus object.

Parameters

ctrl_iface	Pointer to dbus private data
path	DBus path to object which will be unregistered

Returns

Zero on success and -1 on failure

Unregisters DBus object given by its path

char* wpas_dbus_new_decompose_object_path	(	const char *	path,
		const char *	sep,
		char **	item
	)

Decompose an interface object path into parts.

Parameters

path	The dbus object path
sep	Separating part (e.g., "Networks" or "PersistentGroups")
item	(out) The part following the specified separator, if any

Returns

The object path of the interface this path refers to

For a given object path, decomposes the object path into object id and requested part, if those parts exist. The caller is responsible for freeing the returned value. The *item pointer points to that allocated value and must not be freed separately.

As an example, path = "/fi/w1/wpa_supplicant1/Interfaces/1/Networks/0" and sep = "Networks" would result in "/fi/w1/wpa_supplicant1/Interfaces/1" getting returned and *items set to point to "0".

DBusMessage* wpas_dbus_reply_new_from_error	(	DBusMessage *	message,
		DBusError *	error,
		const char *	fallback_name,
		const char *	fallback_string
	)

Create a new D-Bus error message from a dbus error structure.

Parameters

message	The original request message for which the error is a reply
error	The error containing a name and a descriptive error cause
fallback_name	A generic error name if error was not set
fallback_string	A generic error string if error was not set

Returns

A new D-Bus error message

Given a DBusMessage structure, creates a new D-Bus error message using the error name and string contained in that structure.