Gio.DBusProxy
Description: Reference for Gio.DBusProxy

### Class

# GioDBusProxy

since: 2.26

#### Description [src]

    class Gio.DBusProxy : GObject.Object
      implements Gio.AsyncInitable, Gio.DBusInterface, Gio.Initable {
      /* No available fields */
    }

`GDBusProxy` is a base class used for proxies to access a D-Bus interface on a remote object. A `GDBusProxy` can be constructed for both well-known and unique names.

By default, `GDBusProxy` will cache all properties (and listen to changes) of the remote object, and proxy all signals that get emitted. This behaviour can be changed by passing suitable `GDBusProxyFlags` when the proxy is created. If the proxy is for a well-known name, the property cache is flushed when the name owner vanishes and reloaded when a name owner appears.

The unique name owner of the proxy’s name is tracked and can be read from `GDBusProxy:g-name-owner`. Connect to the `GObject::notify` signal to get notified of changes. Additionally, only signals and property changes emitted from the current name owner are considered and calls are always sent to the current name owner. This avoids a number of race conditions when the name is lost by one owner and claimed by another. However, if no name owner currently exists, then calls will be sent to the well-known name which may result in the message bus launching an owner (unless `G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` is set).

If the proxy is for a stateless D-Bus service, where the name owner may be started and stopped between calls, the `GDBusProxy:g-name-owner` tracking of `GDBusProxy` will cause the proxy to drop signal and property changes from the service after it has restarted for the first time. When interacting with a stateless D-Bus service, do not use `GDBusProxy` — use direct D-Bus method calls and signal connections.

The generic `GDBusProxy::g-properties-changed` and `GDBusProxy::g-signal` signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass `GDBusProxy`, and have more natural properties and signals in your derived class. This example shows how this can easily be done using the `gdbus-codegen` tool.

A `GDBusProxy` instance can be used from multiple threads but note that all signals (e.g. `GDBusProxy::g-signal`, `GDBusProxy::g-properties-changed` and `GObject::notify`) are emitted in the thread-default main context (see `g_main_context_push_thread_default()`) of the thread where the instance was constructed.

## A watch proxy example

An example using a proxy for a well-known name can be found in `gdbus-example-watch-proxy.c`.

Available since: 2.26

#### Ancestors

- GObject

#### Implements

- GAsyncInitable
- GDBusInterface
- GInitable

#### Constructors

###### g_dbus_proxy_new_finish

Finishes creating a `GDBusProxy`.

since: 2.26

###### g_dbus_proxy_new_for_bus_finish

Finishes creating a `GDBusProxy`.

since: 2.26

###### g_dbus_proxy_new_for_bus_sync

Like `g_dbus_proxy_new_sync()` but takes a `GBusType` instead of a `GDBusConnection`.

since: 2.26

###### g_dbus_proxy_new_sync

Creates a proxy for accessing `interface_name` on the remote object at `object_path` owned by `name` at `connection` and synchronously loads D-Bus properties unless the `G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES` flag is used.

since: 2.26

#### Functions

###### g_dbus_proxy_new

Creates a proxy for accessing `interface_name` on the remote object at `object_path` owned by `name` at `connection` and asynchronously loads D-Bus properties unless the `G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES` flag is used. Connect to the `GDBusProxy::g-properties-changed` signal to get notified about property changes.

since: 2.26

###### g_dbus_proxy_new_for_bus

Like `g_dbus_proxy_new()` but takes a `GBusType` instead of a `GDBusConnection`.

since: 2.26

#### Instance methods

###### g_dbus_proxy_call

Asynchronously invokes the `method_name` method on `proxy`.

since: 2.26

###### g_dbus_proxy_call_finish

Finishes an operation started with g_dbus_proxy_call().

since: 2.26

###### g_dbus_proxy_call_sync

Synchronously invokes the `method_name` method on `proxy`.

since: 2.26

###### g_dbus_proxy_call_with_unix_fd_list

Like `g_dbus_proxy_call()` but also takes a `GUnixFDList` object.

since: 2.30

###### g_dbus_proxy_call_with_unix_fd_list_finish

Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().

since: 2.30

###### g_dbus_proxy_call_with_unix_fd_list_sync

Like `g_dbus_proxy_call_sync()` but also takes and returns `GUnixFDList` objects.

since: 2.30

###### g_dbus_proxy_get_cached_property

Looks up the value for a property from the cache. This call does no blocking IO.

since: 2.26

###### g_dbus_proxy_get_cached_property_names

Gets the names of all cached properties on `proxy`.

since: 2.26

###### g_dbus_proxy_get_connection

Gets the connection `proxy` is for.

since: 2.26

###### g_dbus_proxy_get_default_timeout

Gets the timeout to use if -1 (specifying default timeout) is passed as `timeout_msec` in the `g_dbus_proxy_call()` and `g_dbus_proxy_call_sync()` functions.

since: 2.26

###### g_dbus_proxy_get_flags

Gets the flags that `proxy` was constructed with.

since: 2.26

###### g_dbus_proxy_get_interface_info

Returns the `GDBusInterfaceInfo`, if any, specifying the interface that `proxy` conforms to. See the `GDBusProxy:g-interface-info` property for more details.

since: 2.26

###### g_dbus_proxy_get_interface_name

Gets the D-Bus interface name `proxy` is for.

since: 2.26

###### g_dbus_proxy_get_name

Gets the name that `proxy` was constructed for.

since: 2.26

###### g_dbus_proxy_get_name_owner

The unique name that owns the name that `proxy` is for or `NULL` if no-one currently owns that name. You may connect to the `GObject::notify` signal to track changes to the `GDBusProxy:g-name-owner` property.

since: 2.26

###### g_dbus_proxy_get_object_path

Gets the object path `proxy` is for.

since: 2.26

###### g_dbus_proxy_set_cached_property

If `value` is not `NULL`, sets the cached value for the property with name `property_name` to the value in `value`.

since: 2.26

###### g_dbus_proxy_set_default_timeout

Sets the timeout to use if -1 (specifying default timeout) is passed as `timeout_msec` in the `g_dbus_proxy_call()` and `g_dbus_proxy_call_sync()` functions.

since: 2.26

###### g_dbus_proxy_set_interface_info

Ensure that interactions with `proxy` conform to the given interface. See the `GDBusProxy:g-interface-info` property for more details.

since: 2.26

##### Methods inherited from GObject (43)

Please see GObject for a full list of methods.

##### Methods inherited from GAsyncInitable (3)

###### g_async_initable_init_async

Starts asynchronous initialization of the object implementing the interface. This must be done before any real use of the object after initial construction. If the object also implements `GInitable` you can optionally call `g_initable_init()` instead.

since: 2.22

###### g_async_initable_init_finish

Finishes asynchronous initialization and returns the result. See g_async_initable_init_async().

since: 2.22

###### g_async_initable_new_finish

Finishes the async construction for the various g_async_initable_new calls, returning the created object or `NULL` on error.

since: 2.22

##### Methods inherited from GDBusInterface (4)

###### g_dbus_interface_dup_object

Gets the `GDBusObject` that `interface_` belongs to, if any.

since: 2.32

###### g_dbus_interface_get_info

Gets D-Bus introspection information for the D-Bus interface implemented by `interface_`.

since: 2.30

###### g_dbus_interface_get_object

Gets the `GDBusObject` that `interface_` belongs to, if any.

since: 2.30

###### g_dbus_interface_set_object

Sets the `GDBusObject` for `interface_` to `object`.

since: 2.30

##### Methods inherited from GInitable (1)

###### g_initable_init

Initializes the object implementing the interface.

since: 2.22

#### Properties

###### Gio.DBusProxy:g-bus-type

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

since: 2.26

###### Gio.DBusProxy:g-connection

The `GDBusConnection` the proxy is for.

since: 2.26

###### Gio.DBusProxy:g-default-timeout

The timeout to use if -1 (specifying default timeout) is passed as `timeout_msec` in the `g_dbus_proxy_call()` and `g_dbus_proxy_call_sync()` functions.

since: 2.26

###### Gio.DBusProxy:g-flags

Flags from the `GDBusProxyFlags` enumeration.

since: 2.26

###### Gio.DBusProxy:g-interface-info

Ensure that interactions with this proxy conform to the given interface. This is mainly to ensure that malformed data received from the other peer is ignored. The given `GDBusInterfaceInfo` is said to be the “expected interface”.

since: 2.26

###### Gio.DBusProxy:g-interface-name

The D-Bus interface name the proxy is for.

since: 2.26

###### Gio.DBusProxy:g-name

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

since: 2.26

###### Gio.DBusProxy:g-name-owner

The unique name that owns `GDBusProxy:g-name` or `NULL` if no-one currently owns that name. You may connect to `GObject::notify` signal to track changes to this property.

since: 2.26

###### Gio.DBusProxy:g-object-path

The object path the proxy is for.

since: 2.26

#### Signals

###### Gio.DBusProxy::g-properties-changed

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

since: 2.26

###### Gio.DBusProxy::g-signal

Emitted when a signal from the remote object and interface that `proxy` is for, has been received.

since: 2.26

##### Signals inherited from GObject (1)

###### GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

#### Class structure

    struct GioDBusProxyClass {
      void (* g_properties_changed) (
        GDBusProxy* proxy,
        GVariant* changed_properties,
        const gchar* const* invalidated_properties
      );
      void (* g_signal) (
        GDBusProxy* proxy,
        const gchar* sender_name,
        const gchar* signal_name,
        GVariant* parameters
      );

    }

Class structure for `GDBusProxy`.

###### Class members

`g_properties_changed: void (* g_properties_changed) ( GDBusProxy* proxy, GVariant* changed_properties, const gchar* const* invalidated_properties )`

  Signal class handler for the `GDBusProxy::g-properties-changed` signal.

`g_signal: void (* g_signal) ( GDBusProxy* proxy, const gchar* sender_name, const gchar* signal_name, GVariant* parameters )`

  Signal class handler for the `GDBusProxy::g-signal` signal.

#### Virtual methods

###### Gio.DBusProxyClass.g_properties_changed

Signal class handler for the `GDBusProxy::g-properties-changed` signal.

###### Gio.DBusProxyClass.g_signal

Signal class handler for the `GDBusProxy::g-signal` signal.