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 a [class@Gio.IOStream].
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 [
func@Gio.bus_own_name], [func@Gio.bus_watch_name] or [func@Gio.DBusProxy.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 [func@Gio.bus_get] and [func@Gio.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, [
func@Gio.DBusConnection.new] and [func@Gio.bus_get], and the synchronous versions of those methods, give you an initialized connection.
Language bindings for GIO should use [func@Gio.Initable.new] or [func@Gio.AsyncInitable.new_async], which also initialize the connection.
If you construct an uninitialized `GDBusConnection`, such as via [ctor@GObject.Object.new], you must initialize it via [
method@Gio.Initable.init] or [method@Gio.AsyncInitable.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 [method@GObject.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 Object:
gdbus-example-export.c
- public uint add_filter (owned DBusMessageFilterFunction filter_function)
Adds a message filter.
- public async Variant call (string? bus_name, string object_path, string interface_name, string method_name, Variant? parameters, VariantType? reply_type, DBusCallFlags flags, int timeout_msec, Cancellable? cancellable = null) throws Error
Asynchronously invokes the method_name method on the
interface_name D-Bus interface on the remote object at object_path owned by bus_name.
- public Variant call_sync (string? bus_name, string object_path, string interface_name, string method_name, Variant? parameters, VariantType? reply_type, DBusCallFlags flags, int timeout_msec, Cancellable? cancellable = null) throws 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.
- public async Variant call_with_unix_fd_list (string? bus_name, string object_path, string interface_name, string method_name, Variant? parameters, VariantType? reply_type, DBusCallFlags flags, int timeout_msec, UnixFDList? fd_list = null, Cancellable? cancellable = null, out UnixFDList? out_fd_list = null) throws Error
- public Variant call_with_unix_fd_list_sync (string? bus_name, string object_path, string interface_name, string method_name, Variant? parameters, VariantType? reply_type, DBusCallFlags flags, int timeout_msec, UnixFDList? fd_list = null, out UnixFDList? out_fd_list = null, Cancellable? cancellable = null) throws Error
- public async bool close (Cancellable? cancellable = null) throws Error
Closes this.
- public bool close_sync (Cancellable? cancellable = null) throws Error
Synchronously closes this.
- public bool emit_signal (string? destination_bus_name, string object_path, string interface_name, string signal_name, Variant? parameters) throws Error
Emits a signal.
- public uint export_action_group (string object_path, ActionGroup action_group) throws Error
Exports action_group on this
at object_path.
- public uint export_menu_model (string object_path, MenuModel menu) throws Error
Exports menu on this at
object_path.
- public async bool flush (Cancellable? cancellable = null) throws Error
Asynchronously flushes this, that
is, writes all queued outgoing messages to the transport and then flushes the transport (using
flush_async).
- public bool flush_sync (Cancellable? cancellable = null) throws Error
Synchronously flushes this.
- public DBusCapabilityFlags get_capabilities ()
Gets the capabilities negotiated with the remote peer
- public bool get_exit_on_close ()
Gets whether the process is terminated when
this is closed by the remote peer.
- public DBusConnectionFlags get_flags ()
Gets the flags used to construct this connection
- public unowned string get_guid ()
The GUID of the peer performing the role of server when
authenticating.
- public uint32 get_last_serial ()
Retrieves the last serial number assigned to a
DBusMessage on the current thread.
- public unowned Credentials? get_peer_credentials ()
Gets the credentials of the authenticated peer.
- public async T get_proxy<T> (string? name, string object_path, DBusProxyFlags flags = 0, Cancellable? cancellable = null) throws IOError
- public T get_proxy_sync<T> (string? name, string object_path, DBusProxyFlags flags = 0, Cancellable? cancellable = null) throws IOError
- public unowned IOStream get_stream ()
Gets the underlying stream used for IO.
- public unowned string? get_unique_name ()
Gets the unique name of this as
assigned by the message bus.
- public bool is_closed ()
Gets whether this is closed.
- public uint register_object<T> (string object_path, T object) throws IOError
Registers callbacks for exported objects at object_path
with the D-Bus interface that is described in interface_info.
- public uint register_object_with_closures (string object_path, DBusInterfaceInfo interface_info, Closure? method_call_closure, Closure? get_property_closure, Closure? set_property_closure) throws Error
- public uint register_subtree (string object_path, DBusSubtreeVTable vtable, DBusSubtreeFlags flags, void* user_data, DestroyNotify user_data_free_func) throws Error
Registers a whole subtree of dynamic objects.
- public void remove_filter (uint filter_id)
Removes a filter.
- public bool send_message (DBusMessage message, DBusSendMessageFlags flags, out uint32 out_serial) throws Error
Asynchronously sends message to the peer represented by
this.
- public async DBusMessage send_message_with_reply (DBusMessage message, DBusSendMessageFlags flags, int timeout_msec, uint32* out_serial = null, Cancellable? cancellable = null) throws IOError
Asynchronously sends message to the peer represented by
this.
- public DBusMessage send_message_with_reply_sync (DBusMessage message, DBusSendMessageFlags flags, int timeout_msec, out uint32 out_serial = null, Cancellable? cancellable = null) throws IOError
Synchronously sends message to the peer represented by
this and blocks the calling thread until a reply is received or the timeout is reached.
- public void set_exit_on_close (bool exit_on_close)
Sets whether the process should be terminated when
this is closed by the remote peer.
- public uint signal_subscribe (string? sender, string? interface_name, string? member, string? object_path, string? arg0, DBusSignalFlags flags, owned DBusSignalCallback callback)
Subscribes to signals on this and
invokes callback whenever the signal is received.
- public void signal_unsubscribe (uint subscription_id)
Unsubscribes from signals.
- public void start_message_processing ()
If this was created with
g_dbus_connection_flags_delay_message_processing, this method starts processing messages.
- public void unexport_action_group (uint export_id)
Reverses the effect of a previous call to [method@Gio.
- public void unexport_menu_model (uint export_id)
- public bool unregister_object (uint registration_id)
Unregisters an object.
- public bool unregister_subtree (uint registration_id)
Unregisters a subtree.
