class Gio::DBusProxy

Overview

#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][gdbus-example-gdbus-codegen] shows how this can easily be done using the [gdbus-codegen][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][g-main-context-push-thread-default] 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

Included Modules

Defined in:

lib/gi-crystal/src/auto/gio-2.0/d_bus_proxy.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from module Gio::Initable

init(cancellable : Gio::Cancellable?) : Bool init, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter), cancellable : Gio::Cancellable?) : GObject::Object newv, to_unsafe to_unsafe

Class methods inherited from module Gio::Initable

g_type : UInt64 g_type

Instance methods inherited from module Gio::DBusInterface

info : Gio::DBusInterfaceInfo info, object : Gio::DBusObject? object, object=(object : Gio::DBusObject?) : Nil object=, to_unsafe to_unsafe

Class methods inherited from module Gio::DBusInterface

g_type : UInt64 g_type

Instance methods inherited from module Gio::AsyncInitable

init_async(io_priority : Int32, cancellable : Gio::Cancellable?, callback : Gio::AsyncReadyCallback?, user_data : Pointer(Void)?) : Nil init_async, init_finish(res : Gio::AsyncResult) : Bool init_finish, new_finish(res : Gio::AsyncResult) : GObject::Object new_finish, to_unsafe to_unsafe

Class methods inherited from module Gio::AsyncInitable

g_type : UInt64 g_type, newv_async(object_type : UInt64, n_parameters : UInt32, parameters : GObject::Parameter, io_priority : Int32, cancellable : Gio::Cancellable?, callback : Gio::AsyncReadyCallback?, user_data : Pointer(Void)?) : Nil newv_async

Instance methods inherited from class GObject::Object

bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void)? data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void)? qdata, ref_count : UInt32 ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void)?) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void)? steal_data, steal_qdata(quark : UInt32) : Pointer(Void)? steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, cast?(obj : GObject::Object) : self? cast?, new(pointer : Pointer(Void), transfer : GICrystal::Transfer)
new new, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

compat_control(what : UInt64, data : Pointer(Void)?) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Constructor Detail

def self.new(connection : Gio::DBusConnection, flags : Gio::DBusProxyFlags, info : Gio::DBusInterfaceInfo?, name : String?, object_path : String, interface_name : String, cancellable : Gio::Cancellable?, callback : Gio::AsyncReadyCallback?, user_data : Pointer(Void)?) : Nil #

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.

If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the #GDBusProxy::g-signal signal to handle signals from the remote object.

If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to complete immediately without blocking.

If @name is a well-known name and the %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_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 g_dbus_proxy_new_finish() to get the result.

See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.

#GDBusProxy is used in this [example][gdbus-wellknown-proxy].


def self.new #

Initialize a new DBusProxy.


def self.new(*, g_bus_type : Gio::BusType? = nil, g_connection : Gio::DBusConnection? = nil, g_default_timeout : Int32? = nil, g_flags : Gio::DBusProxyFlags? = nil, g_interface_info : Gio::DBusInterfaceInfo? = nil, g_interface_name : String? = nil, g_name : String? = nil, g_name_owner : String? = nil, g_object_path : String? = nil) #

def self.new_finish(res : Gio::AsyncResult) : self #

Finishes creating a #GDBusProxy.


def self.new_for_bus_finish(res : Gio::AsyncResult) : self #

Finishes creating a #GDBusProxy.


def self.new_for_bus_sync(bus_type : Gio::BusType, flags : Gio::DBusProxyFlags, info : Gio::DBusInterfaceInfo?, name : String, object_path : String, interface_name : String, cancellable : Gio::Cancellable?) : self #

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

#GDBusProxy is used in this [example][gdbus-wellknown-proxy].


def self.new_sync(connection : Gio::DBusConnection, flags : Gio::DBusProxyFlags, info : Gio::DBusInterfaceInfo?, name : String?, object_path : String, interface_name : String, cancellable : Gio::Cancellable?) : self #

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.

If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the #GDBusProxy::g-signal signal to handle signals from the remote object.

If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to return immediately without blocking.

If @name is a well-known name and the %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_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 g_dbus_proxy_new() and g_dbus_proxy_new_finish() for the asynchronous version.

#GDBusProxy is used in this [example][gdbus-wellknown-proxy].


Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


def self.new_for_bus(bus_type : Gio::BusType, flags : Gio::DBusProxyFlags, info : Gio::DBusInterfaceInfo?, name : String, object_path : String, interface_name : String, cancellable : Gio::Cancellable?, callback : Gio::AsyncReadyCallback?, user_data : Pointer(Void)?) : Nil #

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

#GDBusProxy is used in this [example][gdbus-wellknown-proxy].


Instance Method Detail

def cached_property(property_name : String) : GLib::Variant? #

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

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


def cached_property_names : Enumerable(String)? #

Gets the names of all cached properties on @proxy.


def call(method_name : String, parameters : _?, flags : Gio::DBusCallFlags, timeout_msec : Int32, cancellable : Gio::Cancellable?, callback : Gio::AsyncReadyCallback?, user_data : Pointer(Void)?) : Nil #

Asynchronously invokes the @method_name method on @proxy.

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

If the #GDBusConnection associated with @proxy is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.

If the @parameters #GVariant 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 @proxy has an expected interface (see #GDBusProxy: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][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call g_dbus_proxy_call_finish() to get the result of the operation. See g_dbus_proxy_call_sync() for the synchronous version of this method.

If @callback is nil then the D-Bus method call message will be sent with the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.


def call_finish(res : Gio::AsyncResult) : GLib::Variant #

Finishes an operation started with g_dbus_proxy_call().


def call_sync(method_name : String, parameters : _?, flags : Gio::DBusCallFlags, timeout_msec : Int32, cancellable : Gio::Cancellable?) : GLib::Variant #

Synchronously invokes the @method_name method on @proxy.

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

If the #GDBusConnection associated with @proxy is disconnected then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.

If the @parameters #GVariant 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 g_dbus_proxy_call() for the asynchronous version of this method.

If @proxy has an expected interface (see #GDBusProxy:g-interface-info) and @method_name is referenced by it, then the return value is checked against the return type.


def call_with_unix_fd_list(method_name : String, parameters : _?, flags : Gio::DBusCallFlags, timeout_msec : Int32, fd_list : Gio::UnixFDList?, cancellable : Gio::Cancellable?, callback : Gio::AsyncReadyCallback?, user_data : Pointer(Void)?) : Nil #

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

This method is only available on UNIX.


def call_with_unix_fd_list_finish(res : Gio::AsyncResult) : GLib::Variant #

Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().


def call_with_unix_fd_list_sync(method_name : String, parameters : _?, flags : Gio::DBusCallFlags, timeout_msec : Int32, fd_list : Gio::UnixFDList?, cancellable : Gio::Cancellable?) : GLib::Variant #

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

This method is only available on UNIX.


def connection : Gio::DBusConnection #

Gets the connection @proxy is for.


def default_timeout : Int32 #

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.

See the #GDBusProxy:g-default-timeout property for more details.


def default_timeout=(timeout_msec : Int32) : Nil #

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.

See the #GDBusProxy:g-default-timeout property for more details.


def flags : Gio::DBusProxyFlags #

Gets the flags that @proxy was constructed with.


def g_bus_type=(value : Gio::BusType) : Gio::BusType #

def g_connection : Gio::DBusConnection? #

def g_connection=(value : Gio::DBusConnection?) : Gio::DBusConnection? #

def g_default_timeout : Int32 #

def g_default_timeout=(value : Int32) : Int32 #

def g_flags : Gio::DBusProxyFlags #

def g_flags=(value : Gio::DBusProxyFlags) : Gio::DBusProxyFlags #

def g_interface_info : Gio::DBusInterfaceInfo? #

def g_interface_info=(value : Gio::DBusInterfaceInfo?) : Gio::DBusInterfaceInfo? #

def g_interface_name : String #

def g_interface_name=(value : String) : String #

def g_name : String #

def g_name=(value : String) : String #

def g_name_owner : String #

def g_object_path : String #

def g_object_path=(value : String) : String #

def g_properties_changed_signal #

def g_signal_signal #

def interface_info : Gio::DBusInterfaceInfo? #

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


def interface_info=(info : Gio::DBusInterfaceInfo?) : Nil #

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


def interface_name : String #

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


def name : String? #

Gets the name that @proxy was constructed for.

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


def name_owner : String? #

The unique name that owns the name that @proxy is for or nil 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.


def object_path : String #

Gets the object path @proxy is for.


def set_cached_property(property_name : String, value : _?) : Nil #

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

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

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

If the @value #GVariant 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 @proxy 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).