class Gio::DBusProxy
- Gio::DBusProxy
- GObject::Object
- Reference
- Object
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.crConstructors
-
.new
Initialize a new
DBusProxy
. - .new(*, g_bus_type : Gio::BusType | Nil = nil, g_connection : Gio::DBusConnection | Nil = nil, g_default_timeout : Int32 | Nil = nil, g_flags : Gio::DBusProxyFlags | Nil = nil, g_interface_info : Gio::DBusInterfaceInfo | Nil = nil, g_interface_name : String | Nil = nil, g_name : String | Nil = nil, g_name_owner : String | Nil = nil, g_object_path : String | Nil = nil)
-
.new(connection : Gio::DBusConnection, flags : Gio::DBusProxyFlags, info : Gio::DBusInterfaceInfo | Nil, name : String | Nil, object_path : String, interface_name : String, cancellable : Gio::Cancellable | Nil, &callback : Gio::AsyncReadyCallback) : 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.
-
.new_finish(res : Gio::AsyncResult) : self
Finishes creating a #GDBusProxy.
-
.new_for_bus_finish(res : Gio::AsyncResult) : self
Finishes creating a #GDBusProxy.
-
.new_for_bus_sync(bus_type : Gio::BusType, flags : Gio::DBusProxyFlags, info : Gio::DBusInterfaceInfo | Nil, name : String, object_path : String, interface_name : String, cancellable : Gio::Cancellable | Nil) : self
Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
-
.new_sync(connection : Gio::DBusConnection, flags : Gio::DBusProxyFlags, info : Gio::DBusInterfaceInfo | Nil, name : String | Nil, object_path : String, interface_name : String, cancellable : Gio::Cancellable | Nil) : 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.
Class Method Summary
-
.g_type : UInt64
Returns the type id (GType) registered in GLib type system.
-
.new_for_bus(bus_type : Gio::BusType, flags : Gio::DBusProxyFlags, info : Gio::DBusInterfaceInfo | Nil, name : String, object_path : String, interface_name : String, cancellable : Gio::Cancellable | Nil, &callback : Gio::AsyncReadyCallback) : Nil
Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
Instance Method Summary
-
#==(other : self)
Returns
true
if this reference is the same as other. -
#cached_property(property_name : String) : GLib::Variant | Nil
Looks up the value for a property from the cache.
-
#cached_property_names : Enumerable(String) | Nil
Gets the names of all cached properties on proxy.
-
#call(method_name : String, parameters : _ | Nil, flags : Gio::DBusCallFlags, timeout_msec : Int32, cancellable : Gio::Cancellable | Nil, &callback : Gio::AsyncReadyCallback) : Nil
Asynchronously invokes the method_name method on proxy.
-
#call_finish(res : Gio::AsyncResult) : GLib::Variant
Finishes an operation started with g_dbus_proxy_call().
-
#call_sync(method_name : String, parameters : _ | Nil, flags : Gio::DBusCallFlags, timeout_msec : Int32, cancellable : Gio::Cancellable | Nil) : GLib::Variant
Synchronously invokes the method_name method on proxy.
-
#call_with_unix_fd_list(method_name : String, parameters : _ | Nil, flags : Gio::DBusCallFlags, timeout_msec : Int32, fd_list : Gio::UnixFDList | Nil, cancellable : Gio::Cancellable | Nil, &callback : Gio::AsyncReadyCallback) : Nil
Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
-
#call_with_unix_fd_list_finish(res : Gio::AsyncResult) : GLib::Variant
Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
-
#call_with_unix_fd_list_sync(method_name : String, parameters : _ | Nil, flags : Gio::DBusCallFlags, timeout_msec : Int32, fd_list : Gio::UnixFDList | Nil, cancellable : Gio::Cancellable | Nil) : GLib::Variant
Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
-
#connection : Gio::DBusConnection
Gets the connection proxy is for.
-
#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.
-
#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.
-
#flags : Gio::DBusProxyFlags
Gets the flags that proxy was constructed with.
- #g_bus_type=(value : Gio::BusType) : Gio::BusType
- #g_connection : Gio::DBusConnection | Nil
- #g_connection=(value : Gio::DBusConnection | Nil) : Gio::DBusConnection | Nil
- #g_default_timeout : Int32
- #g_default_timeout=(value : Int32) : Int32
- #g_flags : Gio::DBusProxyFlags
- #g_flags=(value : Gio::DBusProxyFlags) : Gio::DBusProxyFlags
- #g_interface_info : Gio::DBusInterfaceInfo | Nil
- #g_interface_info=(value : Gio::DBusInterfaceInfo | Nil) : Gio::DBusInterfaceInfo | Nil
- #g_interface_name : String
- #g_interface_name=(value : String) : String
-
#g_interface_name=(value : Nil) : Nil
Set
#g_interface_name
property to nil. -
#g_interface_name? : String | Nil
Same as
#g_interface_name
, but can return nil. - #g_name : String
- #g_name=(value : String) : String
-
#g_name=(value : Nil) : Nil
Set
#g_name
property to nil. -
#g_name? : String | Nil
Same as
#g_name
, but can return nil. - #g_name_owner : String
-
#g_name_owner? : String | Nil
Same as
#g_name_owner
, but can return nil. - #g_object_path : String
- #g_object_path=(value : String) : String
-
#g_object_path=(value : Nil) : Nil
Set
#g_object_path
property to nil. -
#g_object_path? : String | Nil
Same as
#g_object_path
, but can return nil. - #g_properties_changed_signal
- #g_signal_signal
-
#hash(hasher)
See
Object#hash(hasher)
-
#interface_info : Gio::DBusInterfaceInfo | Nil
Returns the #GDBusInterfaceInfo, if any, specifying the interface that proxy conforms to.
-
#interface_info=(info : Gio::DBusInterfaceInfo | Nil) : Nil
Ensure that interactions with proxy conform to the given interface.
-
#interface_name : String
Gets the D-Bus interface name proxy is for.
-
#name : String | Nil
Gets the name that proxy was constructed for.
-
#name_owner : String | Nil
The unique name that owns the name that proxy is for or
nil
if no-one currently owns that name. -
#object_path : String
Gets the object path proxy is for.
-
#set_cached_property(property_name : String, value : _ | Nil) : Nil
If value is not
nil
, sets the cached value for the property with name property_name to the value in value.
Instance methods inherited from module Gio::Initable
init(cancellable : Gio::Cancellable | Nil) : Bool
init,
newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter), cancellable : Gio::Cancellable | Nil) : GObject::Object
newv,
to_unsafe
to_unsafe
Constructor methods inherited from module Gio::Initable
cast(obj : GObject::Object) : self
cast
Class methods inherited from module Gio::Initable
cast?(obj : GObject::Object) : self | Nil
cast?,
g_type : UInt64
g_type
Instance methods inherited from module Gio::DBusInterface
info : Gio::DBusInterfaceInfo
info,
object : Gio::DBusObject | Nil
object,
object=(object : Gio::DBusObject | Nil) : Nil
object=,
to_unsafe
to_unsafe
Constructor methods inherited from module Gio::DBusInterface
cast(obj : GObject::Object) : self
cast
Class methods inherited from module Gio::DBusInterface
cast?(obj : GObject::Object) : self | Nil
cast?,
g_type : UInt64
g_type
Instance methods inherited from module Gio::AsyncInitable
init_async(io_priority : Int32, cancellable : Gio::Cancellable | Nil, &callback : Gio::AsyncReadyCallback) : Nil
init_async,
init_finish(res : Gio::AsyncResult) : Bool
init_finish,
new_finish(res : Gio::AsyncResult) : GObject::Object
new_finish,
to_unsafe
to_unsafe
Constructor methods inherited from module Gio::AsyncInitable
cast(obj : GObject::Object) : self
cast
Class methods inherited from module Gio::AsyncInitable
cast?(obj : GObject::Object) : self | Nil
cast?,
g_type : UInt64
g_type,
newv_async(object_type : UInt64, n_parameters : UInt32, parameters : GObject::Parameter, io_priority : Int32, cancellable : Gio::Cancellable | Nil, &callback : Gio::AsyncReadyCallback) : Nil
newv_async
Instance methods inherited from class GObject::Object
==(other : self)
==,
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) | Nil
data,
finalize
finalize,
freeze_notify : Nil
freeze_notify,
getv(names : Enumerable(String), values : Enumerable(_)) : Nil
getv,
hash(hasher)
hash,
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) | Nil
qdata,
ref_count : UInt32
ref_count,
run_dispose : Nil
run_dispose,
set_data(key : String, data : Pointer(Void) | Nil) : Nil
set_data,
set_property(property_name : String, value : _) : Nil
set_property,
steal_data(key : String) : Pointer(Void) | Nil
steal_data,
steal_qdata(quark : UInt32) : Pointer(Void) | Nil
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,
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
cast?(obj : GObject::Object) : self | Nil
cast?,
compat_control(what : UInt64, data : Pointer(Void) | Nil) : 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
Macros inherited from class GObject::Object
previous_vfunc(*args)
previous_vfunc,
previous_vfunc!(*args)
previous_vfunc!,
signal(signature)
signal
Constructor Detail
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].
Finishes creating a #GDBusProxy.
Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
#GDBusProxy is used in this [example][gdbus-wellknown-proxy].
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
Returns the type id (GType) registered in GLib type system.
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
Returns true
if this reference is the same as other. Invokes same?
.
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.
Gets the names of all cached properties on proxy.
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.
Finishes an operation started with g_dbus_proxy_call().
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.
Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
This method is only available on UNIX.
Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
This method is only available on UNIX.
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.
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.
Returns the #GDBusInterfaceInfo, if any, specifying the interface that proxy conforms to. See the #GDBusProxy:g-interface-info property for more details.
Ensure that interactions with proxy conform to the given interface. See the #GDBusProxy:g-interface-info property for more details.
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.
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.
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)
.