D-BUS Utility Functions

## 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.