D-BUS Utility Functions

D-BUS Utility Functions — D-BUS utility functions.

Synopsis




#define             GALAGO_DBUS_SERVICE
#define             GALAGO_DBUS_ERROR_INVALID_ATTRIBUTE
#define             GALAGO_DBUS_ERROR_OBJECT_NOT_FOUND
void                galago_dbus_message_iter_append_string_or_nil
                                                        (DBusMessageIter *iter,
                                                         const char *str);
const char*         galago_dbus_message_iter_get_string_or_nil
                                                        (DBusMessageIter *iter);
void                galago_dbus_message_iter_append_object
                                                        (DBusMessageIter *iter,
                                                         const GalagoObject *object);
void                galago_dbus_message_iter_append_object_list
                                                        (DBusMessageIter *iter,
                                                         GType type,
                                                         GList *list);
void*               galago_dbus_message_iter_get_object (DBusMessageIter *iter,
                                                         GType type);
GList*              galago_dbus_message_iter_get_object_list
                                                        (DBusMessageIter *iter,
                                                         GType type);
DBusMessage*        galago_dbus_message_new_method_call (const GalagoObject *object,
                                                         const char *name,
                                                         gboolean reply,
                                                         DBusMessageIter *ret_iter);
DBusMessage*        galago_dbus_message_new_method_call_vargs
                                                        (const GalagoObject *object,
                                                         const char *name,
                                                         gboolean reply,
                                                         va_list args);
DBusMessage*        galago_dbus_message_new_method_call_args
                                                        (const GalagoObject *object,
                                                         const char *name,
                                                         gboolean reply,
                                                         ...);
void                galago_dbus_send_message            (const GalagoObject *object,
                                                         const char *name,
                                                         ...);
GList*              galago_dbus_send_message_with_reply_list
                                                        (const GalagoObject *object,
                                                         const char *name,
                                                         GList *return_types,
                                                         ...);
void*               galago_dbus_send_message_with_reply (const GalagoObject *object,
                                                         const char *name,
                                                         GalagoValue *return_type,
                                                         ...);
void                galago_dbus_object_push_full        (GalagoObject *object);

Description

A set of Galago-specific utility functions for working with D-BUS. These functions should be considered semi-public, but are expected to change in time.

Details

GALAGO_DBUS_SERVICE

#define GALAGO_DBUS_SERVICE "org.freedesktop.Galago"

The Galago D-BUS service.


GALAGO_DBUS_ERROR_INVALID_ATTRIBUTE

#define GALAGO_DBUS_ERROR_INVALID_ATTRIBUTE "org.freedesktop.Galago.Error.InvalidAttribute"

An "Invalid Attribute" D-BUS message error.


GALAGO_DBUS_ERROR_OBJECT_NOT_FOUND

#define GALAGO_DBUS_ERROR_OBJECT_NOT_FOUND "org.freedesktop.Galago.Error.ObjectNotFound"

An "Object Not Found" D-BUS message error.


galago_dbus_message_iter_append_string_or_nil ()

void                galago_dbus_message_iter_append_string_or_nil
                                                        (DBusMessageIter *iter,
                                                         const char *str);

Appends a string to a message, or an empty string if the passed string is NULL.

iter : The message iterator.
str : The string, or NULL.

galago_dbus_message_iter_get_string_or_nil ()

const char*         galago_dbus_message_iter_get_string_or_nil
                                                        (DBusMessageIter *iter);

Returns a string that the iterator points to. If the returned string is an empty string (""), this returns NULL.

iter : The iterator.
Returns : The string or NULL.

galago_dbus_message_iter_append_object ()

void                galago_dbus_message_iter_append_object
                                                        (DBusMessageIter *iter,
                                                         const GalagoObject *object);

Appends an object to a D-BUS message.

iter : The D-BUS message iterator.
object : The object to append.

galago_dbus_message_iter_append_object_list ()

void                galago_dbus_message_iter_append_object_list
                                                        (DBusMessageIter *iter,
                                                         GType type,
                                                         GList *list);

Appends a list of objects to a D-BUS message.

iter : The D-BUS message iterator.
type : The type of the objects inside.
list : The list of objects to append.

galago_dbus_message_iter_get_object ()

void*               galago_dbus_message_iter_get_object (DBusMessageIter *iter,
                                                         GType type);

Returns an object of the specified type from a D-BUS message.

iter : The D-BUS message iterator.
type : The GType.
Returns : The object.

galago_dbus_message_iter_get_object_list ()

GList*              galago_dbus_message_iter_get_object_list
                                                        (DBusMessageIter *iter,
                                                         GType type);

Returns a list of objects of the specified type from a D-BUS message. The returned list must be destroyed.

iter : The D-BUS message iterator.
type : The GType.
Returns : The list.

galago_dbus_message_new_method_call ()

DBusMessage*        galago_dbus_message_new_method_call (const GalagoObject *object,
                                                         const char *name,
                                                         gboolean reply,
                                                         DBusMessageIter *ret_iter);

Creates a D-BUS message to the specified object.

object : The object.
name : The message name.
reply : TRUE if a reply is expected.
ret_iter : The returned message iterator, if not NULL.
Returns : The D-BUS message.

galago_dbus_message_new_method_call_vargs ()

DBusMessage*        galago_dbus_message_new_method_call_vargs
                                                        (const GalagoObject *object,
                                                         const char *name,
                                                         gboolean reply,
                                                         va_list args);

Creates a D-BUS message to the specified object with a va_list of parameters.

object : The object.
name : The message name.
reply : TRUE if a reply is expected.
args : The va_list of parameters.
Returns : The D-BUS message.

galago_dbus_message_new_method_call_args ()

DBusMessage*        galago_dbus_message_new_method_call_args
                                                        (const GalagoObject *object,
                                                         const char *name,
                                                         gboolean reply,
                                                         ...);

Creates a D-BUS message to the specified object with a list of parameters.

The parameters passed are in GalagoValue, pointer-to-data form.

object : The object.
name : The message name.
reply : TRUE if a reply is expected.
... : The list of parameters.
Returns : The D-BUS message.

galago_dbus_send_message ()

void                galago_dbus_send_message            (const GalagoObject *object,
                                                         const char *name,
                                                         ...);

Sends a new D-BUS message with an object, name, and parameters.

The parameters passed are in GalagoValue, pointer-to-data form.

object : The object.
name : The message name.
... : The list of parameters.

galago_dbus_send_message_with_reply_list ()

GList*              galago_dbus_send_message_with_reply_list
                                                        (const GalagoObject *object,
                                                         const char *name,
                                                         GList *return_types,
                                                         ...);

Sends a new D-BUS message with an object, name, and parameters, and waits for a reply with a variable list of return types.

The parameters passed are in GalagoValue, pointer-to-data form.

object : The object.
name : The message name.
return_types : A list of expected return types, in order.
... : The list of parameters.
Returns : The returned data in a list. The list will need to be g_freed, as may some of its data.

galago_dbus_send_message_with_reply ()

void*               galago_dbus_send_message_with_reply (const GalagoObject *object,
                                                         const char *name,
                                                         GalagoValue *return_type,
                                                         ...);

Sends a new D-BUS message with an object, name, and parameters, and waits for a reply.

The parameters passed are in GalagoValue, pointer-to-data form.

object : The object.
name : The message name.
return_type : The expected return type.
... : The list of parameters.
Returns : The returned data. This may need to be g_freed.

galago_dbus_object_push_full ()

void                galago_dbus_object_push_full        (GalagoObject *object);

Pushes an object and all its internal data to the server.

This is meant for internal use.

object : The object to push.