GDBusConnection: GIO Reference Manual

## GDBusConnection GDBusConnection — D-Bus Connections |

## Functions

void | g_bus_get ()
GDBusConnection * | g_bus_get_finish ()
GDBusConnection * | g_bus_get_sync ()
void | g_dbus_connection_new ()
GDBusConnection * | g_dbus_connection_new_finish ()
GDBusConnection * | g_dbus_connection_new_sync ()
void | g_dbus_connection_new_for_address ()
GDBusConnection * | g_dbus_connection_new_for_address_finish ()
GDBusConnection * | g_dbus_connection_new_for_address_sync ()
void | g_dbus_connection_start_message_processing ()
void | g_dbus_connection_close ()
gboolean | g_dbus_connection_close_finish ()
gboolean | g_dbus_connection_close_sync ()
gboolean | g_dbus_connection_is_closed ()
void | g_dbus_connection_flush ()
gboolean | g_dbus_connection_flush_finish ()
gboolean | g_dbus_connection_flush_sync ()
gboolean | g_dbus_connection_get_exit_on_close ()
void | g_dbus_connection_set_exit_on_close ()
GIOStream * | g_dbus_connection_get_stream ()
const gchar * | g_dbus_connection_get_guid ()
const gchar * | g_dbus_connection_get_unique_name ()
GDBusCapabilityFlags | g_dbus_connection_get_capabilities ()
GCredentials * | g_dbus_connection_get_peer_credentials ()
guint32 | g_dbus_connection_get_last_serial ()
void | g_dbus_connection_call ()
GVariant * | g_dbus_connection_call_finish ()
GVariant * | g_dbus_connection_call_sync ()
void | g_dbus_connection_call_with_unix_fd_list ()
GVariant * | g_dbus_connection_call_with_unix_fd_list_finish ()
GVariant * | g_dbus_connection_call_with_unix_fd_list_sync ()
gboolean | g_dbus_connection_emit_signal ()
void | (*GDBusSignalCallback) ()
guint | g_dbus_connection_signal_subscribe ()
void | g_dbus_connection_signal_unsubscribe ()
gboolean | g_dbus_connection_send_message ()
void | g_dbus_connection_send_message_with_reply ()
GDBusMessage * | g_dbus_connection_send_message_with_reply_finish ()
GDBusMessage * | g_dbus_connection_send_message_with_reply_sync ()
GDBusMessage * | (*GDBusMessageFilterFunction) ()
guint | g_dbus_connection_add_filter ()
void | g_dbus_connection_remove_filter ()
void | (*GDBusInterfaceMethodCallFunc) ()
GVariant * | (*GDBusInterfaceGetPropertyFunc) ()
gboolean | (*GDBusInterfaceSetPropertyFunc) ()
guint | g_dbus_connection_register_object ()
gboolean | g_dbus_connection_unregister_object ()
guint | g_dbus_connection_register_object_with_closures ()
gchar ** | (*GDBusSubtreeEnumerateFunc) ()
GDBusInterfaceInfo ** | (*GDBusSubtreeIntrospectFunc) ()
const GDBusInterfaceVTable * | (*GDBusSubtreeDispatchFunc) ()
guint | g_dbus_connection_register_subtree ()
gboolean | g_dbus_connection_unregister_subtree ()

## Properties

gchar * | address | Write / Construct Only
GDBusAuthObserver * | authentication-observer | Write / Construct Only
GDBusCapabilityFlags | capabilities | Read
gboolean | closed | Read
gboolean | exit-on-close | Read / Write
GDBusConnectionFlags | flags | Write / Construct Only
gchar * | guid | Read / Write / Construct Only
GIOStream * | stream | Read / Write / Construct Only
gchar * | unique-name | Read

## Signals

void | closed | Run Last

## Types and Values

enum | GBusType
| GDBusConnection
enum | GDBusConnectionFlags
enum | GDBusCapabilityFlags
enum | GDBusCallFlags
enum | GDBusSignalFlags
enum | GDBusSendMessageFlags
| GDBusInterfaceVTable
| GDBusSubtreeVTable
enum | GDBusSubtreeFlags

## Object Hierarchy

        GObject
        ╰── GDBusConnection

## Implemented Interfaces

GDBusConnection implements GInitable and GAsyncInitable.

## Includes

    #include <gio/gio.h>

## Description

The GDBusConnection type is used for D-Bus connections to remote peers such as a message buses. It is a low-level API that offers a lot of flexibility. For instance, it lets you establish a connection over any transport that can by represented as an GIOStream.

This class is rarely used directly in D-Bus clients. If you are writing a D-Bus client, it is often easier to use the `g_bus_own_name()`, `g_bus_watch_name()` or `g_dbus_proxy_new_for_bus()` APIs.

As an exception to the usual GLib rule that a particular object must not be used by two threads at the same time, GDBusConnection's methods may be called from any thread. This is so that `g_bus_get()` and `g_bus_get_sync()` can safely return the same GDBusConnection when called from any thread.

Most of the ways to obtain a GDBusConnection automatically initialize it (i.e. connect to D-Bus): for instance, `g_dbus_connection_new()` and `g_bus_get()`, and the synchronous versions of those methods, give you an initialized connection. Language bindings for GIO should use `g_initable_new()` or `g_async_initable_new_async()`, which also initialize the connection.

If you construct an uninitialized GDBusConnection, such as via `g_object_new()`, you must initialize it via `g_initable_init()` or `g_async_initable_init_async()` before using its methods or properties. Calling methods or accessing properties on a GDBusConnection that has not completed initialization successfully is considered to be invalid, and leads to undefined behaviour. In particular, if initialization fails with a GError, the only valid thing you can do with that GDBusConnection is to free it with `g_object_unref()`.

#### An example D-Bus server

Here is an example for a D-Bus server: gdbus-example-server.c

#### An example for exporting a subtree

Here is an example for exporting a subtree: gdbus-example-subtree.c

#### An example for file descriptor passing

Here is an example for passing UNIX file descriptors: gdbus-unix-fd-client.c

#### An example for exporting a GObject

Here is an example for exporting a GObject: gdbus-example-export.c

## Functions

### g_bus_get ()

    void
    g_bus_get (GBusType bus_type,
               GCancellable *cancellable,
               GAsyncReadyCallback callback,
               gpointer user_data);

Asynchronously connects to the message bus specified by `bus_type` .

When the operation is finished, `callback` will be invoked. You can then call `g_bus_get_finish()` to get the result of the operation.

This is a asynchronous failable function. See `g_bus_get_sync()` for the synchronous version.

#### Parameters

bus_type | a GBusType |
cancellable | a GCancellable or `NULL`. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | the data to pass to `callback` |

Since: 2.26

### g_bus_get_finish ()

    GDBusConnection *
    g_bus_get_finish (GAsyncResult *res,
                      GError **error);

Finishes an operation started with `g_bus_get()`.

The returned object is a singleton, that is, shared with other callers of `g_bus_get()` and `g_bus_get_sync()` for `bus_type` . In the event that you need a private message bus connection, use `g_dbus_address_get_for_bus_sync()` and `g_dbus_connection_new_for_address()`.

Note that the returned GDBusConnection object will (usually) have the “exit-on-close” property set to `TRUE`.

#### Parameters

res | a GAsyncResult obtained from the GAsyncReadyCallback passed to `g_bus_get()` |
error | return location for error or `NULL` |

#### Returns

a GDBusConnection or `NULL` if `error` is set. Free with `g_object_unref()`.

[transfer full]

Since: 2.26

### g_bus_get_sync ()

    GDBusConnection *
    g_bus_get_sync (GBusType bus_type,
                    GCancellable *cancellable,
                    GError **error);

Synchronously connects to the message bus specified by `bus_type` . Note that the returned object may shared with other callers, e.g. if two separate parts of a process calls this function with the same `bus_type` , they will share the same object.

This is a synchronous failable function. See `g_bus_get()` and `g_bus_get_finish()` for the asynchronous version.

The returned object is a singleton, that is, shared with other callers of `g_bus_get()` and `g_bus_get_sync()` for `bus_type` . In the event that you need a private message bus connection, use `g_dbus_address_get_for_bus_sync()` and `g_dbus_connection_new_for_address()`.

Note that the returned GDBusConnection object will (usually) have the “exit-on-close” property set to `TRUE`.

#### Parameters

bus_type | a GBusType |
cancellable | a GCancellable or `NULL`. | [nullable]
error | return location for error or `NULL` |

#### Returns

a GDBusConnection or `NULL` if `error` is set. Free with `g_object_unref()`.

[transfer full]

Since: 2.26

### g_dbus_connection_new ()

    void
    g_dbus_connection_new (GIOStream *stream,
                           const gchar *guid,
                           GDBusConnectionFlags flags,
                           GDBusAuthObserver *observer,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Asynchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by `stream` .

If `stream` is a GSocketConnection, then the corresponding GSocket will be put into non-blocking mode.

The D-Bus connection will interact with `stream` from a worker thread. As a result, the caller should not interact with `stream` after this method has been called, except by calling `g_object_unref()` on it.

If `observer` is not `NULL` it may be used to control the authentication process.

When the operation is finished, `callback` will be invoked. You can then call `g_dbus_connection_new_finish()` to get the result of the operation.

This is a asynchronous failable constructor. See `g_dbus_connection_new_sync()` for the synchronous version.

#### Parameters

stream | a GIOStream |
guid | the GUID to use if a authenticating as a server or `NULL`. | [nullable]
flags | flags describing how to make the connection |
observer | a GDBusAuthObserver or `NULL`. | [nullable]
cancellable | a GCancellable or `NULL`. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | the data to pass to `callback` |

Since: 2.26

### g_dbus_connection_new_finish ()

    GDBusConnection *
    g_dbus_connection_new_finish (GAsyncResult *res,
                                  GError **error);

Finishes an operation started with `g_dbus_connection_new()`.

#### Parameters

res | a GAsyncResult obtained from the GAsyncReadyCallback passed to `g_dbus_connection_new()`. |
error | return location for error or `NULL` |

#### Returns

a GDBusConnection or `NULL` if `error` is set. Free with `g_object_unref()`.

Since: 2.26

### g_dbus_connection_new_sync ()

    GDBusConnection *
    g_dbus_connection_new_sync (GIOStream *stream,
                                const gchar *guid,
                                GDBusConnectionFlags flags,
                                GDBusAuthObserver *observer,
                                GCancellable *cancellable,
                                GError **error);

Synchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by `stream` .

If `stream` is a GSocketConnection, then the corresponding GSocket will be put into non-blocking mode.

The D-Bus connection will interact with `stream` from a worker thread. As a result, the caller should not interact with `stream` after this method has been called, except by calling `g_object_unref()` on it.

If `observer` is not `NULL` it may be used to control the authentication process.

This is a synchronous failable constructor. See `g_dbus_connection_new()` for the asynchronous version.

#### Parameters

stream | a GIOStream |
guid | the GUID to use if a authenticating as a server or `NULL`. | [nullable]
flags | flags describing how to make the connection |
observer | a GDBusAuthObserver or `NULL`. | [nullable]
cancellable | a GCancellable or `NULL`. | [nullable]
error | return location for error or `NULL` |

#### Returns

a GDBusConnection or `NULL` if `error` is set. Free with `g_object_unref()`.

Since: 2.26

### g_dbus_connection_new_for_address ()

    void
    g_dbus_connection_new_for_address (const gchar *address,
                                       GDBusConnectionFlags flags,
                                       GDBusAuthObserver *observer,
                                       GCancellable *cancellable,
                                       GAsyncReadyCallback callback,
                                       gpointer user_data);

Asynchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by `address` which must be in the D-Bus address format.

This constructor can only be used to initiate client-side connections - use `g_dbus_connection_new()` if you need to act as the server. In particular, `flags` cannot contain the `G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER` or `G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS` flags.

When the operation is finished, `callback` will be invoked. You can then call `g_dbus_connection_new_finish()` to get the result of the operation.

If `observer` is not `NULL` it may be used to control the authentication process.

This is a asynchronous failable constructor. See `g_dbus_connection_new_for_address_sync()` for the synchronous version.

#### Parameters

address | a D-Bus address |
flags | flags describing how to make the connection |
observer | a GDBusAuthObserver or `NULL`. | [nullable]
cancellable | a GCancellable or `NULL`. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | the data to pass to `callback` |

Since: 2.26

### g_dbus_connection_new_for_address_finish ()

    GDBusConnection *
    g_dbus_connection_new_for_address_finish
                                   (GAsyncResult *res,
                                    GError **error);

Finishes an operation started with `g_dbus_connection_new_for_address()`.

#### Parameters

res | a GAsyncResult obtained from the GAsyncReadyCallback passed to `g_dbus_connection_new()` |
error | return location for error or `NULL` |

#### Returns

a GDBusConnection or `NULL` if `error` is set. Free with `g_object_unref()`.

Since: 2.26

### g_dbus_connection_new_for_address_sync ()

    GDBusConnection *
    g_dbus_connection_new_for_address_sync
                                   (const gchar *address,
                                    GDBusConnectionFlags flags,
                                    GDBusAuthObserver *observer,
                                    GCancellable *cancellable,
                                    GError **error);

Synchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by `address` which must be in the D-Bus address format.

This constructor can only be used to initiate client-side connections - use `g_dbus_connection_new_sync()` if you need to act as the server. In particular, `flags` cannot contain the `G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER` or `G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS` flags.

This is a synchronous failable constructor. See `g_dbus_connection_new_for_address()` for the asynchronous version.

If `observer` is not `NULL` it may be used to control the authentication process.

#### Parameters

address | a D-Bus address |
flags | flags describing how to make the connection |
observer | a GDBusAuthObserver or `NULL`. | [nullable]
cancellable | a GCancellable or `NULL`. | [nullable]
error | return location for error or `NULL` |

#### Returns

a GDBusConnection or `NULL` if `error` is set. Free with `g_object_unref()`.

Since: 2.26

### g_dbus_connection_start_message_processing ()

    void
    g_dbus_connection_start_message_processing
                                   (GDBusConnection *connection);

If `connection` was created with `G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING`, this method starts processing messages. Does nothing on if `connection` wasn't created with this flag or if the method has already been called.

#### Parameters

connection | a GDBusConnection |

Since: 2.26

### g_dbus_connection_close ()

    void
    g_dbus_connection_close (GDBusConnection *connection,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Closes `connection` . Note that this never causes the process to exit (this might only happen if the other end of a shared message bus connection disconnects, see “exit-on-close”).

Once the connection is closed, operations such as sending a message will return with the error `G_IO_ERROR_CLOSED`. Closing a connection will not automatically flush the connection so queued messages may be lost. Use `g_dbus_connection_flush()` if you need such guarantees.

If `connection` is already closed, this method fails with `G_IO_ERROR_CLOSED`.

When `connection` has been closed, the “closed” signal is emitted in the thread-default main context of the thread that `connection` was constructed in.

This is an asynchronous method. When the operation is finished, `callback` will be invoked in the thread-default main context of the thread you are calling this method from. You can then call `g_dbus_connection_close_finish()` to get the result of the operation. See `g_dbus_connection_close_sync()` for the synchronous version.

#### Parameters

connection | a GDBusConnection |
cancellable | a GCancellable or `NULL`. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied or `NULL` if you don't care about the result. | [nullable]
user_data | The data to pass to `callback` |

Since: 2.26

### g_dbus_connection_close_finish ()

    gboolean
    g_dbus_connection_close_finish (GDBusConnection *connection,
                                    GAsyncResult *res,
                                    GError **error);

Finishes an operation started with `g_dbus_connection_close()`.

#### Parameters

connection | a GDBusConnection |
res | a GAsyncResult obtained from the GAsyncReadyCallback passed to `g_dbus_connection_close()` |
error | return location for error or `NULL` |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set

Since: 2.26

### g_dbus_connection_close_sync ()

    gboolean
    g_dbus_connection_close_sync (GDBusConnection *connection,
                                  GCancellable *cancellable,
                                  GError **error);

Synchronously closees `connection` . The calling thread is blocked until this is done. See `g_dbus_connection_close()` for the asynchronous version of this method and more details about what it does.

#### Parameters

connection | a GDBusConnection |
cancellable | a GCancellable or `NULL`. | [nullable]
error | return location for error or `NULL` |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set

Since: 2.26

### g_dbus_connection_is_closed ()

    gboolean
    g_dbus_connection_is_closed (GDBusConnection *connection);

Gets whether `connection` is closed.

#### Parameters

connection | a GDBusConnection |

#### Returns

`TRUE` if the connection is closed, `FALSE` otherwise

Since: 2.26

### g_dbus_connection_flush ()

    void
    g_dbus_connection_flush (GDBusConnection *connection,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Asynchronously flushes `connection` , that is, writes all queued outgoing message to the transport and then flushes the transport (using `g_output_stream_flush_async()`). This is useful in programs that wants to emit a D-Bus signal and then exit immediately. Without flushing the connection, there is no guaranteed that the message has been sent to the networking buffers in the OS kernel.

This is an asynchronous method. When the operation is finished, `callback` will be invoked in the thread-default main context of the thread you are calling this method from. You can then call `g_dbus_connection_flush_finish()` to get the result of the operation. See `g_dbus_connection_flush_sync()` for the synchronous version.

#### Parameters

connection | a GDBusConnection |
cancellable | a GCancellable or `NULL`. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied or `NULL` if you don't care about the result. | [nullable]
user_data | The data to pass to `callback` |

Since: 2.26

### g_dbus_connection_flush_finish ()

    gboolean
    g_dbus_connection_flush_finish (GDBusConnection *connection,
                                    GAsyncResult *res,
                                    GError **error);

Finishes an operation started with `g_dbus_connection_flush()`.

#### Parameters

connection | a GDBusConnection |
res | a GAsyncResult obtained from the GAsyncReadyCallback passed to `g_dbus_connection_flush()` |
error | return location for error or `NULL` |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set

Since: 2.26

### g_dbus_connection_flush_sync ()

    gboolean
    g_dbus_connection_flush_sync (GDBusConnection *connection,
                                  GCancellable *cancellable,
                                  GError **error);

Synchronously flushes `connection` . The calling thread is blocked until this is done. See `g_dbus_connection_flush()` for the asynchronous version of this method and more details about what it does.

#### Parameters

connection | a GDBusConnection |
cancellable | a GCancellable or `NULL`. | [nullable]
error | return location for error or `NULL` |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if `error` is set

Since: 2.26

### g_dbus_connection_get_exit_on_close ()

    gboolean
    g_dbus_connection_get_exit_on_close (GDBusConnection *connection);

Gets whether the process is terminated when `connection` is closed by the remote peer. See “exit-on-close” for more details.

#### Parameters

connection | a GDBusConnection |

#### Returns

whether the process is terminated when `connection` is closed by the remote peer

Since: 2.26

### g_dbus_connection_set_exit_on_close ()

    void
    g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
                                         gboolean exit_on_close);

Sets whether the process should be terminated when `connection` is closed by the remote peer. See “exit-on-close” for more details.

Note that this function should be used with care. Most modern UNIX desktops tie the notion of a user session the session bus, and expect all of a users applications to quit when their bus connection goes away. If you are setting `exit_on_close` to `FALSE` for the shared session bus connection, you should make sure that your application exits when the user session ends.

#### Parameters

connection | a GDBusConnection |
exit_on_close | whether the process should be terminated when `connection` is closed by the remote peer |

Since: 2.26

### g_dbus_connection_get_stream ()

    GIOStream *
    g_dbus_connection_get_stream (GDBusConnection *connection);

Gets the underlying stream used for IO.

While the GDBusConnection is active, it will interact with this stream from a worker thread, so it is not safe to interact with the stream directly.

#### Parameters

connection | a GDBusConnection |

#### Returns

the stream used for IO.

[transfer none]

Since: 2.26

### g_dbus_connection_get_guid ()

    const gchar *
    g_dbus_connection_get_guid (GDBusConnection *connection);

The GUID of the peer performing the role of server when authenticating. See “guid” for more details.

#### Parameters

connection | a GDBusConnection |

#### Returns

The GUID. Do not free this string, it is owned by `connection` .

Since: 2.26

### g_dbus_connection_get_unique_name ()

    const gchar *
    g_dbus_connection_get_unique_name (GDBusConnection *connection);

Gets the unique name of `connection` as assigned by the message bus. This can also be used to figure out if `connection` is a message bus connection.

#### Parameters

connection | a GDBusConnection |

#### Returns

the unique name or `NULL` if `connection` is not a message bus connection. Do not free this string, it is owned by `connection` .

Since: 2.26

### g_dbus_connection_get_capabilities ()

    GDBusCapabilityFlags
    g_dbus_connection_get_capabilities (GDBusConnection *connection);

Gets the capabilities negotiated with the remote peer

#### Parameters

connection | a GDBusConnection |

#### Returns

zero or more flags from the GDBusCapabilityFlags enumeration

Since: 2.26

### g_dbus_connection_get_peer_credentials ()

    GCredentials *
    g_dbus_connection_get_peer_credentials
                                   (GDBusConnection *connection);

Gets the credentials of the authenticated peer. This will always return `NULL` unless `connection` acted as a server (e.g. `G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER` was passed) when set up and the client passed credentials as part of the authentication process.

In a message bus setup, the message bus is always the server and each application is a client. So this method will always return `NULL` for message bus clients.

#### Parameters

connection | a GDBusConnection |

#### Returns

a GCredentials or `NULL` if not available. Do not free this object, it is owned by `connection` .

[transfer none][nullable]

Since: 2.26

### g_dbus_connection_get_last_serial ()

    guint32
    g_dbus_connection_get_last_serial (GDBusConnection *connection);

Retrieves the last serial number assigned to a GDBusMessage on the current thread. This includes messages sent via both low-level API such as `g_dbus_connection_send_message()` as well as high-level API such as `g_dbus_connection_emit_signal()`, `g_dbus_connection_call()` or `g_dbus_proxy_call()`.

#### Parameters

connection | a GDBusConnection |

#### Returns

the last used serial or zero when no message has been sent within the current thread

Since: 2.34

### g_dbus_connection_call ()

    void
    g_dbus_connection_call (GDBusConnection *connection,
                            const gchar *bus_name,
                            const gchar *object_path,
                            const gchar *interface_name,
                            const gchar *method_name,
                            GVariant *parameters,
                            const GVariantType *reply_type,
                            GDBusCallFlags flags,
                            gint timeout_msec,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Asynchronously invokes the `method_name` method on the `interface_name` D-Bus interface on the remote object at `object_path` owned by `bus_name` .

If `connection` is closed then the operation will fail with `G_IO_ERROR_CLOSED`. If `cancellable` is canceled, the operation will fail with `G_IO_ERROR_CANCELLED`. If `parameters` contains a value not compatible with the D-Bus protocol, the operation fails with `G_IO_ERROR_INVALID_ARGUMENT`.

If `reply_type` is non-`NULL` then the reply will be checked for having this type and an error will be raised if it does not match. Said another way, if you give a `reply_type` then any non-`NULL` return value will be of this type.

If the `parameters` GVariant is floating, it is consumed. This allows convenient 'inline' use of `g_variant_new()`, e.g.:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    g_dbus_connection_call (connection,
                            "org.freedesktop.StringThings",
                            "/org/freedesktop/StringThings",
                            "org.freedesktop.StringThings",
                            "TwoStrings",
                            g_variant_new ("(ss)",
                                           "Thing One",
                                           "Thing Two"),
                            NULL,
                            G_DBUS_CALL_FLAGS_NONE,
                            -1,
                            NULL,
                            (GAsyncReadyCallback) two_strings_done,
                            NULL);

This is an asynchronous method. When the operation is finished, `callback` will be invoked in the thread-default main context of the thread you are calling this method from. You can then call `g_dbus_connection_call_finish()` to get the result of the operation. See `g_dbus_connection_call_sync()` for the synchronous version of this function.

If `callback` is `NULL` then the D-Bus method call message will be sent with the `G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED` flag set.

#### Parameters

connection | a GDBusConnection |
bus_name | a unique or well-known bus name or `NULL` if `connection` is not a message bus connection. | [nullable]
object_path | path of remote object |
interface_name | D-Bus interface to invoke method on |
method_name | the name of the method to invoke |
parameters | a GVariant tuple with parameters for the method or `NULL` if not passing parameters. | [nullable]
reply_type | the expected type of the reply, or `NULL`. | [nullable]
flags | flags from the GDBusCallFlags enumeration |
timeout_msec | the timeout in milliseconds, -1 to use the default timeout or `G_MAXINT` for no timeout |
cancellable | a GCancellable or `NULL`. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied or `NULL` if you don't care about the result of the method invocation. | [nullable]
user_data | the data to pass to `callback` |

Since: 2.26

### g_dbus_connection_call_finish ()

    GVariant *
    g_dbus_connection_call_finish (GDBusConnection *connection,
                                   GAsyncResult *res,
                                   GError **error);

Finishes an operation started with `g_dbus_connection_call()`.

#### Parameters

connection | a GDBusConnection |
res | a GAsyncResult obtained from the GAsyncReadyCallback passed to `g_dbus_connection_call()` |
error | return location for error or `NULL` |

#### Returns

`NULL` if `error` is set. Otherwise a GVariant tuple with return values. Free with `g_variant_unref()`.

Since: 2.26

### g_dbus_connection_call_sync ()

    GVariant *
    g_dbus_connection_call_sync (GDBusConnection *connection,
                                 const gchar *bus_name,
                                 const gchar *object_path,
                                 const gchar *interface_name,
                                 const gchar *method_name,
                                 GVariant *parameters,
                                 const GVariantType *reply_type,
                                 GDBusCallFlags flags,
                                 gint timeout_msec,
                                 GCancellable *cancellable,
                                 GError **error);

Synchronously invokes the `method_name` method on the `interface_name` D-Bus interface on the remote object at `object_path` owned by `bus_name` .

If `connection` is closed then the operation will fail with `G_IO_ERROR_CLOSED`. If `cancellable` is canceled, the operation will fail with `G_IO_ERROR_CANCELLED`. If `parameters` contains a value not compatible with the D-Bus protocol, the operation fails with `G_IO_ERROR_INVALID_ARGUMENT`.

If `reply_type` is non-`NULL` then the reply will be checked for having this type and an error will be raised if it does not match. Said another way, if you give a `reply_type` then any non-`NULL` return value will be of this type.

If the `parameters` GVariant is floating, it is consumed. This allows convenient 'inline' use of `g_variant_new()`, e.g.:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    g_dbus_connection_call_sync (connection,
                                 "org.freedesktop.StringThings",
                                 "/org/freedesktop/StringThings",
                                 "org.freedesktop.StringThings",
                                 "TwoStrings",
                                 g_variant_new ("(ss)",
                                                "Thing One",
                                                "Thing Two"),
                                 NULL,
                                 G_DBUS_CALL_FLAGS_NONE,
                                 -1,
                                 NULL,
                                 &error);

The calling thread is blocked until a reply is received. See `g_dbus_connection_call()` for the asynchronous version of this method.

#### Parameters

connection | a GDBusConnection |
bus_name | a unique or well-known bus name or `NULL` if `connection` is not a message bus connection. | [nullable]
object_path | path of remote object |
interface_name | D-Bus interface to invoke method on |
method_name | the name of the method to invoke |
parameters | a GVariant tuple with parameters for the method or `NULL` if not passing parameters. | [nullable]
reply_type | the expected type of the reply, or `NULL`. | [nullable]
flags | flags from the GDBusCallFlags enumeration |
timeout_msec | the timeout in milliseconds, -1 to use the default timeout or `G_MAXINT` for no timeout |
cancellable | a GCancellable or `NULL`. | [nullable]
error | return location for error or `NULL` |

#### Returns

`NULL` if `error` is set. Otherwise a GVariant tuple with return values. Free with `g_variant_unref()`.

Since: 2.26

### g_dbus_connection_call_with_unix_fd_list ()

    void
    g_dbus_connection_call_with_unix_fd_list
                                   (GDBusConnection *connection,
                                    const gchar *bus_name,
                                    const gchar *object_path,
                                    const gchar *interface_name,
                                    const gchar *method_name,
                                    GVariant *parameters,
                                    const GVariantType *reply_type,
                                    GDBusCallFlags flags,
                                    gint timeout_msec,
                                    GUnixFDList *fd_list,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Like `g_dbus_connection_call()` but also takes a GUnixFDList object.

This method is only available on UNIX.

#### Parameters

connection | a GDBusConnection |
bus_name | a unique or well-known bus name or `NULL` if `connection` is not a message bus connection. | [nullable]
object_path | path of remote object |
interface_name | D-Bus interface to invoke method on |
method_name | the name of the method to invoke |
parameters | a GVariant tuple with parameters for the method or `NULL` if not passing parameters. | [nullable]
reply_type | the expected type of the reply, or `NULL`. | [nullable]
flags | flags from the GDBusCallFlags enumeration |
timeout_msec | the timeout in milliseconds, -1 to use the default timeout or `G_MAXINT` for no timeout |
fd_list | a GUnixFDList or `NULL`. | [nullable]
cancellable | a GCancellable or `NULL`. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied or `NULL` if you don't * care about the result of the method invocation. | [nullable]
user_data | The data to pass to `callback` . |

Since: 2.30

### g_dbus_connection_call_with_unix_fd_list_finish ()

    GVariant *
    g_dbus_connection_call_with_unix_fd_list_finish
                                   (GDBusConnection *connection,
                                    GUnixFDList **out_fd_list,
                                    GAsyncResult *res,
                                    GError **error);

Finishes an operation started with `g_dbus_connection_call_with_unix_fd_list()`.

#### Parameters

connection | a GDBusConnection |
out_fd_list | return location for a GUnixFDList or `NULL`. | [out][optional]
res | a GAsyncResult obtained from the GAsyncReadyCallback passed to `g_dbus_connection_call_with_unix_fd_list()` |
error | return location for error or `NULL` |

#### Returns

`NULL` if `error` is set. Otherwise a GVariant tuple with return values. Free with `g_variant_unref()`.

Since: 2.30

### g_dbus_connection_call_with_unix_fd_list_sync ()

    GVariant *
    g_dbus_connection_call_with_unix_fd_list_sync
                                   (GDBusConnection *connection,
                                    const gchar *bus_name,
                                    const gchar *object_path,
                                    const gchar *interface_name,
                                    const gchar *method_name,
                                    GVariant *parameters,
                                    const GVariantType *reply_type,
                                    GDBusCallFlags flags,
                                    gint timeout_msec,
                                    GUnixFDList *fd_list,
                                    GUnixFDList **out_fd_list,
                                    GCancellable *cancellable,
                                    GError **error);

Like `g_dbus_connection_call_sync()` but also takes and returns GUnixFDList objects.

This method is only available on UNIX.

#### Parameters

connection | a GDBusConnection |
bus_name | a unique or well-known bus name or `NULL` if `connection` is not a message bus connection. | [nullable]
object_path | path of remote object |
interface_name | D-Bus interface to invoke method on |
method_name | the name of the method to invoke |
parameters | a GVariant tuple with parameters for the method or `NULL` if not passing parameters. | [nullable]
reply_type | the expected type of the reply, or `NULL`. | [nullable]
flags | flags from the GDBusCallFlags enumeration |
timeout_msec | the timeout in milliseconds, -1 to use the default timeout or `G_MAXINT` for no timeout |
fd_list | a GUnixFDList or `NULL`. | [nullable]
out_fd_list | return location for a GUnixFDList or `NULL`. | [out][optional]
cancellable | a GCancellable or `NULL`. | [nullable]
error | return location for error or `NULL` |

#### Returns

`NULL` if `error` is set. Otherwise a GVariant tuple with return values. Free with `g_variant_unref()`.

Since: 2.30

### g_dbus_connection_emit_signal ()

    gboolean
    g_dbus_connection_emit_signal (GDBusConnection *connection,
                                   const gchar *destination_bus_name,
                                   const gchar *object_path,
                                   const gchar *interface_name,
                                   const gchar *signal_name,
                                   GVariant *parameters,
                                   GError **error);

Emits a signal.

If the parameters GVariant is floating, it is consumed.

This can only fail if `parameters` is not compatible with the D-Bus protocol.

#### Parameters

connection | a GDBusConnection |
destination_bus_name | the unique bus name for the destination for the signal or `NULL` to emit to all listeners. | [nullable]
object_path | path of remote object |
interface_name | D-Bus interface to emit a signal on |
signal_name | the name of the signal to emit |
parameters | a GVariant tuple with parameters for the signal or `NULL` if not passing parameters. | [nullable]
error | Return location for error or `NULL` |

#### Returns

`TRUE` unless `error` is set

Since: 2.26

### GDBusSignalCallback ()

    void
    (*GDBusSignalCallback) (GDBusConnection *connection,
                            const gchar *sender_name,
                            const gchar *object_path,
                            const gchar *interface_name,
                            const gchar *signal_name,
                            GVariant *parameters,
                            gpointer user_data);

Signature for callback function used in `g_dbus_connection_signal_subscribe()`.

#### Parameters

connection | A GDBusConnection. |
sender_name | The unique bus name of the sender of the signal. |
object_path | The object path that the signal was emitted on. |
interface_name | The name of the interface. |
signal_name | The name of the signal. |
parameters | A GVariant tuple with parameters for the signal. |
user_data | User data passed when subscribing to the signal. |

Since: 2.26

### g_dbus_connection_signal_subscribe ()

    guint
    g_dbus_connection_signal_subscribe (GDBusConnection *connection,
                                        const gchar *sender,
                                        const gchar *interface_name,
                                        const gchar *member,
                                        const gchar *object_path,
                                        const gchar *arg0,
                                        GDBusSignalFlags flags,
                                        GDBusSignalCallback callback,
                                        gpointer user_data,
                                        GDestroyNotify user_data_free_func);

Subscribes to signals on `connection` and invokes `callback` with a whenever the signal is received. Note that `callback` will be invoked in the thread-default main context of the thread you are calling this method from.

If `connection` is not a message bus connection, `sender` must be `NULL`.

If `sender` is a well-known name note that `callback` is invoked with the unique name for the owner of `sender` , not the well-known name as one would expect. This is because the message bus rewrites the name. As such, to avoid certain race conditions, users should be tracking the name owner of the well-known name and use that when processing the received signal.

If one of `G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE` or `G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH` are given, `arg0` is interpreted as part of a namespace or path. The first argument of a signal is matched against that part as specified by D-Bus.

If `user_data_free_func` is non-`NULL`, it will be called (in the thread-default main context of the thread you are calling this method from) at some point after `user_data` is no longer needed. (It is not guaranteed to be called synchronously when the signal is unsubscribed from, and may be called after `connection` has been destroyed.)

#### Parameters

connection | a GDBusConnection |
sender | sender name to match on (unique or well-known name) or `NULL` to listen from all senders. | [nullable]
interface_name | D-Bus interface name to match on or `NULL` to match on all interfaces. | [nullable]
member | D-Bus signal name to match on or `NULL` to match on all signals. | [nullable]
object_path | object path to match on or `NULL` to match on all object paths. | [nullable]
arg0 | contents of first string argument to match on or `NULL` to match on all kinds of arguments. | [nullable]
flags | GDBusSignalFlags describing how arg0 is used in subscribing to the signal |
callback | callback to invoke when there is a signal matching the requested data |
user_data | user data to pass to `callback` |
user_data_free_func | function to free `user_data` with when subscription is removed or `NULL`. | [nullable]

#### Returns

a subscription identifier that can be used with `g_dbus_connection_signal_unsubscribe()`

Since: 2.26

### g_dbus_connection_signal_unsubscribe ()

    void
    g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
                                          guint subscription_id);

Unsubscribes from signals.

#### Parameters

connection | a GDBusConnection |
subscription_id | a subscription id obtained from `g_dbus_connection_signal_subscribe()` |

Since: 2.26

### g_dbus_connection_send_message ()

    gboolean
    g_dbus_connection_send_message (GDBusConnection *connection,
                                    GDBusMessage *message,
                                    GDBusSendMessageFlags flags,
                                    volatile guint32 *out_serial,
                                    GError **error);

Asynchronously sends `message` to the peer represented by `connection` .

Unless `flags` contain the `G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL` flag, the serial number will be assigned by `connection` and set on `message` via `g_dbus_message_set_serial()`. If `out_serial` is not `NULL`, then the serial number used will be written to this location prior to submitting the message to the underlying transport.

If `connection` is closed then the operation will fail with `G_IO_ERROR_CLOSED`. If `message` is not well-formed, the operation fails with `G_IO_ERROR_INVALID_ARGUMENT`.

See this server and client for an example of how to use this low-level API to send and receive UNIX file descriptors.

Note that `message` must be unlocked, unless `flags` contain the `G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL` flag.

#### Parameters

connection | a GDBusConnection |
message | a GDBusMessage |
flags | flags affecting how the message is sent |
out_serial | return location for serial number assigned to `message` when sending it or `NULL`. | [out][optional]
error | Return location for error or `NULL` |

#### Returns

`TRUE` if the message was well-formed and queued for transmission, `FALSE` if `error` is set

Since: 2.26

### g_dbus_connection_send_message_with_reply ()

    void
    g_dbus_connection_send_message_with_reply
                                   (GDBusConnection *connection,
                                    GDBusMessage *message,
                                    GDBusSendMessageFlags flags,
                                    gint timeout_msec,
                                    volatile guint32 *out_serial,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Asynchronously sends `message` to the peer represented by `connection` .

Unless `flags` contain the `G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL` flag, the serial number will be assigned by `connection` and set on `message` via `g_dbus_message_set_serial()`. If `out_serial` is not `NULL`, then the serial number used will be written to this location prior to submitting the message to the underlying transport.

If `connection` is closed then the operation will fail with `G_IO_ERROR_CLOSED`. If `cancellable` is canceled, the operation will fail with `G_IO_ERROR_CANCELLED`. If `message` is not well-formed, the operation fails with `G_IO_ERROR_INVALID_ARGUMENT`.

This is an asynchronous method. When the operation is finished, `callback` will be invoked in the thread-default main context of the thread you are calling this method from. You can then call `g_dbus_connection_send_message_with_reply_finish()` to get the result of the operation. See `g_dbus_connection_send_message_with_reply_sync()` for the synchronous version.

Note that `message` must be unlocked, unless `flags` contain the `G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL` flag.

See this server and client for an example of how to use this low-level API to send and receive UNIX file descriptors.

#### Parameters

connection | a GDBusConnection |
message | a GDBusMessage |
flags | flags affecting how the message is sent |
timeout_msec | the timeout in milliseconds, -1 to use the default timeout or `G_MAXINT` for no timeout |
out_serial | return location for serial number assigned to `message` when sending it or `NULL`. | [out][optional]
cancellable | a GCancellable or `NULL`. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied or `NULL` if you don't care about the result. | [nullable]
user_data | The data to pass to `callback` |

Since: 2.26

### g_dbus_connection_send_message_with_reply_finish ()

    GDBusMessage *
    g_dbus_connection_send_message_with_reply_finish
                                   (GDBusConnection *connection,
                                    GAsyncResult *res,
                                    GError **error);

Finishes an operation started with `g_dbus_connection_send_message_with_reply()`.

Note that `error` is only set if a local in-process error occurred. That is to say that the returned GDBusMessage object may be of type `G_DBUS_MESSAGE_TYPE_ERROR`. Use `g_dbus_message_to_gerror()` to transcode this to a GError.

See this server and client for an example of how to use this low-level API to send and receive UNIX file descriptors.

#### Parameters

connection | a GDBusConnection |
res | a GAsyncResult obtained from the GAsyncReadyCallback passed to `g_dbus_connection_send_message_with_reply()` |
error | teturn location for error or `NULL` |

#### Returns

a locked GDBusMessage or `NULL` if `error` is set.

[transfer full]

Since: 2.26

### g_dbus_connection_send_message_with_reply_sync ()

    GDBusMessage *
    g_dbus_connection_send_message_with_reply_sync
                                   (GDBusConnection *connection,
                                    GDBusMessage *message,
                                    GDBusSendMessageFlags flags,
                                    gint timeout_msec,
                                    volatile guint32 *out_serial,
                                    GCancellable *cancellable,
                                    GError **error);

Synchronously sends `message` to the peer represented by `connection` and blocks the calling thread until a reply is received or the timeout is reached. See `g_dbus_connection_send_message_with_reply()` for the asynchronous version of this method.

Unless `flags` contain the `G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL` flag, the serial number will be assigned by `connection` and set on `message` via `g_dbus_message_set_serial()`. If `out_serial` is not `NULL`, then the serial number used will be written to this location prior to submitting the message to the underlying transport.

If `connection` is closed then the operation will fail with `G_IO_ERROR_CLOSED`. If `cancellable` is canceled, the operation will fail with `G_IO_ERROR_CANCELLED`. If `message` is not well-formed, the operation fails with `G_IO_ERROR_INVALID_ARGUMENT`.

Note that `error` is only set if a local in-process error occurred. That is to say that the returned GDBusMessage object may be of type `G_DBUS_MESSAGE_TYPE_ERROR`. Use `g_dbus_message_to_gerror()` to transcode this to a GError.

See this server and client for an example of how to use this low-level API to send and receive UNIX file descriptors.

Note that `message` must be unlocked, unless `flags` contain the `G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL` flag.

#### Parameters

connection | a GDBusConnection |
message | a GDBusMessage |
flags | flags affecting how the message is sent. |
timeout_msec | the timeout in milliseconds, -1 to use the default timeout or `G_MAXINT` for no timeout |
out_serial | return location for serial number assigned to `message` when sending it or `NULL`. | [out][optional]
cancellable | a GCancellable or `NULL`. | [nullable]
error | return location for error or `NULL` |

#### Returns

a locked GDBusMessage that is the reply to `message` or `NULL` if `error` is set.

[transfer full]

Since: 2.26

### GDBusMessageFilterFunction ()

    GDBusMessage *
    (*GDBusMessageFilterFunction) (GDBusConnection *connection,
                                   GDBusMessage *message,
                                   gboolean incoming,
                                   gpointer user_data);

Signature for function used in `g_dbus_connection_add_filter()`.

A filter function is passed a GDBusMessage and expected to return a GDBusMessage too. Passive filter functions that don't modify the message can simply return the `message` object:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    static GDBusMessage *
    passive_filter (GDBusConnection *connection
                    GDBusMessage    *message,
                    gboolean         incoming,
                    gpointer         user_data)
    {
      /<!-- -->* inspect @message *<!-- -->/
      return message;
    }

Filter functions that wants to drop a message can simply return `NULL`:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    static GDBusMessage *
    drop_filter (GDBusConnection *connection
                 GDBusMessage    *message,
                 gboolean         incoming,
                 gpointer         user_data)
    {
      if (should_drop_message)
        {
          g_object_unref (message);
          message = NULL;
        }
      return message;
    }

Finally, a filter function may modify a message by copying it:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    static GDBusMessage *
    modifying_filter (GDBusConnection *connection
                      GDBusMessage    *message,
                      gboolean         incoming,
                      gpointer         user_data)
    {
      GDBusMessage *copy;
      GError *error;

      error = NULL;
      copy = g_dbus_message_copy (message, &error);
      /<!-- -->* handle @error being is set *<!-- -->/
      g_object_unref (message);

      /<!-- -->* modify @copy *<!-- -->/

      return copy;
    }

If the returned GDBusMessage is different from `message` and cannot be sent on `connection` (it could use features, such as file descriptors, not compatible with `connection` ), then a warning is logged to standard error. Applications can check this ahead of time using `g_dbus_message_to_blob()` passing a GDBusCapabilityFlags value obtained from `connection` .

#### Parameters

connection | A GDBusConnection. | [transfer none]
message | A locked GDBusMessage that the filter function takes ownership of. | [transfer full]
incoming | `TRUE` if it is a message received from the other peer, `FALSE` if it is a message to be sent to the other peer. |
user_data | User data passed when adding the filter. |

#### Returns

A GDBusMessage that will be freed with `g_object_unref()` or `NULL` to drop the message. Passive filter functions can simply return the passed `message` object.

[transfer full][nullable]

Since: 2.26

### g_dbus_connection_add_filter ()

    guint
    g_dbus_connection_add_filter (GDBusConnection *connection,
                                  GDBusMessageFilterFunction filter_function,
                                  gpointer user_data,
                                  GDestroyNotify user_data_free_func);

Adds a message filter. Filters are handlers that are run on all incoming and outgoing messages, prior to standard dispatch. Filters are run in the order that they were added. The same handler can be added as a filter more than once, in which case it will be run more than once. Filters added during a filter callback won't be run on the message being processed. Filter functions are allowed to modify and even drop messages.

Note that filters are run in a dedicated message handling thread so they can't block and, generally, can't do anything but signal a worker thread. Also note that filters are rarely needed - use API such as `g_dbus_connection_send_message_with_reply()`, `g_dbus_connection_signal_subscribe()` or `g_dbus_connection_call()` instead.

If a filter consumes an incoming message the message is not dispatched anywhere else - not even the standard dispatch machinery (that API such as `g_dbus_connection_signal_subscribe()` and `g_dbus_connection_send_message_with_reply()` relies on) will see the message. Similary, if a filter consumes an outgoing message, the message will not be sent to the other peer.

If `user_data_free_func` is non-`NULL`, it will be called (in the thread-default main context of the thread you are calling this method from) at some point after `user_data` is no longer needed. (It is not guaranteed to be called synchronously when the filter is removed, and may be called after `connection` has been destroyed.)

#### Parameters

connection | a GDBusConnection |
filter_function | a filter function |
user_data | user data to pass to `filter_function` |
user_data_free_func | function to free `user_data` with when filter is removed or `NULL` |

#### Returns

a filter identifier that can be used with `g_dbus_connection_remove_filter()`

Since: 2.26

### g_dbus_connection_remove_filter ()

    void
    g_dbus_connection_remove_filter (GDBusConnection *connection,
                                     guint filter_id);

Removes a filter.

Note that since filters run in a different thread, there is a race condition where it is possible that the filter will be running even after calling `g_dbus_connection_remove_filter()`, so you cannot just free data that the filter might be using. Instead, you should pass a GDestroyNotify to `g_dbus_connection_add_filter()`, which will be called when it is guaranteed that the data is no longer needed.

#### Parameters

connection | a GDBusConnection |
filter_id | an identifier obtained from `g_dbus_connection_add_filter()` |

Since: 2.26

### GDBusInterfaceMethodCallFunc ()

    void
    (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
                                     const gchar *sender,
                                     const gchar *object_path,
                                     const gchar *interface_name,
                                     const gchar *method_name,
                                     GVariant *parameters,
                                     GDBusMethodInvocation *invocation,
                                     gpointer user_data);

The type of the `method_call` function in GDBusInterfaceVTable.

#### Parameters

connection | A GDBusConnection. |
sender | The unique bus name of the remote caller. |
object_path | The object path that the method was invoked on. |
interface_name | The D-Bus interface name the method was invoked on. |
method_name | The name of the method that was invoked. |
parameters | A GVariant tuple with parameters. |
invocation | A GDBusMethodInvocation object that must be used to return a value or error. | [transfer full]
user_data | The `user_data` gpointer passed to `g_dbus_connection_register_object()`. |

Since: 2.26

### GDBusInterfaceGetPropertyFunc ()

    GVariant *
    (*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection,
                                      const gchar *sender,
                                      const gchar *object_path,
                                      const gchar *interface_name,
                                      const gchar *property_name,
                                      GError **error,
                                      gpointer user_data);

The type of the `get_property` function in GDBusInterfaceVTable.

#### Parameters

connection | A GDBusConnection. |
sender | The unique bus name of the remote caller. |
object_path | The object path that the method was invoked on. |
interface_name | The D-Bus interface name for the property. |
property_name | The name of the property to get the value of. |
error | Return location for error. |
user_data | The `user_data` gpointer passed to `g_dbus_connection_register_object()`. |

#### Returns

A GVariant with the value for `property_name` or `NULL` if `error` is set. If the returned GVariant is floating, it is consumed - otherwise its reference count is decreased by one.

Since: 2.26

### GDBusInterfaceSetPropertyFunc ()

    gboolean
    (*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection,
                                      const gchar *sender,
                                      const gchar *object_path,
                                      const gchar *interface_name,
                                      const gchar *property_name,
                                      GVariant *value,
                                      GError **error,
                                      gpointer user_data);

The type of the `set_property` function in GDBusInterfaceVTable.

#### Parameters

connection | A GDBusConnection. |
sender | The unique bus name of the remote caller. |
object_path | The object path that the method was invoked on. |
interface_name | The D-Bus interface name for the property. |
property_name | The name of the property to get the value of. |
value | The value to set the property to. |
error | Return location for error. |
user_data | The `user_data` gpointer passed to `g_dbus_connection_register_object()`. |

#### Returns

`TRUE` if the property was set to `value` , `FALSE` if `error` is set.

Since: 2.26

### g_dbus_connection_register_object ()

    guint
    g_dbus_connection_register_object (GDBusConnection *connection,
                                       const gchar *object_path,
                                       GDBusInterfaceInfo *interface_info,
                                       const GDBusInterfaceVTable *vtable,
                                       gpointer user_data,
                                       GDestroyNotify user_data_free_func,
                                       GError **error);

Registers callbacks for exported objects at `object_path` with the D-Bus interface that is described in `interface_info` .

Calls to functions in `vtable` (and `user_data_free_func` ) will happen in the thread-default main context of the thread you are calling this method from.

Note that all GVariant values passed to functions in `vtable` will match the signature given in `interface_info` - if a remote caller passes incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs` is returned to the remote caller.

Additionally, if the remote caller attempts to invoke methods or access properties not mentioned in `interface_info` the `org.freedesktop.DBus.Error.UnknownMethod` resp. `org.freedesktop.DBus.Error.InvalidArgs` errors are returned to the caller.

It is considered a programming error if the GDBusInterfaceGetPropertyFunc function in `vtable` returns a GVariant of incorrect type.

If an existing callback is already registered at `object_path` and `interface_name` , then `error` is set to G_IO_ERROR_EXISTS.

GDBus automatically implements the standard D-Bus interfaces org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable and org.freedesktop.Peer, so you don't have to implement those for the objects you export. You can implement org.freedesktop.DBus.Properties yourself, e.g. to handle getting and setting of properties asynchronously.

Note that the reference count on `interface_info` will be incremented by 1 (unless allocated statically, e.g. if the reference count is -1, see `g_dbus_interface_info_ref()`) for as long as the object is exported. Also note that `vtable` will be copied.

See this server for an example of how to use this method.

#### Parameters

connection | a GDBusConnection |
object_path | the object path to register at |
interface_info | introspection data for the interface |
vtable | a GDBusInterfaceVTable to call into or `NULL`. | [nullable]
user_data | data to pass to functions in `vtable` . | [nullable]
user_data_free_func | function to call when the object path is unregistered |
error | return location for error or `NULL` |

#### Returns

0 if `error` is set, otherwise a registration id (never 0) that can be used with `g_dbus_connection_unregister_object()`

Since: 2.26

### g_dbus_connection_unregister_object ()

    gboolean
    g_dbus_connection_unregister_object (GDBusConnection *connection,
                                         guint registration_id);

Unregisters an object.

#### Parameters

connection | a GDBusConnection |
registration_id | a registration id obtained from `g_dbus_connection_register_object()` |

#### Returns

`TRUE` if the object was unregistered, `FALSE` otherwise

Since: 2.26

### g_dbus_connection_register_object_with_closures ()

    guint
    g_dbus_connection_register_object_with_closures
                                   (GDBusConnection *connection,
                                    const gchar *object_path,
                                    GDBusInterfaceInfo *interface_info,
                                    GClosure *method_call_closure,
                                    GClosure *get_property_closure,
                                    GClosure *set_property_closure,
                                    GError **error);

Version of `g_dbus_connection_register_object()` using closures instead of a GDBusInterfaceVTable for easier binding in other languages.

[rename-to g_dbus_connection_register_object]

#### Parameters

connection | A GDBusConnection. |
object_path | The object path to register at. |
interface_info | Introspection data for the interface. |
method_call_closure | GClosure for handling incoming method calls. | [nullable]
get_property_closure | GClosure for getting a property. | [nullable]
set_property_closure | GClosure for setting a property. | [nullable]
error | Return location for error or `NULL`. |

#### Returns

0 if `error` is set, otherwise a registration id (never 0) that can be used with `g_dbus_connection_unregister_object()` .

Since: 2.46

### GDBusSubtreeEnumerateFunc ()

    gchar **
    (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
                                  const gchar *sender,
                                  const gchar *object_path,
                                  gpointer user_data);

The type of the `enumerate` function in GDBusSubtreeVTable.

This function is called when generating introspection data and also when preparing to dispatch incoming messages in the event that the `G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES` flag is not specified (ie: to verify that the object path is valid).

Hierarchies are not supported; the items that you return should not contain the '/' character.

The return value will be freed with `g_strfreev()`.

#### Parameters

connection | A GDBusConnection. |
sender | The unique bus name of the remote caller. |
object_path | The object path that was registered with `g_dbus_connection_register_subtree()`. |
user_data | The `user_data` gpointer passed to `g_dbus_connection_register_subtree()`. |

#### Returns

A newly allocated array of strings for node names that are children of `object_path` .

Since: 2.26

### GDBusSubtreeIntrospectFunc ()

    GDBusInterfaceInfo **
    (*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
                                   const gchar *sender,
                                   const gchar *object_path,
                                   const gchar *node,
                                   gpointer user_data);

The type of the `introspect` function in GDBusSubtreeVTable.

Subtrees are flat. `node` , if non-`NULL`, is always exactly one segment of the object path (ie: it never contains a slash).

This function should return `NULL` to indicate that there is no object at this node.

If this function returns non-`NULL`, the return value is expected to be a `NULL`-terminated array of pointers to GDBusInterfaceInfo structures describing the interfaces implemented by `node` . This array will have `g_dbus_interface_info_unref()` called on each item before being freed with `g_free()`.

The difference between returning `NULL` and an array containing zero items is that the standard DBus interfaces will returned to the remote introspector in the empty array case, but not in the `NULL` case.

#### Parameters

connection | A GDBusConnection. |
sender | The unique bus name of the remote caller. |
object_path | The object path that was registered with `g_dbus_connection_register_subtree()`. |
node | A node that is a child of `object_path` (relative to `object_path` ) or `NULL` for the root of the subtree. |
user_data | The `user_data` gpointer passed to `g_dbus_connection_register_subtree()`. |

#### Returns

A `NULL`-terminated array of pointers to GDBusInterfaceInfo, or `NULL`.

Since: 2.26

### GDBusSubtreeDispatchFunc ()

    const GDBusInterfaceVTable *
    (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
                                 const gchar *sender,
                                 const gchar *object_path,
                                 const gchar *interface_name,
                                 const gchar *node,
                                 gpointer *out_user_data,
                                 gpointer user_data);

The type of the `dispatch` function in GDBusSubtreeVTable.

Subtrees are flat. `node` , if non-`NULL`, is always exactly one segment of the object path (ie: it never contains a slash).

#### Parameters

connection | A GDBusConnection. |
sender | The unique bus name of the remote caller. |
object_path | The object path that was registered with `g_dbus_connection_register_subtree()`. |
interface_name | The D-Bus interface name that the method call or property access is for. |
node | A node that is a child of `object_path` (relative to `object_path` ) or `NULL` for the root of the subtree. |
out_user_data | Return location for user data to pass to functions in the returned GDBusInterfaceVTable (never `NULL`). | [nullable][not optional]
user_data | The `user_data` gpointer passed to `g_dbus_connection_register_subtree()`. |

#### Returns

A GDBusInterfaceVTable or `NULL` if you don't want to handle the methods.

Since: 2.26

### g_dbus_connection_register_subtree ()

    guint
    g_dbus_connection_register_subtree (GDBusConnection *connection,
                                        const gchar *object_path,
                                        const GDBusSubtreeVTable *vtable,
                                        GDBusSubtreeFlags flags,
                                        gpointer user_data,
                                        GDestroyNotify user_data_free_func,
                                        GError **error);

Registers a whole subtree of dynamic objects.

The `enumerate` and `introspection` functions in `vtable` are used to convey, to remote callers, what nodes exist in the subtree rooted by `object_path` .

When handling remote calls into any node in the subtree, first the `enumerate` function is used to check if the node exists. If the node exists or the G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set the `introspection` function is used to check if the node supports the requested method. If so, the `dispatch` function is used to determine where to dispatch the call. The collected GDBusInterfaceVTable and gpointer will be used to call into the interface vtable for processing the request.

All calls into user-provided code will be invoked in the thread-default main context of the thread you are calling this method from.

If an existing subtree is already registered at `object_path` or then `error` is set to G_IO_ERROR_EXISTS.

Note that it is valid to register regular objects (using `g_dbus_connection_register_object()`) in a subtree registered with `g_dbus_connection_register_subtree()` - if so, the subtree handler is tried as the last resort. One way to think about a subtree handler is to consider it a fallback handler for object paths not registered via `g_dbus_connection_register_object()` or other bindings.

Note that `vtable` will be copied so you cannot change it after registration.

See this server for an example of how to use this method.

#### Parameters

connection | a GDBusConnection |
object_path | the object path to register the subtree at |
vtable | a GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree |
flags | flags used to fine tune the behavior of the subtree |
user_data | data to pass to functions in `vtable` |
user_data_free_func | function to call when the subtree is unregistered |
error | return location for error or `NULL` |

#### Returns

0 if `error` is set, otherwise a subtree registration id (never 0) that can be used with `g_dbus_connection_unregister_subtree()` .

Since: 2.26

### g_dbus_connection_unregister_subtree ()

    gboolean
    g_dbus_connection_unregister_subtree (GDBusConnection *connection,
                                          guint registration_id);

Unregisters a subtree.

#### Parameters

connection | a GDBusConnection |
registration_id | a subtree registration id obtained from `g_dbus_connection_register_subtree()` |

#### Returns

`TRUE` if the subtree was unregistered, `FALSE` otherwise

Since: 2.26

## Types and Values

### enum GBusType

An enumeration for well-known message buses.

#### Members

G_BUS_TYPE_STARTER | An alias for the message bus that activated the process, if any. |
G_BUS_TYPE_NONE | Not a message bus. |
G_BUS_TYPE_SYSTEM | The system-wide message bus. |
G_BUS_TYPE_SESSION | The login session message bus. |

Since: 2.26

### GDBusConnection

    typedef struct _GDBusConnection GDBusConnection;

The GDBusConnection structure contains only private data and should only be accessed using the provided API.

Since: 2.26

### enum GDBusConnectionFlags

Flags used when creating a new GDBusConnection.

#### Members

G_DBUS_CONNECTION_FLAGS_NONE | No flags set. |
G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT | Perform authentication against server. |
G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER | Perform authentication against client. |
G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS | When authenticating as a server, allow the anonymous authentication method. |
G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION | Pass this flag if connecting to a peer that is a message bus. This means that the `Hello()` method will be invoked as part of the connection setup. |
G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING | If set, processing of D-Bus messages is delayed until `g_dbus_connection_start_message_processing()` is called. |

Since: 2.26

### enum GDBusCapabilityFlags

Capabilities negotiated with the remote peer.

#### Members

G_DBUS_CAPABILITY_FLAGS_NONE | No flags set. |
G_DBUS_CAPABILITY_FLAGS_UNIX_FD_PASSING | The connection supports exchanging UNIX file descriptors with the remote peer. |

Since: 2.26

### enum GDBusCallFlags

Flags used in `g_dbus_connection_call()` and similar APIs.

#### Members

G_DBUS_CALL_FLAGS_NONE | No flags set. |
G_DBUS_CALL_FLAGS_NO_AUTO_START | The bus must not launch an owner for the destination name in response to this method invocation. |
G_DBUS_CALL_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION | the caller is prepared to wait for interactive authorization. Since 2.46. |

Since: 2.26

### enum GDBusSignalFlags

Flags used when subscribing to signals via `g_dbus_connection_signal_subscribe()`.

#### Members

G_DBUS_SIGNAL_FLAGS_NONE | No flags set. |
G_DBUS_SIGNAL_FLAGS_NO_MATCH_RULE | Don't actually send the AddMatch D-Bus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually). |
G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE | Match first arguments that contain a bus or interface name with the given namespace. |
G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH | Match first arguments that contain an object path that is either equivalent to the given path, or one of the paths is a subpath of the other. |

Since: 2.26

### enum GDBusSendMessageFlags

Flags used when sending GDBusMessages on a GDBusConnection.

#### Members

G_DBUS_SEND_MESSAGE_FLAGS_NONE | No flags set. |
G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL | Do not automatically assign a serial number from the GDBusConnection object when sending a message. |

Since: 2.26

### GDBusInterfaceVTable

    typedef struct {
      GDBusInterfaceMethodCallFunc  method_call;
      GDBusInterfaceGetPropertyFunc get_property;
      GDBusInterfaceSetPropertyFunc set_property;
    } GDBusInterfaceVTable;

Virtual table for handling properties and method calls for a D-Bus interface.

Since 2.38, if you want to handle getting/setting D-Bus properties asynchronously, give `NULL` as your `get_property()` or `set_property()` function. The D-Bus call will be directed to your `method_call` function, with the provided `interface_name` set to "org.freedesktop.DBus.Properties".

Ownership of the GDBusMethodInvocation object passed to the `method_call()` function is transferred to your handler; you must call one of the methods of GDBusMethodInvocation to return a reply (possibly empty), or an error. These functions also take ownership of the passed-in invocation object, so unless the invocation object has otherwise been referenced, it will be then be freed. Calling one of these functions may be done within your `method_call()` implementation but it also can be done at a later point to handle the method asynchronously.

The usual checks on the validity of the calls is performed. For `Get` calls, an error is automatically returned if the property does not exist or the permissions do not allow access. The same checks are performed for `Set` calls, and the provided value is also checked for being the correct type.

For both `Get` and `Set` calls, the GDBusMethodInvocation passed to the `method_call` handler can be queried with `g_dbus_method_invocation_get_property_info()` to get a pointer to the GDBusPropertyInfo of the property.

If you have readable properties specified in your interface info, you must ensure that you either provide a non-`NULL` ``get_property()`` function or provide implementations of both the `Get` and `GetAll` methods on org.freedesktop.DBus.Properties interface in your `method_call` function. Note that the required return type of the `Get` call is `(v)`, not the type of the property. `GetAll` expects a return value of type `a{sv}`.

If you have writable properties specified in your interface info, you must ensure that you either provide a non-`NULL` ``set_property()`` function or provide an implementation of the `Set` call. If implementing the call, you must return the value of type `G_VARIANT_TYPE_UNIT`.

#### Members

GDBusInterfaceMethodCallFunc `method_call`; | Function for handling incoming method calls. |
GDBusInterfaceGetPropertyFunc `get_property`; | Function for getting a property. |
GDBusInterfaceSetPropertyFunc `set_property`; | Function for setting a property. |

Since: 2.26

### GDBusSubtreeVTable

    typedef struct {
      GDBusSubtreeEnumerateFunc  enumerate;
      GDBusSubtreeIntrospectFunc introspect;
      GDBusSubtreeDispatchFunc   dispatch;
    } GDBusSubtreeVTable;

Virtual table for handling subtrees registered with `g_dbus_connection_register_subtree()`.

#### Members

GDBusSubtreeEnumerateFunc `enumerate`; | Function for enumerating child nodes. |
GDBusSubtreeIntrospectFunc `introspect`; | Function for introspecting a child node. |
GDBusSubtreeDispatchFunc `dispatch`; | Function for dispatching a remote call on a child node. |

Since: 2.26

### enum GDBusSubtreeFlags

Flags passed to `g_dbus_connection_register_subtree()`.

#### Members

G_DBUS_SUBTREE_FLAGS_NONE | No flags set. |
G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES | Method calls to objects not in the enumerated range will still be dispatched. This is useful if you want to dynamically spawn objects in the subtree. |

Since: 2.26

## Property Details

### The `“address”` property

      “address”                  gchar *

A D-Bus address specifying potential endpoints that can be used when establishing the connection.

Flags: Write / Construct Only

Default value: NULL

Since: 2.26

### The `“authentication-observer”` property

      “authentication-observer”  GDBusAuthObserver *

A GDBusAuthObserver object to assist in the authentication process or `NULL`.

Flags: Write / Construct Only

Since: 2.26

### The `“capabilities”` property

      “capabilities”             GDBusCapabilityFlags

Flags from the GDBusCapabilityFlags enumeration representing connection features negotiated with the other peer.

Flags: Read

Since: 2.26

### The `“closed”` property

      “closed”                   gboolean

A boolean specifying whether the connection has been closed.

Flags: Read

Default value: FALSE

Since: 2.26

### The `“exit-on-close”` property

      “exit-on-close”            gboolean

A boolean specifying whether the process will be terminated (by calling `raise(SIGTERM)`) if the connection is closed by the remote peer.

Note that GDBusConnection objects returned by `g_bus_get_finish()` and `g_bus_get_sync()` will (usually) have this property set to `TRUE`.

Flags: Read / Write

Default value: FALSE

Since: 2.26

### The `“flags”` property

      “flags”                    GDBusConnectionFlags

Flags from the GDBusConnectionFlags enumeration.

Flags: Write / Construct Only

Since: 2.26

### The `“guid”` property

      “guid”                     gchar *

The GUID of the peer performing the role of server when authenticating.

If you are constructing a GDBusConnection and pass `G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER` in the “flags” property then you MUST also set this property to a valid guid.

If you are constructing a GDBusConnection and pass `G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT` in the “flags” property you will be able to read the GUID of the other peer here after the connection has been successfully initialized.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.26

### The `“stream”` property

      “stream”                   GIOStream *

The underlying GIOStream used for I/O.

If this is passed on construction and is a GSocketConnection, then the corresponding GSocket will be put into non-blocking mode.

While the GDBusConnection is active, it will interact with this stream from a worker thread, so it is not safe to interact with the stream directly.

Flags: Read / Write / Construct Only

Since: 2.26

### The `“unique-name”` property

      “unique-name”              gchar *

The unique name as assigned by the message bus or `NULL` if the connection is not open or not a message bus connection.

Flags: Read

Default value: NULL

Since: 2.26

## Signal Details

### The `“closed”` signal

    void
    user_function (GDBusConnection *connection,
                   gboolean         remote_peer_vanished,
                   GError          *error,
                   gpointer         user_data)

Emitted when the connection is closed.

The cause of this event can be

- If `g_dbus_connection_close()` is called. In this case `remote_peer_vanished` is set to `FALSE` and `error` is `NULL`.

- If the remote peer closes the connection. In this case `remote_peer_vanished` is set to `TRUE` and `error` is set.

- If the remote peer sends invalid or malformed data. In this case `remote_peer_vanished` is set to `FALSE` and `error` is set.

Upon receiving this signal, you should give up your reference to `connection` . You are guaranteed that this signal is emitted only once.

#### Parameters

connection | the GDBusConnection emitting the signal |
remote_peer_vanished | `TRUE` if `connection` is closed because the remote peer closed its end of the connection |
error | a GError with more details about the event or `NULL`. | [nullable]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.26