gio.dbus_connection
Module for [DBusConnection] class
Types 3
classDBusConnection : gobject.object.ObjectWrap, gio.async_initable.AsyncInitable, gio.initable.Initable
The [gio.dbus_connection.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 [gio.iostream.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 [gio.dbus_proxy.DBusProxy.newForBus] APIs.
As an exception to the usual GLib rule that a particular object must not be used by two threads at the same time, [gio.dbus_connection.DBusConnection]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 [gio.dbus_connection.DBusConnection] when called from any thread.
Most of the ways to obtain a [gio.dbus_connection.DBusConnection] automatically initialize it (i.e. connect to D-Bus): for instance, [gio.dbus_connection.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 [gio.initable.Initable.new_] or [gio.async_initable.AsyncInitable.newAsync], which also initialize the connection.
If you construct an uninitialized [gio.dbus_connection.DBusConnection], such as via [gobject.object.ObjectWrap.new_], you must initialize it via [gio.initable.Initable.init_] or [gio.async_initable.AsyncInitable.initAsync] before using its methods or properties. Calling methods or accessing properties on a [gio.dbus_connection.DBusConnection] that has not completed initialization successfully is considered to be invalid, and leads to undefined behaviour. In particular, if initialization fails with a [glib.error.ErrorWrap], the only valid thing you can do with that [gio.dbus_connection.DBusConnection] is to free it with [gobject.object.ObjectWrap.unref].
An example D-Bus server
Here is an example for a D-Bus server:
gdbus-example-server.cAn example for exporting a subtree
Here is an example for exporting a subtree:
gdbus-example-subtree.cAn example for file descriptor passing
Here is an example for passing UNIX file descriptors:
gdbus-unix-fd-client.cAn example for exporting a GObject
Here is an example for exporting a #GObject:
gdbus-example-export.cMethods
DBusConnection self()Returns `this`, for use in `with` statements.DBusConnectionGidBuilder builder()Get builder for [gio.dbus_connection.DBusConnection] Returns: New builder objectgio.types.DBusCapabilityFlags capabilities() @propertyGet `capabilities` property. Returns: Flags from the #GDBusCapabilityFlags enumeration representing connection features negotiated with the other peer.bool closed() @propertyGet `closed` property. Returns: A boolean specifying whether the connection has been closed.bool exitOnClose() @propertyGet `exitOnClose` property. Returns: A boolean specifying whether the process will be terminated (by calling `raise(SIGTERM)`) if the connection is closed by the remote peer.void exitOnClose(bool propval) @propertySet `exitOnClose` property. Params: propval = A boolean specifying whether the process will be terminated (by calling `raise(SIGTERM)`) if the connection is closed by the remote peer.gio.types.DBusConnectionFlags flags() @propertyGet `flags` property. Returns: Flags from the #GDBusConnectionFlags enumeration.string guid() @propertyGet `guid` property. Returns: The GUID of the peer performing the role of server when authenticating.gio.iostream.IOStream stream() @propertyGet `stream` property. Returns: The underlying #GIOStream used for I/O.string uniqueName() @propertyGet `uniqueName` property. Returns: The unique name as assigned by the message bus or null if the connection is not open or not a message bus connection.gio.dbus_connection.DBusConnection newFinish(gio.async_result.AsyncResult res)Finishes an operation started with [gio.dbusconnection.DBusConnection.new].gio.dbus_connection.DBusConnection newForAddressFinish(gio.async_result.AsyncResult res)Finishes an operation started with [gio.dbus_connection.DBusConnection.newForAddress].gio.dbus_connection.DBusConnection newForAddressSync(string address, gio.types.DBusConnectionFlags flags, gio.dbus_auth_observer.DBusAuthObserver observer = null, gio.cancellable.Cancellable cancellable = null)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](https://dbus.freedesktop...gio.dbus_connection.DBusConnection newSync(gio.iostream.IOStream stream, string guid, gio.types.DBusConnectionFlags flags, gio.dbus_auth_observer.DBusAuthObserver observer = null, gio.cancellable.Cancellable cancellable = null)Synchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by stream.void new_(gio.iostream.IOStream stream, string guid, gio.types.DBusConnectionFlags flags, gio.dbus_auth_observer.DBusAuthObserver observer = null, gio.cancellable.Cancellable cancellable = null, gio.types.AsyncReadyCallback callback = null)Asynchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by stream.void newForAddress(string address, gio.types.DBusConnectionFlags flags, gio.dbus_auth_observer.DBusAuthObserver observer = null, gio.cancellable.Cancellable cancellable = null, gio.types.AsyncReadyCallback callback = null)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](https://dbus.freedeskto...uint addFilter(gio.types.DBusMessageFilterFunction filterFunction)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 ...void call(string busName, string objectPath, string interfaceName, string methodName, glib.variant.Variant parameters, glib.variant_type.VariantType replyType, gio.types.DBusCallFlags flags, int timeoutMsec, gio.cancellable.Cancellable cancellable = null, gio.types.AsyncReadyCallback callback = null)Asynchronously invokes the methodname method on the interfacename D-Bus interface on the remote object at objectpath owned by busname.glib.variant.Variant callFinish(gio.async_result.AsyncResult res)Finishes an operation started with [gio.dbus_connection.DBusConnection.call].glib.variant.Variant callSync(string busName, string objectPath, string interfaceName, string methodName, glib.variant.Variant parameters, glib.variant_type.VariantType replyType, gio.types.DBusCallFlags flags, int timeoutMsec, gio.cancellable.Cancellable cancellable = null)Synchronously invokes the methodname method on the interfacename D-Bus interface on the remote object at objectpath owned by busname.void callWithUnixFdList(string busName, string objectPath, string interfaceName, string methodName, glib.variant.Variant parameters, glib.variant_type.VariantType replyType, gio.types.DBusCallFlags flags, int timeoutMsec, gio.unix_fdlist.UnixFDList fdList = null, gio.cancellable.Cancellable cancellable = null, gio.types.AsyncReadyCallback callback = null)Like [gio.dbus_connection.DBusConnection.call] but also takes a #GUnixFDList object.glib.variant.Variant callWithUnixFdListFinish(out gio.unix_fdlist.UnixFDList outFdList, gio.async_result.AsyncResult res)Finishes an operation started with [gio.dbus_connection.DBusConnection.callWithUnixFdList].glib.variant.Variant callWithUnixFdListSync(string busName, string objectPath, string interfaceName, string methodName, glib.variant.Variant parameters, glib.variant_type.VariantType replyType, gio.types.DBusCallFlags flags, int timeoutMsec, gio.unix_fdlist.UnixFDList fdList, out gio.unix_fdlist.UnixFDList outFdList, gio.cancellable.Cancellable cancellable = null)Like [gio.dbusconnection.DBusConnection.callSync] but also takes and returns #GUnixFDList objects. See [gio.dbusconnection.DBusConnection.callWithUnixFdList] and [gio.dbus_connection.DBusConnection...void close(gio.cancellable.Cancellable cancellable = null, gio.types.AsyncReadyCallback callback = null)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 #GDBusConnection:exit-on-close).bool closeFinish(gio.async_result.AsyncResult res)Finishes an operation started with [gio.dbus_connection.DBusConnection.close].bool closeSync(gio.cancellable.Cancellable cancellable = null)Synchronously closes connection. The calling thread is blocked until this is done. See [gio.dbus_connection.DBusConnection.close] for the asynchronous version of this method and more details about ...bool emitSignal(string destinationBusName, string objectPath, string interfaceName, string signalName, glib.variant.Variant parameters = null)Emits a signal.uint exportActionGroup(string objectPath, gio.action_group.ActionGroup actionGroup)Exports actiongroup on connection at objectpath.uint exportMenuModel(string objectPath, gio.menu_model.MenuModel menu)Exports menu on connection at object_path.void flush(gio.cancellable.Cancellable cancellable = null, gio.types.AsyncReadyCallback callback = null)Asynchronously flushes connection, that is, writes all queued outgoing message to the transport and then flushes the transport (using [gio.output_stream.OutputStream.flushAsync]). This is useful in...bool flushFinish(gio.async_result.AsyncResult res)Finishes an operation started with [gio.dbus_connection.DBusConnection.flush].bool flushSync(gio.cancellable.Cancellable cancellable = null)Synchronously flushes connection. The calling thread is blocked until this is done. See [gio.dbus_connection.DBusConnection.flush] for the asynchronous version of this method and more details about...gio.types.DBusCapabilityFlags getCapabilities()Gets the capabilities negotiated with the remote peer Returns: zero or more flags from the #GDBusCapabilityFlags enumerationbool getExitOnClose()Gets whether the process is terminated when connection is closed by the remote peer. See #GDBusConnection:exit-on-close for more details. Returns: whether the process is terminated when connection ...gio.types.DBusConnectionFlags getFlags()Gets the flags used to construct this connection Returns: zero or more flags from the #GDBusConnectionFlags enumerationstring getGuid()The GUID of the peer performing the role of server when authenticating. See #GDBusConnection:guid for more details. Returns: The GUID. Do not free this string, it is owned by connection.uint getLastSerial()Retrieves the last serial number assigned to a #GDBusMessage on the current thread. This includes messages sent via both low-level API such as [gio.dbusconnection.DBusConnection.sendMessage] as wel...gio.credentials.Credentials getPeerCredentials()Gets the credentials of the authenticated peer. This will always return null unless connection acted as a server (e.g. [gio.types.DBusConnectionFlags.AuthenticationServer] was passed) when set up a...gio.iostream.IOStream getStream()Gets the underlying stream used for IO.string getUniqueName()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. Returns: the unique name or null if connection is n...bool isClosed()Gets whether connection is closed. Returns: true if the connection is closed, false otherwiseuint registerObject(string objectPath, gio.dbus_interface_info.DBusInterfaceInfo interfaceInfo, gobject.closure.Closure methodCallClosure = null, gobject.closure.Closure getPropertyClosure = null, gobject.closure.Closure setPropertyClosure = null)Version of [gio.dbus_connection.DBusConnection.registerObject] using closures instead of a #GDBusInterfaceVTable for easier binding in other languages.uint registerSubtree(string objectPath, gio.types.DBusSubtreeVTable vtable, gio.types.DBusSubtreeFlags flags, void * userData, glib.types.DestroyNotify userDataFreeFunc)Registers a whole subtree of dynamic objects.void removeFilter(uint filterId)Removes a filter.bool sendMessage(gio.dbus_message.DBusMessage message, gio.types.DBusSendMessageFlags flags, out uint outSerial)Asynchronously sends message to the peer represented by connection.void sendMessageWithReply(gio.dbus_message.DBusMessage message, gio.types.DBusSendMessageFlags flags, int timeoutMsec, out uint outSerial, gio.cancellable.Cancellable cancellable = null, gio.types.AsyncReadyCallback callback = null)Asynchronously sends message to the peer represented by connection.gio.dbus_message.DBusMessage sendMessageWithReplyFinish(gio.async_result.AsyncResult res)Finishes an operation started with [gio.dbus_connection.DBusConnection.sendMessageWithReply].gio.dbus_message.DBusMessage sendMessageWithReplySync(gio.dbus_message.DBusMessage message, gio.types.DBusSendMessageFlags flags, int timeoutMsec, out uint outSerial, gio.cancellable.Cancellable cancellable = null)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 [gio.dbus_connection.DBusConnection.sendMess...void setExitOnClose(bool exitOnClose)Sets whether the process should be terminated when connection is closed by the remote peer. See #GDBusConnection:exit-on-close for more details.uint signalSubscribe(string sender, string interfaceName, string member, string objectPath, string arg0, gio.types.DBusSignalFlags flags, gio.types.DBusSignalCallback callback)Subscribes to signals on connection and invokes callback whenever the signal is received. Note that callback will be invoked in the [thread-default main context][g-main-context-push-thread-default]...void signalUnsubscribe(uint subscriptionId)Unsubscribes from signals.void startMessageProcessing()If connection was created with [gio.types.DBusConnectionFlags.DelayMessageProcessing], this method starts processing messages. Does nothing on if connection wasn't created with this flag or if the ...void unexportActionGroup(uint exportId)Reverses the effect of a previous call to [gio.dbus_connection.DBusConnection.exportActionGroup].void unexportMenuModel(uint exportId)Reverses the effect of a previous call to [gio.dbus_connection.DBusConnection.exportMenuModel].bool unregisterObject(uint registrationId)Unregisters an object.bool unregisterSubtree(uint registrationId)Unregisters a subtree.gulong connectClosed(T)(T callback, Flag!"After" after = No.After) if (isCallable!T
&& is(ReturnType!T == void)
&& (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] == bool)))
&& (Parameters!T.length < 2 || (ParameterStorageClassTuple!T[1] == ParameterStorageClass.none && is(Parameters!T[1] == glib.error.ErrorWrap)))
&& (Parameters!T.length < 3 || (ParameterStorageClassTuple!T[2] == ParameterStorageClass.none && is(Parameters!T[2] : gio.dbus_connection.DBusConnection)))
&& Parameters!T.length < 4)Connect to `Closed` signal.classDBusConnectionGidBuilderImpl(T) : gobject.object.ObjectWrapGidBuilderImpl!T, gio.async_initable.AsyncInitableGidBuilderImpl!T, gio.initable.InitableGidBuilderImpl!T
Methods
T address(string propval)Set `address` property. Params: propval = A D-Bus address specifying potential endpoints that can be used when establishing the connection. Returns: Builder instance for fluent chainingT authenticationObserver(gio.dbus_auth_observer.DBusAuthObserver propval)Set `authenticationObserver` property. Params: propval = A #GDBusAuthObserver object to assist in the authentication process or null. Returns: Builder instance for fluent chainingT exitOnClose(bool propval)Set `exitOnClose` property. Params: propval = A boolean specifying whether the process will be terminated (by calling `raise(SIGTERM)`) if the connection is closed by the remote peer.T flags(gio.types.DBusConnectionFlags propval)Set `flags` property. Params: propval = Flags from the #GDBusConnectionFlags enumeration. Returns: Builder instance for fluent chainingT guid(string propval)Set `guid` property. Params: propval = The GUID of the peer performing the role of server when authenticating.T stream(gio.iostream.IOStream propval)Set `stream` property. Params: propval = The underlying #GIOStream used for I/O.Fluent builder for [gio.dbus_connection.DBusConnection]
Methods