Gio.DBusProxy

g GObject.GInterface GObject.GInterface Gio.AsyncInitable Gio.AsyncInitable GObject.GInterface->Gio.AsyncInitable Gio.DBusInterface Gio.DBusInterface GObject.GInterface->Gio.DBusInterface Gio.Initable Gio.Initable GObject.GInterface->Gio.Initable GObject.Object GObject.Object Gio.DBusProxy Gio.DBusProxy GObject.Object->Gio.DBusProxy Gio.AsyncInitable->Gio.DBusProxy Gio.DBusInterface->Gio.DBusProxy Gio.Initable->Gio.DBusProxy

Subclasses:

None

Methods

Inherited:

GObject.Object (37), Gio.AsyncInitable (4), Gio.DBusInterface (3), Gio.Initable (2)

Structs:

GObject.ObjectClass (5)

class

new (connection, flags, info, name, object_path, interface_name, cancellable, callback, *user_data)

class

new_finish (res)

class

new_for_bus (bus_type, flags, info, name, object_path, interface_name, cancellable, callback, *user_data)

class

new_for_bus_finish (res)

class

new_for_bus_sync (bus_type, flags, info, name, object_path, interface_name, cancellable)

class

new_sync (connection, flags, info, name, object_path, interface_name, cancellable)

call (method_name, parameters, flags, timeout_msec, cancellable, callback, *user_data)

call_finish (res)

call_sync (method_name, parameters, flags, timeout_msec, cancellable)

call_with_unix_fd_list (method_name, parameters, flags, timeout_msec, fd_list, cancellable, callback, *user_data)

call_with_unix_fd_list_finish (res)

call_with_unix_fd_list_sync (method_name, parameters, flags, timeout_msec, fd_list, cancellable)

get_cached_property (property_name)

get_cached_property_names ()

get_connection ()

get_default_timeout ()

get_flags ()

get_interface_info ()

get_interface_name ()

get_name ()

get_name_owner ()

get_object_path ()

set_cached_property (property_name, value)

set_default_timeout (timeout_msec)

set_interface_info (info)

Virtual Methods

Inherited:

GObject.Object (7), Gio.AsyncInitable (2), Gio.DBusInterface (3), Gio.Initable (1)

do_g_properties_changed (changed_properties, invalidated_properties)

do_g_signal (sender_name, signal_name, parameters)

Properties

Name

Type

Flags

Short Description

g-bus-type

Gio.BusType

w/co

g-connection

Gio.DBusConnection

r/w/co

g-default-timeout

int

r/w/c

g-flags

Gio.DBusProxyFlags

r/w/co

g-interface-info

Gio.DBusInterfaceInfo

r/w

g-interface-name

str

r/w/co

g-name

str

r/w/co

g-name-owner

str

r

g-object-path

str

r/w/co

Signals

Inherited:

GObject.Object (1)

Name

Short Description

g-properties-changed

Emitted when one or more D-Bus properties on proxy changes.

g-signal

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

Fields

Inherited:

GObject.Object (1)

Name

Type

Access

Description

parent_instance

GObject.Object

r

Class Details

class Gio.DBusProxy(**kwargs)
Bases:

GObject.Object, Gio.AsyncInitable, Gio.DBusInterface, Gio.Initable

Abstract:

No

Structure:

Gio.DBusProxyClass

Provide comfortable and pythonic method calls.

This marshalls the method arguments into a GVariant, invokes the call_sync() method on the DBusProxy object, and unmarshalls the result GVariant back into a Python tuple.

The first argument always needs to be the D-Bus signature tuple of the method call. Example:

proxy = Gio.DBusProxy.new_sync(…) result = proxy.MyMethod(‘(is)’, 42, ‘hello’)

The exception are methods which take no arguments, like proxy.MyMethod(‘()’). For these you can omit the signature and just write proxy.MyMethod().

Optional keyword arguments:

  • timeout: timeout for the call in milliseconds (default to D-Bus timeout)

  • flags: Combination of Gio.DBusCallFlags.*

  • result_handler: Do an asynchronous method call and invoke

    result_handler(proxy_object, result, user_data) when it finishes.

  • error_handler: If the asynchronous call raises an exception, error_handler(proxy_object, exception, user_data) is called when it finishes. If error_handler is not given, result_handler is called with the exception object as result instead.

  • user_data: Optional user data to pass to result_handler for asynchronous calls.

Example for asynchronous calls:

def mymethod_done(proxy, result, user_data):
if isinstance(result, Exception):

# handle error

else:

# do something with result

proxy.MyMethod(‘(is)’, 42, ‘hello’,

result_handler=mymethod_done, user_data=’data’)

New in version 2.26.

classmethod new(connection, flags, info, name, object_path, interface_name, cancellable, callback, *user_data)[source]
Parameters:

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 Gio.DBusProxyFlags.DO_NOT_LOAD_PROPERTIES flag is used. Connect to the Gio.DBusProxy ::g-properties-changed signal to get notified about property changes.

If the Gio.DBusProxyFlags.DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the Gio.DBusProxy ::g-signal signal to handle signals from the remote object.

If both Gio.DBusProxyFlags.DO_NOT_LOAD_PROPERTIES and Gio.DBusProxyFlags.DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to complete immediately without blocking.

If name is a well-known name and the Gio.DBusProxyFlags.DO_NOT_AUTO_START and Gio.DBusProxyFlags.DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren’t set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a failable asynchronous constructor - when the proxy is ready, callback will be invoked and you can use Gio.DBusProxy.new_finish() to get the result.

See Gio.DBusProxy.new_sync() and for a synchronous version of this constructor.

Gio.DBusProxy is used in this ‘example [gdbus-wellknown-proxy]’.

New in version 2.26.

classmethod new_finish(res)[source]
Parameters:

res (Gio.AsyncResult) – A Gio.AsyncResult obtained from the Gio.AsyncReadyCallback function passed to Gio.DBusProxy.new().

Raises:

GLib.Error

Returns:

A Gio.DBusProxy or None if error is set. Free with GObject.Object.unref().

Return type:

Gio.DBusProxy

Finishes creating a Gio.DBusProxy.

New in version 2.26.

classmethod new_for_bus(bus_type, flags, info, name, object_path, interface_name, cancellable, callback, *user_data)[source]
Parameters:

Like Gio.DBusProxy.new() but takes a Gio.BusType instead of a Gio.DBusConnection.

Gio.DBusProxy is used in this ‘example [gdbus-wellknown-proxy]’.

New in version 2.26.

classmethod new_for_bus_finish(res)[source]
Parameters:

res (Gio.AsyncResult) – A Gio.AsyncResult obtained from the Gio.AsyncReadyCallback function passed to Gio.DBusProxy.new_for_bus().

Raises:

GLib.Error

Returns:

A Gio.DBusProxy or None if error is set. Free with GObject.Object.unref().

Return type:

Gio.DBusProxy

Finishes creating a Gio.DBusProxy.

New in version 2.26.

classmethod new_for_bus_sync(bus_type, flags, info, name, object_path, interface_name, cancellable)[source]
Parameters:
Raises:

GLib.Error

Returns:

A Gio.DBusProxy or None if error is set. Free with GObject.Object.unref().

Return type:

Gio.DBusProxy

Like Gio.DBusProxy.new_sync() but takes a Gio.BusType instead of a Gio.DBusConnection.

Gio.DBusProxy is used in this ‘example [gdbus-wellknown-proxy]’.

New in version 2.26.

classmethod new_sync(connection, flags, info, name, object_path, interface_name, cancellable)[source]
Parameters:
Raises:

GLib.Error

Returns:

A Gio.DBusProxy or None if error is set. Free with GObject.Object.unref().

Return type:

Gio.DBusProxy

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 Gio.DBusProxyFlags.DO_NOT_LOAD_PROPERTIES flag is used.

If the Gio.DBusProxyFlags.DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the Gio.DBusProxy ::g-signal signal to handle signals from the remote object.

If both Gio.DBusProxyFlags.DO_NOT_LOAD_PROPERTIES and Gio.DBusProxyFlags.DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to return immediately without blocking.

If name is a well-known name and the Gio.DBusProxyFlags.DO_NOT_AUTO_START and Gio.DBusProxyFlags.DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren’t set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a synchronous failable constructor. See Gio.DBusProxy.new() and Gio.DBusProxy.new_finish() for the asynchronous version.

Gio.DBusProxy is used in this ‘example [gdbus-wellknown-proxy]’.

New in version 2.26.

call(method_name, parameters, flags, timeout_msec, cancellable, callback, *user_data)[source]
Parameters:

Asynchronously invokes the method_name method on self.

If method_name contains any dots, then name is split into interface and method name parts. This allows using self for invoking methods on other interfaces.

If the Gio.DBusConnection associated with self is closed then the operation will fail with Gio.IOErrorEnum.CLOSED. If cancellable is canceled, the operation will fail with Gio.IOErrorEnum.CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with Gio.IOErrorEnum.INVALID_ARGUMENT.

If the parameters GLib.Variant is floating, it is consumed. This allows convenient ‘inline’ use of g_variant_new(), e.g.:

g_dbus_proxy_call (proxy,
"TwoStrings",
g_variant_new ("(ss)",
               "Thing One",
               "Thing Two"),
G_DBUS_CALL_FLAGS_NONE,
-1,
NULL,
(GAsyncReadyCallback) two_strings_done,
&data);

If self has an expected interface (see Gio.DBusProxy :g-interface-info) and method_name is referenced by it, then the return value is checked against the return type.

This is an asynchronous method. When the operation is finished, callback will be invoked in the thread-default main context of the thread you are calling this method from. You can then call Gio.DBusProxy.call_finish() to get the result of the operation. See Gio.DBusProxy.call_sync() for the synchronous version of this method.

If callback is None then the D-Bus method call message will be sent with the Gio.DBusMessageFlags.NO_REPLY_EXPECTED flag set.

New in version 2.26.

call_finish(res)[source]
Parameters:

res (Gio.AsyncResult) – A Gio.AsyncResult obtained from the Gio.AsyncReadyCallback passed to Gio.DBusProxy.call().

Raises:

GLib.Error

Returns:

None if error is set. Otherwise a GLib.Variant tuple with return values. Free with GLib.Variant.unref().

Return type:

GLib.Variant

Finishes an operation started with Gio.DBusProxy.call().

New in version 2.26.

call_sync(method_name, parameters, flags, timeout_msec, cancellable)[source]
Parameters:
Raises:

GLib.Error

Returns:

None if error is set. Otherwise a GLib.Variant tuple with return values. Free with GLib.Variant.unref().

Return type:

GLib.Variant

Synchronously invokes the method_name method on self.

If method_name contains any dots, then name is split into interface and method name parts. This allows using self for invoking methods on other interfaces.

If the Gio.DBusConnection associated with self is disconnected then the operation will fail with Gio.IOErrorEnum.CLOSED. If cancellable is canceled, the operation will fail with Gio.IOErrorEnum.CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with Gio.IOErrorEnum.INVALID_ARGUMENT.

If the parameters GLib.Variant is floating, it is consumed. This allows convenient ‘inline’ use of g_variant_new(), e.g.:

g_dbus_proxy_call_sync (proxy,
"TwoStrings",
g_variant_new ("(ss)",
               "Thing One",
               "Thing Two"),
G_DBUS_CALL_FLAGS_NONE,
-1,
NULL,
&error);

The calling thread is blocked until a reply is received. See Gio.DBusProxy.call() for the asynchronous version of this method.

If self has an expected interface (see Gio.DBusProxy :g-interface-info) and method_name is referenced by it, then the return value is checked against the return type.

New in version 2.26.

call_with_unix_fd_list(method_name, parameters, flags, timeout_msec, fd_list, cancellable, callback, *user_data)[source]
Parameters:

Like Gio.DBusProxy.call() but also takes a Gio.UnixFDList object.

This method is only available on UNIX.

New in version 2.30.

call_with_unix_fd_list_finish(res)[source]
Parameters:

res (Gio.AsyncResult) – A Gio.AsyncResult obtained from the Gio.AsyncReadyCallback passed to Gio.DBusProxy.call_with_unix_fd_list().

Raises:

GLib.Error

Returns:

None if error is set. Otherwise a GLib.Variant tuple with return values. Free with GLib.Variant.unref().

out_fd_list:

Return location for a Gio.UnixFDList or None.

Return type:

(GLib.Variant, out_fd_list: Gio.UnixFDList)

Finishes an operation started with Gio.DBusProxy.call_with_unix_fd_list().

New in version 2.30.

call_with_unix_fd_list_sync(method_name, parameters, flags, timeout_msec, fd_list, cancellable)[source]
Parameters:
Raises:

GLib.Error

Returns:

None if error is set. Otherwise a GLib.Variant tuple with return values. Free with GLib.Variant.unref().

out_fd_list:

Return location for a Gio.UnixFDList or None.

Return type:

(GLib.Variant, out_fd_list: Gio.UnixFDList)

Like Gio.DBusProxy.call_sync() but also takes and returns Gio.UnixFDList objects.

This method is only available on UNIX.

New in version 2.30.

get_cached_property(property_name)[source]
Parameters:

property_name (str) – Property name.

Returns:

A reference to the GLib.Variant instance that holds the value for property_name or None if the value is not in the cache. The returned reference must be freed with GLib.Variant.unref().

Return type:

GLib.Variant or None

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

If self has an expected interface (see Gio.DBusProxy :g-interface-info) and property_name is referenced by it, then value is checked against the type of the property.

New in version 2.26.

get_cached_property_names()[source]
Returns:

A None-terminated array of strings or None if self has no cached properties. Free the returned array with GLib.strfreev().

Return type:

[str] or None

Gets the names of all cached properties on self.

New in version 2.26.

get_connection()[source]
Returns:

A Gio.DBusConnection owned by self. Do not free.

Return type:

Gio.DBusConnection

Gets the connection self is for.

New in version 2.26.

get_default_timeout()[source]
Returns:

Timeout to use for self.

Return type:

int

Gets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the Gio.DBusProxy.call() and Gio.DBusProxy.call_sync() functions.

See the Gio.DBusProxy :g-default-timeout property for more details.

New in version 2.26.

get_flags()[source]
Returns:

Flags from the Gio.DBusProxyFlags enumeration.

Return type:

Gio.DBusProxyFlags

Gets the flags that self was constructed with.

New in version 2.26.

get_interface_info()[source]
Returns:

A Gio.DBusInterfaceInfo or None. Do not unref the returned object, it is owned by self.

Return type:

Gio.DBusInterfaceInfo or None

Returns the Gio.DBusInterfaceInfo, if any, specifying the interface that self conforms to. See the Gio.DBusProxy :g-interface-info property for more details.

New in version 2.26.

get_interface_name()[source]
Returns:

A string owned by self. Do not free.

Return type:

str

Gets the D-Bus interface name self is for.

New in version 2.26.

get_name()[source]
Returns:

A string owned by self. Do not free.

Return type:

str or None

Gets the name that self was constructed for.

When connected to a message bus, this will usually be non-None. However, it may be None for a proxy that communicates using a peer-to-peer pattern.

New in version 2.26.

get_name_owner()[source]
Returns:

The name owner or None if no name owner exists. Free with GLib.free().

Return type:

str or None

The unique name that owns the name that self is for or None if no-one currently owns that name. You may connect to the GObject.Object ::notify signal to track changes to the Gio.DBusProxy :g-name-owner property.

New in version 2.26.

get_object_path()[source]
Returns:

A string owned by self. Do not free.

Return type:

str

Gets the object path self is for.

New in version 2.26.

set_cached_property(property_name, value)[source]
Parameters:
  • property_name (str) – Property name.

  • value (GLib.Variant or None) – Value for the property or None to remove it from the cache.

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

If value is None, then the cached value is removed from the property cache.

If self has an expected interface (see Gio.DBusProxy :g-interface-info) and property_name is referenced by it, then value is checked against the type of the property.

If the value GLib.Variant is floating, it is consumed. This allows convenient ‘inline’ use of g_variant_new(), e.g.

g_dbus_proxy_set_cached_property (proxy,
"SomeProperty",
g_variant_new ("(si)",
              "A String",
              42));

Normally you will not need to use this method since self is tracking changes using the org.freedesktop.DBus.Properties.PropertiesChanged D-Bus signal. However, for performance reasons an object may decide to not use this signal for some properties and instead use a proprietary out-of-band mechanism to transmit changes.

As a concrete example, consider an object with a property ChatroomParticipants which is an array of strings. Instead of transmitting the same (long) array every time the property changes, it is more efficient to only transmit the delta using e.g. signals ChatroomParticipantJoined(String name) and ChatroomParticipantParted(String name).

New in version 2.26.

set_default_timeout(timeout_msec)[source]
Parameters:

timeout_msec (int) – Timeout in milliseconds.

Sets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the Gio.DBusProxy.call() and Gio.DBusProxy.call_sync() functions.

See the Gio.DBusProxy :g-default-timeout property for more details.

New in version 2.26.

set_interface_info(info)[source]
Parameters:

info (Gio.DBusInterfaceInfo or None) – Minimum interface this proxy conforms to or None to unset.

Ensure that interactions with self conform to the given interface. See the Gio.DBusProxy :g-interface-info property for more details.

New in version 2.26.

do_g_properties_changed(changed_properties, invalidated_properties) virtual
Parameters:

Signal class handler for the Gio.DBusProxy ::g-properties-changed signal.

do_g_signal(sender_name, signal_name, parameters) virtual
Parameters:

Signal class handler for the Gio.DBusProxy ::g-signal signal.

Signal Details

Gio.DBusProxy.signals.g_properties_changed(d_bus_proxy, changed_properties, invalidated_properties)
Signal Name:

g-properties-changed

Flags:

RUN_LAST, MUST_COLLECT

Parameters:
  • d_bus_proxy (Gio.DBusProxy) – The object which received the signal

  • changed_properties (GLib.Variant) – A GLib.Variant containing the properties that changed (type: a{sv})

  • invalidated_properties ([str]) – A None terminated array of properties that was invalidated

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 None (either may be empty though).

If the proxy has the flag Gio.DBusProxyFlags.GET_INVALIDATED_PROPERTIES set, then invalidated_properties will always be empty.

This signal corresponds to the PropertiesChanged D-Bus signal on the org.freedesktop.DBus.Properties interface.

New in version 2.26.

Gio.DBusProxy.signals.g_signal(d_bus_proxy, sender_name, signal_name, parameters)
Signal Name:

g-signal

Flags:

RUN_LAST, DETAILED, MUST_COLLECT

Parameters:
  • d_bus_proxy (Gio.DBusProxy) – The object which received the signal

  • sender_name (str or None) – The sender of the signal or None if the connection is not a bus connection.

  • signal_name (str) – The name of the signal.

  • parameters (GLib.Variant) – A GLib.Variant tuple with parameters for the signal.

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

Since 2.72 this signal supports detailed connections. You can connect to the detailed signal g-signal::x in order to receive callbacks only when signal x is received from the remote object.

New in version 2.26.

Property Details

Gio.DBusProxy.props.g_bus_type
Name:

g-bus-type

Type:

Gio.BusType

Default Value:

Gio.BusType.NONE

Flags:

WRITABLE, CONSTRUCT_ONLY

If this property is not Gio.BusType.NONE, then Gio.DBusProxy :g-connection must be None and will be set to the Gio.DBusConnection obtained by calling Gio.bus_get() with the value of this property.

New in version 2.26.

Gio.DBusProxy.props.g_connection
Name:

g-connection

Type:

Gio.DBusConnection

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

The Gio.DBusConnection the proxy is for.

New in version 2.26.

Gio.DBusProxy.props.g_default_timeout
Name:

g-default-timeout

Type:

int

Default Value:

-1

Flags:

READABLE, WRITABLE, CONSTRUCT

The timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the Gio.DBusProxy.call() and Gio.DBusProxy.call_sync() functions.

This allows applications to set a proxy-wide timeout for all remote method invocations on the proxy. If this property is -1, the default timeout (typically 25 seconds) is used. If set to GObject.G_MAXINT, then no timeout is used.

New in version 2.26.

Gio.DBusProxy.props.g_flags
Name:

g-flags

Type:

Gio.DBusProxyFlags

Default Value:

Gio.DBusProxyFlags.NONE

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

Flags from the Gio.DBusProxyFlags enumeration.

New in version 2.26.

Gio.DBusProxy.props.g_interface_info
Name:

g-interface-info

Type:

Gio.DBusInterfaceInfo

Default Value:

None

Flags:

READABLE, WRITABLE

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 Gio.DBusInterfaceInfo is said to be the “expected interface”.

The checks performed are:

  • When completing a method call, if the type signature of the reply message isn’t what’s expected, the reply is discarded and the GLib.Error is set to Gio.IOErrorEnum.INVALID_ARGUMENT.

  • Received signals that have a type signature mismatch are dropped and a warning is logged via g_warning().

  • Properties received via the initial GetAll() call or via the ::PropertiesChanged signal (on the org.freedesktop.DBus.Properties interface) or set using Gio.DBusProxy.set_cached_property() with a type signature mismatch are ignored and a warning is logged via g_warning().

Note that these checks are never done on methods, signals and properties that are not referenced in the given Gio.DBusInterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break.

New in version 2.26.

Gio.DBusProxy.props.g_interface_name
Name:

g-interface-name

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

The D-Bus interface name the proxy is for.

New in version 2.26.

Gio.DBusProxy.props.g_name
Name:

g-name

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

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

New in version 2.26.

Gio.DBusProxy.props.g_name_owner
Name:

g-name-owner

Type:

str

Default Value:

None

Flags:

READABLE

The unique name that owns Gio.DBusProxy :g-name or None if no-one currently owns that name. You may connect to GObject.Object ::notify signal to track changes to this property.

New in version 2.26.

Gio.DBusProxy.props.g_object_path
Name:

g-object-path

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

The object path the proxy is for.

New in version 2.26.