Class DBusObjectManagerClient

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gio.DBusObjectManagerClient
All Implemented Interfaces:
AsyncInitable, DBusObjectManager, Initable, Proxy
@Generated("org.javagi.JavaGI") public class DBusObjectManagerClient extends GObject implements AsyncInitable, DBusObjectManager, Initable

GDBusObjectManagerClient is used to create, monitor and delete object proxies for remote objects exported by a DBusObjectManagerServer (or any code implementing the org.freedesktop.DBus.ObjectManager interface).

Once an instance of this type has been created, you can connect to the Gio.DBusObjectManager::object-added and Gio.DBusObjectManager::object-removed signals and inspect the DBusObjectProxy objects returned by DBusObjectManager.getObjects().

If the name for a GDBusObjectManagerClient is not owned by anyone at object construction time, the default behavior is to request the message bus to launch an owner for the name. This behavior can be disabled using the G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START flag. It’s also worth noting that this only works if the name of interest is activatable in the first place. E.g. in some cases it is not possible to launch an owner for the requested name. In this case, GDBusObjectManagerClient object construction still succeeds but there will be no object proxies (e.g. DBusObjectManager.getObjects() returns the empty list) and the Gio.DBusObjectManagerClient:name-owner property is NULL.

The owner of the requested name can come and go (for example consider a system service being restarted) – GDBusObjectManagerClient handles this case too; simply connect to the GObject.Object::notify signal to watch for changes on the Gio.DBusObjectManagerClient:name-owner property. When the name owner vanishes, the behavior is that Gio.DBusObjectManagerClient:name-owner is set to NULL (this includes emission of the GObject.Object::notify signal) and then Gio.DBusObjectManager::object-removed signals are synthesized for all currently existing object proxies. Since Gio.DBusObjectManagerClient:name-owner is NULL when this happens, you can use this information to disambiguate a synthesized signal from a genuine signal caused by object removal on the remote DBusObjectManager. Similarly, when a new name owner appears, Gio.DBusObjectManager::object-added signals are synthesized while Gio.DBusObjectManagerClient:name-owner is still NULL. Only when all object proxies have been added, the Gio.DBusObjectManagerClient:name-owner is set to the new name owner (this includes emission of the GObject.Object::notify signal). Furthermore, you are guaranteed that Gio.DBusObjectManagerClient:name-owner will alternate between a name owner (e.g. :1.42) and NULL even in the case where the name of interest is atomically replaced

Ultimately, GDBusObjectManagerClient is used to obtain DBusProxy instances. All signals (including the org.freedesktop.DBus.Properties::PropertiesChanged signal) delivered to DBusProxy instances are guaranteed to originate from the name owner. This guarantee along with the behavior described above, means that certain race conditions including the “half the proxy is from the old owner and the other half is from the new owner” problem cannot happen.

To avoid having the application connect to signals on the returned DBusObjectProxy and DBusProxy objects, the Gio.DBusObject::interface-added, Gio.DBusObject::interface-removed, Gio.DBusProxy::g-properties-changed and Gio.DBusProxy::g-signal signals are also emitted on the GDBusObjectManagerClient instance managing these objects. The signals emitted are Gio.DBusObjectManager::interface-added, Gio.DBusObjectManager::interface-removed, Gio.DBusObjectManagerClient::interface-proxy-properties-changed and Gio.DBusObjectManagerClient::interface-proxy-signal.

Note that all callbacks and signals are emitted in the thread-default main context (see MainContext#pushThreadDefault) that the GDBusObjectManagerClient object was constructed in. Additionally, the DBusObjectProxy and DBusProxy objects originating from the GDBusObjectManagerClient object will be created in the same context and, consequently, will deliver signals in the same main loop.

Since:
2.30

  • Constructor Details

    • DBusObjectManagerClient

      public DBusObjectManagerClient(MemorySegment address)
      Create a DBusObjectManagerClient instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • DBusObjectManagerClient

      public DBusObjectManagerClient()
      Create a new DBusObjectManagerClient.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the DBusObjectManagerClient class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected DBusObjectManagerClient asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class GObject
      Returns:
      the instance as if it were its parent type

    • finish

      public static DBusObjectManagerClient finish(AsyncResult res) throws GErrorException
      Finishes an operation started with g_dbus_object_manager_client_new().
      Parameters:
      res - A GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_object_manager_client_new().
      Returns:
      A GDBusObjectManagerClient object or null if error is set. Free with g_object_unref().
      Throws:
      GErrorException - see GError
      Since:
      2.30

    • forBusFinish

      public static DBusObjectManagerClient forBusFinish(AsyncResult res) throws GErrorException
      Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
      Parameters:
      res - A GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().
      Returns:
      A GDBusObjectManagerClient object or null if error is set. Free with g_object_unref().
      Throws:
      GErrorException - see GError
      Since:
      2.30

    • forBusSync

      public static DBusObjectManagerClient forBusSync(BusType busType, Set<DBusObjectManagerClientFlags> flags, String name, String objectPath, @Nullable DBusProxyTypeFunc getProxyTypeFunc, @Nullable Cancellable cancellable) throws GErrorException

      Like g_dbus_object_manager_client_new_sync() but takes a GBusType instead of a GDBusConnection.

      This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus() for the asynchronous version.

      Parameters:
      busType - A GBusType.
      flags - Zero or more flags from the GDBusObjectManagerClientFlags enumeration.
      name - The owner of the control object (unique or well-known name).
      objectPath - The object path of the control object.
      getProxyTypeFunc - A GDBusProxyTypeFunc function or null to always construct GDBusProxy proxies.
      cancellable - A GCancellable or null
      Returns:
      A GDBusObjectManagerClient object or null if error is set. Free with g_object_unref().
      Throws:
      GErrorException - see GError
      Since:
      2.30

    • forBusSync

      public static DBusObjectManagerClient forBusSync(BusType busType, DBusObjectManagerClientFlags flags, String name, String objectPath, @Nullable DBusProxyTypeFunc getProxyTypeFunc, @Nullable Cancellable cancellable) throws GErrorException

      Like g_dbus_object_manager_client_new_sync() but takes a GBusType instead of a GDBusConnection.

      This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus() for the asynchronous version.

      Parameters:
      busType - A GBusType.
      flags - Zero or more flags from the GDBusObjectManagerClientFlags enumeration.
      name - The owner of the control object (unique or well-known name).
      objectPath - The object path of the control object.
      getProxyTypeFunc - A GDBusProxyTypeFunc function or null to always construct GDBusProxy proxies.
      cancellable - A GCancellable or null
      Returns:
      A GDBusObjectManagerClient object or null if error is set. Free with g_object_unref().
      Throws:
      GErrorException - see GError
      Since:
      2.30

    • sync

      public static DBusObjectManagerClient sync(DBusConnection connection, Set<DBusObjectManagerClientFlags> flags, @Nullable String name, String objectPath, @Nullable DBusProxyTypeFunc getProxyTypeFunc, @Nullable Cancellable cancellable) throws GErrorException

      Creates a new GDBusObjectManagerClient object.

      This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See g_dbus_object_manager_client_new() for the asynchronous version.

      Parameters:
      connection - A GDBusConnection.
      flags - Zero or more flags from the GDBusObjectManagerClientFlags enumeration.
      name - The owner of the control object (unique or well-known name), or null when not using a message bus connection.
      objectPath - The object path of the control object.
      getProxyTypeFunc - A GDBusProxyTypeFunc function or null to always construct GDBusProxy proxies.
      cancellable - A GCancellable or null
      Returns:
      A GDBusObjectManagerClient object or null if error is set. Free with g_object_unref().
      Throws:
      GErrorException - see GError
      Since:
      2.30

    • sync

      public static DBusObjectManagerClient sync(DBusConnection connection, DBusObjectManagerClientFlags flags, @Nullable String name, String objectPath, @Nullable DBusProxyTypeFunc getProxyTypeFunc, @Nullable Cancellable cancellable) throws GErrorException

      Creates a new GDBusObjectManagerClient object.

      This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See g_dbus_object_manager_client_new() for the asynchronous version.

      Parameters:
      connection - A GDBusConnection.
      flags - Zero or more flags from the GDBusObjectManagerClientFlags enumeration.
      name - The owner of the control object (unique or well-known name), or null when not using a message bus connection.
      objectPath - The object path of the control object.
      getProxyTypeFunc - A GDBusProxyTypeFunc function or null to always construct GDBusProxy proxies.
      cancellable - A GCancellable or null
      Returns:
      A GDBusObjectManagerClient object or null if error is set. Free with g_object_unref().
      Throws:
      GErrorException - see GError
      Since:
      2.30

    • new_

      public static void new_(DBusConnection connection, Set<DBusObjectManagerClientFlags> flags, String name, String objectPath, @Nullable DBusProxyTypeFunc getProxyTypeFunc, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)

      Asynchronously creates a new GDBusObjectManagerClient object.

      This is an asynchronous failable constructor. When the result is ready, callback will be invoked in the thread-default main context (see MainContext#pushThreadDefault) of the thread you are calling this method from. You can then call g_dbus_object_manager_client_new_finish() to get the result. See g_dbus_object_manager_client_new_sync() for the synchronous version.

      Parameters:
      connection - A GDBusConnection.
      flags - Zero or more flags from the GDBusObjectManagerClientFlags enumeration.
      name - The owner of the control object (unique or well-known name).
      objectPath - The object path of the control object.
      getProxyTypeFunc - A GDBusProxyTypeFunc function or null to always construct GDBusProxy proxies.
      cancellable - A GCancellable or null
      callback - A GAsyncReadyCallback to call when the request is satisfied.
      Since:
      2.30

    • new_

      public static void new_(DBusConnection connection, DBusObjectManagerClientFlags flags, String name, String objectPath, @Nullable DBusProxyTypeFunc getProxyTypeFunc, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)

      Asynchronously creates a new GDBusObjectManagerClient object.

      This is an asynchronous failable constructor. When the result is ready, callback will be invoked in the thread-default main context (see MainContext#pushThreadDefault) of the thread you are calling this method from. You can then call g_dbus_object_manager_client_new_finish() to get the result. See g_dbus_object_manager_client_new_sync() for the synchronous version.

      Parameters:
      connection - A GDBusConnection.
      flags - Zero or more flags from the GDBusObjectManagerClientFlags enumeration.
      name - The owner of the control object (unique or well-known name).
      objectPath - The object path of the control object.
      getProxyTypeFunc - A GDBusProxyTypeFunc function or null to always construct GDBusProxy proxies.
      cancellable - A GCancellable or null
      callback - A GAsyncReadyCallback to call when the request is satisfied.
      Since:
      2.30

    • newForBus

      public static void newForBus(BusType busType, Set<DBusObjectManagerClientFlags> flags, String name, String objectPath, @Nullable DBusProxyTypeFunc getProxyTypeFunc, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)

      Like g_dbus_object_manager_client_new() but takes a GBusType instead of a GDBusConnection.

      This is an asynchronous failable constructor. When the result is ready, callback will be invoked in the thread-default main context (see MainContext#pushThreadDefault) of the thread you are calling this method from. You can then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.

      Parameters:
      busType - A GBusType.
      flags - Zero or more flags from the GDBusObjectManagerClientFlags enumeration.
      name - The owner of the control object (unique or well-known name).
      objectPath - The object path of the control object.
      getProxyTypeFunc - A GDBusProxyTypeFunc function or null to always construct GDBusProxy proxies.
      cancellable - A GCancellable or null
      callback - A GAsyncReadyCallback to call when the request is satisfied.
      Since:
      2.30

    • newForBus

      public static void newForBus(BusType busType, DBusObjectManagerClientFlags flags, String name, String objectPath, @Nullable DBusProxyTypeFunc getProxyTypeFunc, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)

      Like g_dbus_object_manager_client_new() but takes a GBusType instead of a GDBusConnection.

      This is an asynchronous failable constructor. When the result is ready, callback will be invoked in the thread-default main context (see MainContext#pushThreadDefault) of the thread you are calling this method from. You can then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.

      Parameters:
      busType - A GBusType.
      flags - Zero or more flags from the GDBusObjectManagerClientFlags enumeration.
      name - The owner of the control object (unique or well-known name).
      objectPath - The object path of the control object.
      getProxyTypeFunc - A GDBusProxyTypeFunc function or null to always construct GDBusProxy proxies.
      cancellable - A GCancellable or null
      callback - A GAsyncReadyCallback to call when the request is satisfied.
      Since:
      2.30

    • getConnection

      public DBusConnection getConnection()
      Gets the GDBusConnection used by manager.
      Returns:
      A GDBusConnection object. Do not free, the object belongs to manager.
      Since:
      2.30

    • getFlags

      public Set<DBusObjectManagerClientFlags> getFlags()
      Gets the flags that this DBusObjectManagerClient was constructed with.
      Returns:
      Zero of more flags from the GDBusObjectManagerClientFlags enumeration.
      Since:
      2.30

    • getName

      public String getName()
      Gets the name that this DBusObjectManagerClient is for, or null if not a message bus connection.
      Returns:
      A unique or well-known name. Do not free, the string belongs to manager.
      Since:
      2.30

    • getNameOwner

      public @Nullable String getNameOwner()
      The unique name that owns the name that this DBusObjectManagerClient is for or null if no-one currently owns that name. You can connect to the GObject::notify signal to track changes to the GDBusObjectManagerClient:name-owner property.
      Returns:
      The name owner or null if no name owner exists. Free with g_free().
      Since:
      2.30

    • interfaceProxyPropertiesChanged

      protected void interfaceProxyPropertiesChanged(DBusObjectProxy objectProxy, DBusProxy interfaceProxy, Variant changedProperties, String invalidatedProperties)
      Signal class handler for the GDBusObjectManagerClient::interface-proxy-properties-changed signal.

    • interfaceProxySignal

      protected void interfaceProxySignal(DBusObjectProxy objectProxy, DBusProxy interfaceProxy, String senderName, String signalName, Variant parameters)
      Signal class handler for the GDBusObjectManagerClient::interface-proxy-signal signal.

    • onInterfaceProxyPropertiesChanged

      public SignalConnection<DBusObjectManagerClient.InterfaceProxyPropertiesChangedCallback> onInterfaceProxyPropertiesChanged(DBusObjectManagerClient.InterfaceProxyPropertiesChangedCallback handler)

      Emitted when one or more D-Bus properties on proxy changes. The local cache has already been updated when this signal fires. Note that both changedProperties and invalidatedProperties are guaranteed to never be null (either may be empty though).

      This signal exists purely as a convenience to avoid having to connect signals to all interface proxies managed by manager.

      This signal is emitted in the thread-default main context (see MainContext#pushThreadDefault) that manager was constructed in.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      2.30
      See Also:

    • emitInterfaceProxyPropertiesChanged

      public void emitInterfaceProxyPropertiesChanged(@Nullable DBusObjectProxy objectProxy, @Nullable DBusProxy interfaceProxy, @Nullable Variant changedProperties, @Nullable String @Nullable [] invalidatedProperties)
      Emits the "interface-proxy-properties-changed" signal. See onInterfaceProxyPropertiesChanged(DBusObjectManagerClient.InterfaceProxyPropertiesChangedCallback).

    • onInterfaceProxySignal

      public SignalConnection<DBusObjectManagerClient.InterfaceProxySignalCallback> onInterfaceProxySignal(DBusObjectManagerClient.InterfaceProxySignalCallback handler)

      Emitted when a D-Bus signal is received on interfaceProxy.

      This signal exists purely as a convenience to avoid having to connect signals to all interface proxies managed by manager.

      This signal is emitted in the thread-default main context (see MainContext#pushThreadDefault) that manager was constructed in.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      2.30
      See Also:

    • emitInterfaceProxySignal

      public void emitInterfaceProxySignal(@Nullable DBusObjectProxy objectProxy, @Nullable DBusProxy interfaceProxy, String senderName, String signalName, @Nullable Variant parameters)
      Emits the "interface-proxy-signal" signal. See onInterfaceProxySignal(DBusObjectManagerClient.InterfaceProxySignalCallback).

    • builder

      public static DBusObjectManagerClient.Builder<? extends DBusObjectManagerClient.Builder> builder()
      A DBusObjectManagerClient.Builder object constructs a DBusObjectManagerClient with the specified properties. Use the various set...() methods to set properties, and finish construction with DBusObjectManagerClient.Builder.build().
      Returns:
      the builder object