Class: Gio::DBusProxy

Inherits:
Object
  • Object
show all
Defined in:
(unknown)

Overview

Class structure for GDBus::Proxy.

Instance Method Summary collapse

Instance Method Details

#cached_property_names ⇒ Array<String>

Gets the names of all cached properties on proxy.

Returns:

  • (Array<String>) —

    A nil-terminated array of strings or nil if proxy has no cached properties. Free the returned array with g_strfreev().

#call(method_name, parameters, flags, timeout_msec, cancellable, callback, user_data) ⇒ 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 GDBus::Connection 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 GDBus::Proxy: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. care about the result of the method invocation.

Parameters:

  • method_name (String) —

    Name of method to invoke.

  • parameters (GLib::Variant) —

    A #GVariant tuple with parameters for the signal or nil if not passing parameters.

  • flags (Gio::DBusCallFlags) —

    Flags from the GDBus::CallFlags enumeration.

  • timeout_msec (Integer) —

    The timeout in milliseconds (with %G_MAXINT meaning “infinite”) or -1 to use the proxy default timeout.

  • cancellable (Gio::Cancellable) —

    A #GCancellable or nil.

  • callback (Gio::AsyncReadyCallback) —

    A GAsync::ReadyCallback to call when the request is satisfied or nil if you don’t

  • user_data (GObject) —

    The data to pass to callback.

Returns:

  • (nil)

#call_finish(res) ⇒ GLib::Variant

Finishes an operation started with g_dbus_proxy_call(). return values. Free with g_variant_unref().

Parameters:

  • res (Gio::AsyncResult) —

    A GAsync::Result obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().

Returns:

  • (GLib::Variant) —

    nil if error is set. Otherwise a #GVariant tuple with

#call_sync(method_name, parameters, flags, timeout_msec, 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 GDBus::Connection 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 GDBus::Proxy:g-interface-info) and method_name is referenced by it, then the return value is checked against the return type. return values. Free with g_variant_unref().

Parameters:

  • method_name (String) —

    Name of method to invoke.

  • parameters (GLib::Variant) —

    A #GVariant tuple with parameters for the signal or nil if not passing parameters.

  • flags (Gio::DBusCallFlags) —

    Flags from the GDBus::CallFlags enumeration.

  • timeout_msec (Integer) —

    The timeout in milliseconds (with %G_MAXINT meaning “infinite”) or -1 to use the proxy default timeout.

  • cancellable (Gio::Cancellable) —

    A #GCancellable or nil.

Returns:

  • (GLib::Variant) —

    nil if error is set. Otherwise a #GVariant tuple with

#call_with_unix_fd_list(method_name, parameters, flags, timeout_msec, fd_list, cancellable, callback, user_data) ⇒ nil

Like g_dbus_proxy_call() but also takes a GUnix::FDList object.

This method is only available on UNIX. care about the result of the method invocation.

Parameters:

  • method_name (String) —

    Name of method to invoke.

  • parameters (GLib::Variant) —

    A #GVariant tuple with parameters for the signal or nil if not passing parameters.

  • flags (Gio::DBusCallFlags) —

    Flags from the GDBus::CallFlags enumeration.

  • timeout_msec (Integer) —

    The timeout in milliseconds (with %G_MAXINT meaning “infinite”) or -1 to use the proxy default timeout.

  • fd_list (Gio::UnixFDList) —

    A GUnix::FDList or nil.

  • cancellable (Gio::Cancellable) —

    A #GCancellable or nil.

  • callback (Gio::AsyncReadyCallback) —

    A GAsync::ReadyCallback to call when the request is satisfied or nil if you don’t

  • user_data (GObject) —

    The data to pass to callback.

Returns:

  • (nil)

#call_with_unix_fd_list_finish(out_fd_list, res) ⇒ GLib::Variant

Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list(). return values. Free with g_variant_unref().

Parameters:

  • out_fd_list (Gio::UnixFDList) —

    Return location for a GUnix::FDList or nil.

  • res (Gio::AsyncResult) —

    A GAsync::Result obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().

Returns:

  • (GLib::Variant) —

    nil if error is set. Otherwise a #GVariant tuple with

#call_with_unix_fd_list_sync(method_name, parameters, flags, timeout_msec, fd_list, out_fd_list, cancellable) ⇒ GLib::Variant

Like g_dbus_proxy_call_sync() but also takes and returns GUnix::FDList objects.

This method is only available on UNIX. return values. Free with g_variant_unref().

Parameters:

  • method_name (String) —

    Name of method to invoke.

  • parameters (GLib::Variant) —

    A #GVariant tuple with parameters for the signal or nil if not passing parameters.

  • flags (Gio::DBusCallFlags) —

    Flags from the GDBus::CallFlags enumeration.

  • timeout_msec (Integer) —

    The timeout in milliseconds (with %G_MAXINT meaning “infinite”) or -1 to use the proxy default timeout.

  • fd_list (Gio::UnixFDList) —

    A GUnix::FDList or nil.

  • out_fd_list (Gio::UnixFDList) —

    Return location for a GUnix::FDList or nil.

  • cancellable (Gio::Cancellable) —

    A #GCancellable or nil.

Returns:

  • (GLib::Variant) —

    nil if error is set. Otherwise a #GVariant tuple with

#connection ⇒ Gio::DBusConnection

Gets the connection proxy is for.

Returns:

#default_timeout ⇒ Integer

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 GDBus::Proxy:g-default-timeout property for more details.

Returns:

  • (Integer) —

    Timeout to use for proxy.

#default_timeout=(timeout_msec) ⇒ 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 GDBus::Proxy:g-default-timeout property for more details.

Parameters:

  • timeout_msec (Integer) —

    Timeout in milliseconds.

Returns:

  • (nil)

#flags ⇒ Gio::DBusProxyFlags

Gets the flags that proxy was constructed with.

Returns:

#g_bus_type=(g_bus_type) ⇒ Gio::BusType

If this property is not %G_BUS_TYPE_NONE, then GDBus::Proxy:g-connection must be nil and will be set to the GDBus::Connection obtained by calling g_bus_get() with the value of this property.

Parameters:

Returns:

#g_connection ⇒ Gio::DBusConnection

The GDBus::Connection the proxy is for.

Returns:

#g_connection=(g_connection) ⇒ Gio::DBusConnection

The GDBus::Connection the proxy is for.

Parameters:

Returns:

#g_default_timeout ⇒ Integer

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.

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 %G_MAXINT, then no timeout is used.

Returns:

  • (Integer) —

    g-default-timeout

#g_default_timeout=(g_default_timeout) ⇒ Integer

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.

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 %G_MAXINT, then no timeout is used.

Parameters:

  • g_default_timeout (Integer)

Returns:

  • (Integer) —

    g-default-timeout

  • (Integer) —

    g-default-timeout

#g_flags ⇒ Gio::DBusProxyFlags

Flags from the GDBus::ProxyFlags enumeration.

Returns:

#g_flags=(g_flags) ⇒ Gio::DBusProxyFlags

Flags from the GDBus::ProxyFlags enumeration.

Parameters:

Returns:

#g_interface_info ⇒ Gio::DBusInterfaceInfo

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 GDBus::InterfaceInfo 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 #GError is set to %G_IO_ERROR_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](dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) interface) or set using g_dbus_proxy_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 GDBus::InterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break.

Returns:

  • (Gio::DBusInterfaceInfo) —

    g-interface-info

#g_interface_info=(g_interface_info) ⇒ Gio::DBusInterfaceInfo

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 GDBus::InterfaceInfo 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 #GError is set to %G_IO_ERROR_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](dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) interface) or set using g_dbus_proxy_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 GDBus::InterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break.

Parameters:

  • g_interface_info (Gio::DBusInterfaceInfo)

Returns:

  • (Gio::DBusInterfaceInfo) —

    g-interface-info

  • (Gio::DBusInterfaceInfo) —

    g-interface-info

#g_interface_name ⇒ String

The D-Bus interface name the proxy is for.

Returns:

  • (String) —

    g-interface-name

#g_interface_name=(g_interface_name) ⇒ String

The D-Bus interface name the proxy is for.

Parameters:

  • g_interface_name (String)

Returns:

  • (String) —

    g-interface-name

  • (String) —

    g-interface-name

#g_name ⇒ String

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

Returns:

  • (String) —

    g-name

#g_name=(g_name) ⇒ String

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

Parameters:

  • g_name (String)

Returns:

  • (String) —

    g-name

  • (String) —

    g-name

#g_name_owner ⇒ String

The unique name that owns GDBus::Proxy:g-name or nil if no-one currently owns that name. You may connect to #GObject::notify signal to track changes to this property.

Returns:

  • (String) —

    g-name-owner

#g_name_owner=(g_name_owner) ⇒ String

The unique name that owns GDBus::Proxy:g-name or nil if no-one currently owns that name. You may connect to #GObject::notify signal to track changes to this property.

Parameters:

  • g_name_owner (String)

Returns:

  • (String) —

    g-name-owner

  • (String) —

    g-name-owner

#g_object_path ⇒ String

The object path the proxy is for.

Returns:

  • (String) —

    g-object-path

#g_object_path=(g_object_path) ⇒ String

The object path the proxy is for.

Parameters:

  • g_object_path (String)

Returns:

  • (String) —

    g-object-path

  • (String) —

    g-object-path

#get_cached_property(property_name) ⇒ 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 GDBus::Proxy:g-interface-info) and property_name is referenced by it, then value is checked against the type of the property.

Parameters:

  • property_name (String) —

    Property name.

Returns:

  • (GLib::Variant) —

    A reference to the #GVariant instance that holds the value for property_name or nil if the value is not in the cache. The returned reference must be freed with g_variant_unref().

#interface_info ⇒ Gio::DBusInterfaceInfo

Returns the GDBus::InterfaceInfo, if any, specifying the interface that proxy conforms to. See the GDBus::Proxy:g-interface-info property for more details.

Returns:

  • (Gio::DBusInterfaceInfo) —

    A GDBus::InterfaceInfo or nil. Do not unref the returned object, it is owned by proxy.

#interface_info=(info) ⇒ nil

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

Parameters:

  • info (Gio::DBusInterfaceInfo) —

    Minimum interface this proxy conforms to or nil to unset.

Returns:

  • (nil)

#interface_name ⇒ String

Gets the D-Bus interface name proxy is for.

Returns:

  • (String) —

    A string owned by proxy. Do not free.

#name ⇒ String

Gets the name that proxy was constructed for.

Returns:

  • (String) —

    A string owned by proxy. Do not free.

#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 GDBus::Proxy:g-name-owner property.

Returns:

  • (String) —

    The name owner or nil if no name owner exists. Free with g_free().

#new_finish(res) ⇒ Gio::DBusProxy

Finishes creating a GDBus::Proxy.

Parameters:

  • res (Gio::AsyncResult) —

    A GAsync::Result obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().

Returns:

  • (Gio::DBusProxy) —

    A GDBus::Proxy or nil if error is set. Free with g_object_unref().

#new_for_bus_finish(res) ⇒ Gio::DBusProxy

Finishes creating a GDBus::Proxy.

Parameters:

  • res (Gio::AsyncResult) —

    A GAsync::Result obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().

Returns:

  • (Gio::DBusProxy) —

    A GDBus::Proxy or nil if error is set. Free with g_object_unref().

#new_for_bus_sync(bus_type, flags, info, name, object_path, interface_name, cancellable) ⇒ Gio::DBusProxy

Like g_dbus_proxy_new_sync() but takes a GBus::Type instead of a #GDBusConnection.

GDBus::Proxy is used in this [example].

Parameters:

  • bus_type (Gio::BusType) —

    A GBus::Type.

  • flags (Gio::DBusProxyFlags) —

    Flags used when constructing the proxy.

  • info (Gio::DBusInterfaceInfo) —

    A GDBus::InterfaceInfo specifying the minimal interface that proxy conforms to or nil.

  • name (String) —

    A bus name (well-known or unique).

  • object_path (String) —

    An object path.

  • interface_name (String) —

    A D-Bus interface name.

  • cancellable (Gio::Cancellable) —

    A #GCancellable or nil.

Returns:

  • (Gio::DBusProxy) —

    A GDBus::Proxy or nil if error is set. Free with g_object_unref().

#new_sync(connection, flags, info, name, object_path, interface_name, cancellable) ⇒ 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 %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 GDBus::Proxy::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.

GDBus::Proxy is used in this [example].

Parameters:

  • connection (Gio::DBusConnection) —

    A GDBus::Connection.

  • flags (Gio::DBusProxyFlags) —

    Flags used when constructing the proxy.

  • info (Gio::DBusInterfaceInfo) —

    A GDBus::InterfaceInfo specifying the minimal interface that proxy conforms to or nil.

  • name (String) —

    A bus name (well-known or unique) or nil if connection is not a message bus connection.

  • object_path (String) —

    An object path.

  • interface_name (String) —

    A D-Bus interface name.

  • cancellable (Gio::Cancellable) —

    A #GCancellable or nil.

Returns:

  • (Gio::DBusProxy) —

    A GDBus::Proxy or nil if error is set. Free with g_object_unref().

#object_path ⇒ String

Gets the object path proxy is for.

Returns:

  • (String) —

    A string owned by proxy. Do not free.

#set_cached_property(property_name, 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 GDBus::Proxy: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)`.

Parameters:

  • property_name (String) —

    Property name.

  • value (GLib::Variant) —

    Value for the property or nil to remove it from the cache.

Returns:

  • (nil)