DBusProxy

DBusProxy

Object Hierarchy:

Description:

public class DBusProxy : Object, AsyncInitable, DBusInterface, Initable, AsyncInitable, DBusInterface, Initable

DBusProxy is a base class used for proxies to access a D-Bus interface on a remote object.

A DBusProxy can be constructed for both well-known and unique names.

By default, DBusProxy will cache all properties (and listen to changes) of the remote object, and proxy all signals that gets emitted. This behaviour can be changed by passing suitable DBusProxyFlags 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.

If a DBusProxy is used for a well-known name, the owner of the name is tracked and can be read from g_name_owner. Connect to the 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).

The generic g_properties_changed and g_signal signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass DBusProxy, 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 DBusProxy instance can be used from multiple threads but note that all signals (e.g. g_signal, g_properties_changed and notify) are emitted in the thread-default main context of the thread where the instance was constructed.

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

Namespace: GLib

Package: gio-2.0

Content:

Properties:

public BusType g_bus_type { construct; }
If this property is not g_bus_type_none, then g_connection must be null and will be set to the DBusConnection obtained by calling @get with the value of this property.
public DBusConnection g_connection { construct; owned get; }
The DBusConnection the proxy is for.
public int g_default_timeout { construct set; get; }
The timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the call and call_sync functions.
public DBusProxyFlags g_flags { construct; get; }
Flags from the DBusProxyFlags enumeration.
public DBusInterfaceInfo g_interface_info { set; owned get; }
Ensure that interactions with this proxy conform to the given interface.
public string g_interface_name { construct; owned get; }
The D-Bus interface name the proxy is for.
public string g_name { construct; owned get; }
The well-known or unique name that the proxy is for.
public string g_name_owner { owned get; }
The unique name that owns g_name or null if no-one currently owns that name.
public string g_object_path { construct; owned get; }
The object path the proxy is for.

Static methods:

public static async DBusProxy create_for_bus (BusType bus_type, DBusProxyFlags flags, DBusInterfaceInfo? info, string name, string object_path, string interface_name, Cancellable? cancellable = null) throws IOError
Like @new but takes a BusType instead of a DBusConnection.
public static async DBusProxy @new (DBusConnection connection, DBusProxyFlags flags, DBusInterfaceInfo? info, string? name, string object_path, string interface_name, Cancellable? cancellable = null) throws IOError
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.

Creation methods:

protected DBusProxy ()
public DBusProxy.for_bus_sync (BusType bus_type, DBusProxyFlags flags, DBusInterfaceInfo? info, string name, string object_path, string interface_name, Cancellable? cancellable = null) throws Error
Like DBusProxy.sync but takes a BusType instead of a DBusConnection.
public DBusProxy.sync (DBusConnection connection, DBusProxyFlags flags, DBusInterfaceInfo? info, string? name, string object_path, string interface_name, Cancellable? cancellable = null) throws Error
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.

Methods:

public async Variant call (string method_name, Variant? parameters, DBusCallFlags flags, int timeout_msec, Cancellable? cancellable = null) throws Error
Asynchronously invokes the method_name method on this.
public Variant call_sync (string method_name, Variant? parameters, DBusCallFlags flags, int timeout_msec, Cancellable? cancellable = null) throws Error
Synchronously invokes the method_name method on this.
public async Variant call_with_unix_fd_list (string method_name, Variant? parameters, DBusCallFlags flags, int timeout_msec, UnixFDList? fd_list = null, Cancellable? cancellable = null, out UnixFDList? out_fd_list = null) throws Error
Like call but also takes a UnixFDList object.
public Variant call_with_unix_fd_list_sync (string method_name, Variant? parameters, DBusCallFlags flags, int timeout_msec, UnixFDList? fd_list = null, out UnixFDList? out_fd_list = null, Cancellable? cancellable = null) throws Error
Like call_sync but also takes and returns UnixFDList objects.
public Variant get_cached_property (string property_name)
Looks up the value for a property from the cache.
public string[] get_cached_property_names ()
Gets the names of all cached properties on this.
public weak DBusConnection get_connection ()
Gets the connection this is for.
public int get_default_timeout ()
Gets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the call and call_sync functions.
public DBusProxyFlags get_flags ()
Gets the flags that this was constructed with.
public DBusInterfaceInfo get_interface_info ()
Returns the DBusInterfaceInfo, if any, specifying the interface that this conforms to.
public unowned string get_interface_name ()
Gets the D-Bus interface name this is for.
public unowned string get_name ()
Gets the name that this was constructed for.
public string get_name_owner ()
The unique name that owns the name that this is for or null if no-one currently owns that name.
public unowned string get_object_path ()
Gets the object path this is for.
public void set_cached_property (string property_name, Variant? value)
If value is not null, sets the cached value for the property with name property_name to the value in value.
public void set_default_timeout (int timeout_msec)
Sets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the call and call_sync functions.
public void set_interface_info (DBusInterfaceInfo? info)
Ensure that interactions with this conform to the given interface.

Signals:

public virtual signal void g_properties_changed (Variant changed_properties, string[] invalidated_properties)
Emitted when one or more D-Bus properties on proxy changes.
public virtual signal void g_signal (string? sender_name, string signal_name, Variant parameters)
Emitted when a signal from the remote object and interface that proxy is for, has been received.

Inherited Members:

All known members inherited from class GLib.Object

All known members inherited from interface GLib.AsyncInitable

newv_async

init_async

All known members inherited from interface GLib.DBusInterface

get_object

set_object

All known members inherited from interface GLib.Initable

newv

init