The DBusConnection 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 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
g_bus_own_name, g_bus_watch_name or
create_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,
DBusConnection's methods may be called from any thread. This is so that @get and
get_sync can safely return the same DBusConnection when
called from any thread.
Most of the ways to obtain a DBusConnection automatically initialize it (i.e. connect to D-Bus): for instance,
@new and @get, and the
synchronous versions of those methods, give you an initialized connection. Language bindings for GIO should use
@new or
new_async, which also initialize the connection.
If you construct an uninitialized DBusConnection, such as via @new, you
must initialize it via init or
init_async before using its methods or properties. Calling methods
or accessing properties on a DBusConnection that has not completed initialization successfully is considered
to be invalid, and leads to undefined behaviour. In particular, if initialization fails with a Error, the only
valid thing you can do with that DBusConnection is to free it with unref.
An example D-Bus server # {gdbuss-server}
Here is an example for a D-Bus server:
gdbus-example-server.c
An example for exporting a subtree # {gdbuss-subtree-server}
Here is an example for exporting a subtree:
gdbus-example-subtree.c
An example for file descriptor passing # {gdbuss-unix-fd-client}
Here is an example for passing UNIX file descriptors:
gdbus-unix-fd-client.c
An example for exporting a GObject # {gdbuss-export}
Here is an example for exporting a Object:
gdbus-example-export.c
Example: Using extra D-Bus hooks with a GLib.Application::
public class MyApplication : Application {
private MyApplication () {
Object (application_id: "org.example.application", flags: 0);
set_inactivity_timeout (10000);
}
public override void activate () {
// NOTE: when doing a longer-lasting action here that returns
// to the mainloop, you should use g_application_hold() and
// g_application_release() to keep the application alive until
// the action is completed.
print ("Activated\n");
}
public override bool dbus_register (DBusConnection connection, string object_path) throws Error {
// We must chain up to the parent class:
base.dbus_register (connection, object_path);
// Now we can do our own stuff here. For example, we could export some D-Bus objects
return true;
}
public override void dbus_unregister (DBusConnection connection, string object_path) {
// Do our own stuff here, e.g. unexport any D-Bus objects we exported in the dbus_register
// hook above. Be sure to check that we actually did export them, since the hook
// above might have returned early due to the parent class' hook returning false!
base.dbus_unregister (connection, object_path);
}
public static int main (string[] args) {
MyApplication app = new MyApplication ();
int status = app.run (args);
return status;
}
}
valac --pkg gio-2.0 GLib.Application.3.vala
- 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 message 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 with a 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)
- 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.