## DBus GLib low level

DBus GLib low level — DBus lower level functions

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #define             DBUS_TYPE_CONNECTION
    #define             DBUS_TYPE_MESSAGE
    DBusGConnection *   dbus_connection_get_g_connection    (DBusConnection *connection);
    GType               dbus_connection_get_g_type          (void);
    void                dbus_connection_setup_with_g_main   (DBusConnection *connection,
                                                             GMainContext *context);
    DBusConnection *    dbus_g_connection_get_connection    (DBusGConnection *gconnection);
    DBusMessage *       dbus_g_message_get_message          (DBusGMessage *gmessage);
    DBusMessage *       dbus_g_method_get_reply             (DBusGMethodInvocation *context);
    gchar *             dbus_g_method_get_sender            (DBusGMethodInvocation *context);
    void                dbus_g_method_send_reply            (DBusGMethodInvocation *context,
                                                             DBusMessage *reply);
    void                dbus_g_proxy_send                   (DBusGProxy *proxy,
                                                             DBusMessage *message,
                                                             dbus_uint32_t *client_serial);
    GType               dbus_message_get_g_type             (void);
    void                dbus_server_setup_with_g_main       (DBusServer *server,
                                                             GMainContext *context);
    void                dbus_set_g_error                    (GError **gerror,
                                                             DBusError *derror);

## Description

These functions can be used to access lower level of DBus.

## Details

### DBUS_TYPE_CONNECTION

    #define DBUS_TYPE_CONNECTION      (dbus_connection_get_g_type ())

Expands to a function call returning a boxed GType representing a DBusConnection pointer from libdbus. Not to be confused with `DBUS_TYPE_G_CONNECTION`, which you should usually use instead.

Returns : | the GLib type

### DBUS_TYPE_MESSAGE

    #define DBUS_TYPE_MESSAGE         (dbus_message_get_g_type ())

Expands to a function call returning a boxed GType representing a DBusMessage pointer from libdbus. Not to be confused with `DBUS_TYPE_G_MESSAGE`, which you should usually use instead.

Returns : | the GLib type

### dbus_connection_get_g_connection ()

    DBusGConnection *   dbus_connection_get_g_connection    (DBusConnection *connection);

Get the DBusGConnection corresponding to this DBusConnection. This only makes sense if the DBusConnection was originally a DBusGConnection that was registered with the GLib main loop. The return value does not have its refcount incremented.

`connection` : | a DBusConnection
Returns : | DBusGConnection

### dbus_connection_get_g_type ()

    GType               dbus_connection_get_g_type          (void);

### dbus_connection_setup_with_g_main ()

    void                dbus_connection_setup_with_g_main   (DBusConnection *connection,
                                                             GMainContext *context);

Sets the watch and timeout functions of a DBusConnection to integrate the connection with the GLib main loop. Pass in `NULL` for the GMainContext unless you're doing something specialized.

If called twice for the same context, does nothing the second time. If called once with context A and once with context B, context B replaces context A as the context monitoring the connection.

`connection` : | the connection
`context` : | the GMainContext or `NULL` for default context

### dbus_g_connection_get_connection ()

    DBusConnection *    dbus_g_connection_get_connection    (DBusGConnection *gconnection);

Get the DBusConnection corresponding to this DBusGConnection. The return value does not have its refcount incremented.

`gconnection` : | a DBusGConnection
Returns : | DBusConnection

### dbus_g_message_get_message ()

    DBusMessage *       dbus_g_message_get_message          (DBusGMessage *gmessage);

Get the DBusMessage corresponding to this DBusGMessage. The return value does not have its refcount incremented.

`gmessage` : | a DBusGMessage
Returns : | DBusMessage

### dbus_g_method_get_reply ()

    DBusMessage *       dbus_g_method_get_reply             (DBusGMethodInvocation *context);

Get the reply message to append reply values Used as a sidedoor when you can't generate dbus values of the correct type due to glib binding limitations

`context` : | the method context
Returns : | a DBusMessage with the reply

### dbus_g_method_get_sender ()

    gchar *             dbus_g_method_get_sender            (DBusGMethodInvocation *context);

Get the sender of a message so we can send a "reply" later (i.e. send a message directly to a service which invoked the method at a later time).

`context` : | the method context
Returns : | the unique name of the sender. It is up to the caller to free the returned string.

### dbus_g_method_send_reply ()

    void                dbus_g_method_send_reply            (DBusGMethodInvocation *context,
                                                             DBusMessage *reply);

Send a manually created reply message.

Used as a sidedoor when you can't generate dbus values of the correct type due to glib binding limitations

`context` : | the method context
`reply` : | the reply message, will be unreffed

### dbus_g_proxy_send ()

    void                dbus_g_proxy_send                   (DBusGProxy *proxy,
                                                             DBusMessage *message,
                                                             dbus_uint32_t *client_serial);

Sends a message to the interface we're proxying for. Does not block or wait for a reply. The message is only actually written out when you return to the main loop or block in `dbus_g_connection_flush()`.

The message is modified to be addressed to the target interface. That is, a destination name field or whatever is needed will be added to the message. The basic point of this function is to add the necessary header fields, otherwise it's equivalent to `dbus_connection_send()`.

This function adds a reference to the message, so the caller still owns its original reference.

It is an error to call this method on a proxy that has emitted the "destroy" signal.

`proxy` : | a proxy for a remote interface
`message` : | the message to address and send
`client_serial` : | return location for message's serial, or `NULL`

### dbus_message_get_g_type ()

    GType               dbus_message_get_g_type             (void);

### dbus_server_setup_with_g_main ()

    void                dbus_server_setup_with_g_main       (DBusServer *server,
                                                             GMainContext *context);

Sets the watch and timeout functions of a DBusServer to integrate the server with the GLib main loop. In most cases the context argument should be `NULL`.

If called twice for the same context, does nothing the second time. If called once with context A and once with context B, context B replaces context A as the context monitoring the connection.

`server` : | the server
`context` : | the GMainContext or `NULL` for default

### dbus_set_g_error ()

    void                dbus_set_g_error                    (GError **gerror,
                                                             DBusError *derror);

Store the information from a DBus method error return into a GError. For the normal case of an arbitrary remote process, the error code will be DBUS_GERROR_REMOTE_EXCEPTION. Now, DBus errors have two components; a message and a "name". The former is an arbitrary (normally American English) string. The second is a string like com.example.FooFailure which programs can use as a conditional source. Because a GError only has one string, we use a hack to encode both values:

<human readable string><null><error name><null>

You can use the following code to retrieve both values:

    1
    2
    3

    const char *msg = error->message;
    size_t len = strlen(msg);
    const char *error_name = msg+len+1;

`gerror` : | an error
`derror` : | a DBusError