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

The Galago D-BUS service.

GALAGO_DBUS_ERROR_INVALID_ATTRIBUTE

#define     GALAGO_DBUS_ERROR_INVALID_ATTRIBUTE

An "Invalid Attribute" D-BUS message error.

GALAGO_DBUS_ERROR_OBJECT_NOT_FOUND

#define     GALAGO_DBUS_ERROR_OBJECT_NOT_FOUND

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.