GDBusObjectManagerClient

## GDBusObjectManagerClient GDBusObjectManagerClient — Client-side object manager |

## Synopsis

    #include <gio/gio.h>

                        GDBusObjectManagerClient;
    struct              GDBusObjectManagerClientClass;
    enum                GDBusObjectManagerClientFlags;
    GType               (*GDBusProxyTypeFunc)               (GDBusObjectManagerClient *manager,
                                                             const gchar *object_path,
                                                             const gchar *interface_name,
                                                             gpointer user_data);
    void                g_dbus_object_manager_client_new    (GDBusConnection *connection,
                                                             GDBusObjectManagerClientFlags flags,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             GDBusProxyTypeFunc get_proxy_type_func,
                                                             gpointer get_proxy_type_user_data,
                                                             GDestroyNotify get_proxy_type_destroy_notify,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDBusObjectManager * g_dbus_object_manager_client_new_finish
                                                            (GAsyncResult *res,
                                                             GError **error);
    GDBusObjectManager * g_dbus_object_manager_client_new_sync
                                                            (GDBusConnection *connection,
                                                             GDBusObjectManagerClientFlags flags,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             GDBusProxyTypeFunc get_proxy_type_func,
                                                             gpointer get_proxy_type_user_data,
                                                             GDestroyNotify get_proxy_type_destroy_notify,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                g_dbus_object_manager_client_new_for_bus
                                                            (GBusType bus_type,
                                                             GDBusObjectManagerClientFlags flags,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             GDBusProxyTypeFunc get_proxy_type_func,
                                                             gpointer get_proxy_type_user_data,
                                                             GDestroyNotify get_proxy_type_destroy_notify,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDBusObjectManager * g_dbus_object_manager_client_new_for_bus_finish
                                                            (GAsyncResult *res,
                                                             GError **error);
    GDBusObjectManager * g_dbus_object_manager_client_new_for_bus_sync
                                                            (GBusType bus_type,
                                                             GDBusObjectManagerClientFlags flags,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             GDBusProxyTypeFunc get_proxy_type_func,
                                                             gpointer get_proxy_type_user_data,
                                                             GDestroyNotify get_proxy_type_destroy_notify,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GDBusConnection *   g_dbus_object_manager_client_get_connection
                                                            (GDBusObjectManagerClient *manager);
    GDBusObjectManagerClientFlags g_dbus_object_manager_client_get_flags
                                                            (GDBusObjectManagerClient *manager);
    const gchar *       g_dbus_object_manager_client_get_name
                                                            (GDBusObjectManagerClient *manager);
    gchar *             g_dbus_object_manager_client_get_name_owner
                                                            (GDBusObjectManagerClient *manager);

## Object Hierarchy

      GObject
       +----GDBusObjectManagerClient

## Implemented Interfaces

GDBusObjectManagerClient implements GInitable, GAsyncInitable and GDBusObjectManager.

## Properties

      "bus-type"                 GBusType              : Write / Construct Only
      "connection"               GDBusConnection*      : Read / Write / Construct Only
      "flags"                    GDBusObjectManagerClientFlags  : Read / Write / Construct Only
      "get-proxy-type-destroy-notify" gpointer              : Read / Write / Construct Only
      "get-proxy-type-func"      gpointer              : Read / Write / Construct Only
      "get-proxy-type-user-data" gpointer              : Read / Write / Construct Only
      "name"                     gchar*                : Read / Write / Construct Only
      "name-owner"               gchar*                : Read
      "object-path"              gchar*                : Read / Write / Construct Only

## Signals

      "interface-proxy-properties-changed"             : Run Last
      "interface-proxy-signal"                         : Run Last

## Description

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

Once an instance of this type has been created, you can connect to the "object-added" and "object-removed" signals and inspect the GDBusObjectProxy objects returned by `g_dbus_object_manager_get_objects()`.

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. `g_dbus_object_manager_get_objects()` returns the empty list) and the "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 "notify" signal to watch for changes on the "name-owner" property. When the name owner vanishes, the behavior is that "name-owner" is set to `NULL` (this includes emission of the "notify" signal) and then "object-removed" signals are synthesized for all currently existing object proxies. Since "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 GDBusObjectManager. Similarly, when a new name owner appears, "object-added" signals are synthesized while "name-owner" is still `NULL`. Only when all object proxies have been added, the "name-owner" is set to the new name owner (this includes emission of the "notify" signal). Furthermore, you are guaranteed that "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 GDBusProxy instances. All signals (including the `org.freedesktop.DBus.Properties::PropertiesChanged` signal) delivered to GDBusProxy 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 GDBusObjectProxy and GDBusProxy objects, the "interface-added", "interface-removed", "g-properties-changed" and "g-signal" signals are also emitted on the GDBusObjectManagerClient instance managing these objects. The signals emitted are "interface-added", "interface-removed", "interface-proxy-properties-changed" and "interface-proxy-signal".

Note that all callbacks and signals are emitted in the thread-default main loop that the GDBusObjectManagerClient object was constructed in. Additionally, the GDBusObjectProxy and GDBusProxy objects originating from the GDBusObjectManagerClient object will be created in the same context and, consequently, will deliver signals in the same main loop.

## Details

### GDBusObjectManagerClient

    typedef struct _GDBusObjectManagerClient GDBusObjectManagerClient;

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

Since 2.30

### struct GDBusObjectManagerClientClass

    struct GDBusObjectManagerClientClass {
      GObjectClass parent_class;

      /* signals */
      void    (*interface_proxy_signal)             (GDBusObjectManagerClient *manager,
                                                     GDBusObjectProxy         *object_proxy,
                                                     GDBusProxy               *interface_proxy,
                                                     const gchar              *sender_name,
                                                     const gchar              *signal_name,
                                                     GVariant                 *parameters);

      void    (*interface_proxy_properties_changed) (GDBusObjectManagerClient   *manager,
                                                     GDBusObjectProxy           *object_proxy,
                                                     GDBusProxy                 *interface_proxy,
                                                     GVariant                   *changed_properties,
                                                     const gchar* const         *invalidated_properties);
    };

Class structure for GDBusObjectManagerClient.

GObjectClass `parent_class`; | The parent class.
`interface_proxy_signal` () | Signal class handler for the "interface-proxy-signal" signal.
`interface_proxy_properties_changed` () | Signal class handler for the "interface-proxy-properties-changed" signal.

Since 2.30

### enum GDBusObjectManagerClientFlags

    typedef enum {
      G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_NONE = 0,
      G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START = (1<<0)
    } GDBusObjectManagerClientFlags;

Flags used when constructing a GDBusObjectManagerClient.

`G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_NONE` | No flags set.
`G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START` | If not set and the manager is for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only be used in managers for well-known names.

Since 2.30

### GDBusProxyTypeFunc ()

    GType               (*GDBusProxyTypeFunc)               (GDBusObjectManagerClient *manager,
                                                             const gchar *object_path,
                                                             const gchar *interface_name,
                                                             gpointer user_data);

Function signature for a function used to determine the GType to use for an interface proxy (if `interface_name` is not `NULL`) or object proxy (if `interface_name` is `NULL`).

This function is called in the thread-default main loop that `manager` was constructed in.

`manager` : | A GDBusObjectManagerClient.
`object_path` : | The object path of the remote object.
`interface_name` : | The interface name of the remote object or `NULL` if a GDBusObjectProxy GType is requested. [allow-none]
`user_data` : | User data.
Returns : | A GType to use for the remote object. The returned type must be a GDBusProxy- or GDBusObjectProxy-derived type.

Since 2.30

### g_dbus_object_manager_client_new ()

    void                g_dbus_object_manager_client_new    (GDBusConnection *connection,
                                                             GDBusObjectManagerClientFlags flags,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             GDBusProxyTypeFunc get_proxy_type_func,
                                                             gpointer get_proxy_type_user_data,
                                                             GDestroyNotify get_proxy_type_destroy_notify,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

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 loop 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.

`connection` : | A GDBusConnection.
`flags` : | Zero or more flags from the GDBusObjectManagerClientFlags enumeration.
`name` : | The owner of the control object (unique or well-known name).
`object_path` : | The object path of the control object.
`get_proxy_type_func` : | A GDBusProxyTypeFunc function or `NULL` to always construct GDBusProxy proxies.
`get_proxy_type_user_data` : | User data to pass to `get_proxy_type_func`.
`get_proxy_type_destroy_notify` : | Free function for `get_proxy_type_user_data` or `NULL`. [allow-none]
`cancellable` : | A GCancellable or `NULL`
`callback` : | A GAsyncReadyCallback to call when the request is satisfied.
`user_data` : | The data to pass to `callback`.

Since 2.30

### g_dbus_object_manager_client_new_finish ()

    GDBusObjectManager * g_dbus_object_manager_client_new_finish
                                                            (GAsyncResult *res,
                                                             GError **error);

Finishes an operation started with `g_dbus_object_manager_client_new()`.

`res` : | A GAsyncResult obtained from the GAsyncReadyCallback passed to `g_dbus_object_manager_client_new()`.
`error` : | Return location for error or `NULL`.
Returns : | A GDBusObjectManagerClient object or `NULL` if `error` is set. Free with `g_object_unref()`. [transfer full][type GDBusObjectManagerClient]

Since 2.30

### g_dbus_object_manager_client_new_sync ()

    GDBusObjectManager * g_dbus_object_manager_client_new_sync
                                                            (GDBusConnection *connection,
                                                             GDBusObjectManagerClientFlags flags,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             GDBusProxyTypeFunc get_proxy_type_func,
                                                             gpointer get_proxy_type_user_data,
                                                             GDestroyNotify get_proxy_type_destroy_notify,
                                                             GCancellable *cancellable,
                                                             GError **error);

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.

`connection` : | A GDBusConnection.
`flags` : | Zero or more flags from the GDBusObjectManagerClientFlags enumeration.
`name` : | The owner of the control object (unique or well-known name).
`object_path` : | The object path of the control object.
`get_proxy_type_func` : | A GDBusProxyTypeFunc function or `NULL` to always construct GDBusProxy proxies.
`get_proxy_type_user_data` : | User data to pass to `get_proxy_type_func`.
`get_proxy_type_destroy_notify` : | Free function for `get_proxy_type_user_data` or `NULL`. [allow-none]
`cancellable` : | A GCancellable or `NULL`
`error` : | Return location for error or `NULL`.
Returns : | A GDBusObjectManagerClient object or `NULL` if `error` is set. Free with `g_object_unref()`. [transfer full][type GDBusObjectManagerClient]

Since 2.30

### g_dbus_object_manager_client_new_for_bus ()

    void                g_dbus_object_manager_client_new_for_bus
                                                            (GBusType bus_type,
                                                             GDBusObjectManagerClientFlags flags,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             GDBusProxyTypeFunc get_proxy_type_func,
                                                             gpointer get_proxy_type_user_data,
                                                             GDestroyNotify get_proxy_type_destroy_notify,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

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 loop 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.

`bus_type` : | A GBusType.
`flags` : | Zero or more flags from the GDBusObjectManagerClientFlags enumeration.
`name` : | The owner of the control object (unique or well-known name).
`object_path` : | The object path of the control object.
`get_proxy_type_func` : | A GDBusProxyTypeFunc function or `NULL` to always construct GDBusProxy proxies.
`get_proxy_type_user_data` : | User data to pass to `get_proxy_type_func`.
`get_proxy_type_destroy_notify` : | Free function for `get_proxy_type_user_data` or `NULL`. [allow-none]
`cancellable` : | A GCancellable or `NULL`
`callback` : | A GAsyncReadyCallback to call when the request is satisfied.
`user_data` : | The data to pass to `callback`.

Since 2.30

### g_dbus_object_manager_client_new_for_bus_finish ()

    GDBusObjectManager * g_dbus_object_manager_client_new_for_bus_finish
                                                            (GAsyncResult *res,
                                                             GError **error);

Finishes an operation started with `g_dbus_object_manager_client_new_for_bus()`.

`res` : | A GAsyncResult obtained from the GAsyncReadyCallback passed to `g_dbus_object_manager_client_new_for_bus()`.
`error` : | Return location for error or `NULL`.
Returns : | A GDBusObjectManagerClient object or `NULL` if `error` is set. Free with `g_object_unref()`. [transfer full][type GDBusObjectManagerClient]

Since 2.30

### g_dbus_object_manager_client_new_for_bus_sync ()

    GDBusObjectManager * g_dbus_object_manager_client_new_for_bus_sync
                                                            (GBusType bus_type,
                                                             GDBusObjectManagerClientFlags flags,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             GDBusProxyTypeFunc get_proxy_type_func,
                                                             gpointer get_proxy_type_user_data,
                                                             GDestroyNotify get_proxy_type_destroy_notify,
                                                             GCancellable *cancellable,
                                                             GError **error);

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.

`bus_type` : | A GBusType.
`flags` : | Zero or more flags from the GDBusObjectManagerClientFlags enumeration.
`name` : | The owner of the control object (unique or well-known name).
`object_path` : | The object path of the control object.
`get_proxy_type_func` : | A GDBusProxyTypeFunc function or `NULL` to always construct GDBusProxy proxies.
`get_proxy_type_user_data` : | User data to pass to `get_proxy_type_func`.
`get_proxy_type_destroy_notify` : | Free function for `get_proxy_type_user_data` or `NULL`. [allow-none]
`cancellable` : | A GCancellable or `NULL`
`error` : | Return location for error or `NULL`.
Returns : | A GDBusObjectManagerClient object or `NULL` if `error` is set. Free with `g_object_unref()`. [transfer full][type GDBusObjectManagerClient]

Since 2.30

### g_dbus_object_manager_client_get_connection ()

    GDBusConnection *   g_dbus_object_manager_client_get_connection
                                                            (GDBusObjectManagerClient *manager);

Gets the GDBusConnection used by `manager`.

`manager` : | A GDBusObjectManagerClient
Returns : | A GDBusConnection object. Do not free, the object belongs to `manager`. [transfer none]

Since 2.30

### g_dbus_object_manager_client_get_flags ()

    GDBusObjectManagerClientFlags g_dbus_object_manager_client_get_flags
                                                            (GDBusObjectManagerClient *manager);

Gets the flags that `manager` was constructed with.

`manager` : | A GDBusObjectManagerClient
Returns : | Zero of more flags from the GDBusObjectManagerClientFlags enumeration.

Since 2.30

### g_dbus_object_manager_client_get_name ()

    const gchar *       g_dbus_object_manager_client_get_name
                                                            (GDBusObjectManagerClient *manager);

Gets the name that `manager` is for.

`manager` : | A GDBusObjectManagerClient
Returns : | A unique or well-known name. Do not free, the string belongs to `manager`.

Since 2.30

### g_dbus_object_manager_client_get_name_owner ()

    gchar *             g_dbus_object_manager_client_get_name_owner
                                                            (GDBusObjectManagerClient *manager);

The unique name that owns the name that `manager` is for or `NULL` if no-one currently owns that name. You can connect to the "notify" signal to track changes to the "name-owner" property.

`manager` : | A GDBusObjectManagerClient.
Returns : | The name owner or `NULL` if no name owner exists. Free with `g_free()`.

Since 2.30

## Property Details

### The `"bus-type"` property

      "bus-type"                 GBusType              : Write / Construct Only

If this property is not `G_BUS_TYPE_NONE`, then "connection" must be `NULL` and will be set to the GDBusConnection obtained by calling `g_bus_get()` with the value of this property.

Default value: G_BUS_TYPE_NONE

Since 2.30

### The `"connection"` property

      "connection"               GDBusConnection*      : Read / Write / Construct Only

The GDBusConnection to use.

Since 2.30

### The `"flags"` property

      "flags"                    GDBusObjectManagerClientFlags  : Read / Write / Construct Only

Flags from the GDBusObjectManagerClientFlags enumeration.

Since 2.30

### The `"get-proxy-type-destroy-notify"` property

      "get-proxy-type-destroy-notify" gpointer              : Read / Write / Construct Only

A GDestroyNotify for the gpointer user_data in "get-proxy-type-user-data".

Since 2.30

### The `"get-proxy-type-func"` property

      "get-proxy-type-func"      gpointer              : Read / Write / Construct Only

The GDBusProxyTypeFunc to use when determining what GType to use for interface proxies or `NULL`.

Since 2.30

### The `"get-proxy-type-user-data"` property

      "get-proxy-type-user-data" gpointer              : Read / Write / Construct Only

The gpointer user_data to pass to "get-proxy-type-func".

Since 2.30

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

The well-known name or unique name that the manager is for.

Default value: NULL

Since 2.30

### The `"name-owner"` property

      "name-owner"               gchar*                : Read

The unique name that owns "name" or `NULL` if no-one is currently owning the name. Connect to the "notify" signal to track changes to this property.

Default value: NULL

Since 2.30

### The `"object-path"` property

      "object-path"              gchar*                : Read / Write / Construct Only

The object path the manager is for.

Default value: NULL

Since 2.30

## Signal Details

### The `"interface-proxy-properties-changed"` signal

    void                user_function                      (GDBusObjectManagerClient *manager,
                                                            GDBusObjectProxy         *object_proxy,
                                                            GDBusProxy               *interface_proxy,
                                                            GVariant                 *changed_properties,
                                                            GStrv                     invalidated_properties,
                                                            gpointer                  user_data)                   : Run Last

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 `changed_properties` and `invalidated_properties` 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 loop that `manager` was constructed in.

`manager` : | The GDBusObjectManagerClient emitting the signal.
`object_proxy` : | The GDBusObjectProxy on which an interface has properties that are changing.
`interface_proxy` : | The GDBusProxy that has properties that are changing.
`changed_properties` : | A GVariant containing the properties that changed.
`invalidated_properties` : | A `NULL` terminated array of properties that was invalidated.
`user_data` : | user data set when the signal handler was connected.

Since 2.30

### The `"interface-proxy-signal"` signal

    void                user_function                      (GDBusObjectManagerClient *manager,
                                                            GDBusObjectProxy         *object_proxy,
                                                            GDBusProxy               *interface_proxy,
                                                            gchar                    *sender_name,
                                                            gchar                    *signal_name,
                                                            GVariant                 *parameters,
                                                            gpointer                  user_data)            : Run Last

Emitted when a D-Bus signal is received on `interface_proxy`.

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 loop that `manager` was constructed in.

`manager` : | The GDBusObjectManagerClient emitting the signal.
`object_proxy` : | The GDBusObjectProxy on which an interface is emitting a D-Bus signal.
`interface_proxy` : | The GDBusProxy that is emitting a D-Bus signal.
`sender_name` : | The sender of the signal or NULL if the connection is not a bus connection.
`signal_name` : | The signal name.
`parameters` : | A GVariant tuple with parameters for the signal.
`user_data` : | user data set when the signal handler was connected.

Since 2.30