Trait gio::prelude::DBusProxyExt

source · 
pub trait DBusProxyExt: IsA<DBusProxy> + Sealed + 'static {

Show 32 methods    // Provided methods
    fn call<P: FnOnce(Result<Variant, Error>) + 'static>(
        &self,
        method_name: &str,
        parameters: Option<&Variant>,
        flags: DBusCallFlags,
        timeout_msec: i32,
        cancellable: Option<&impl IsA<Cancellable>>,
        callback: P,
    ) { ... }
    fn call_future(
        &self,
        method_name: &str,
        parameters: Option<&Variant>,
        flags: DBusCallFlags,
        timeout_msec: i32,
    ) -> Pin<Box_<dyn Future<Output = Result<Variant, Error>> + 'static>> { ... }
    fn call_sync(
        &self,
        method_name: &str,
        parameters: Option<&Variant>,
        flags: DBusCallFlags,
        timeout_msec: i32,
        cancellable: Option<&impl IsA<Cancellable>>,
    ) -> Result<Variant, Error> { ... }
    fn call_with_unix_fd_list<P: FnOnce(Result<(Variant, UnixFDList), Error>) + 'static>(
        &self,
        method_name: &str,
        parameters: Option<&Variant>,
        flags: DBusCallFlags,
        timeout_msec: i32,
        fd_list: Option<&impl IsA<UnixFDList>>,
        cancellable: Option<&impl IsA<Cancellable>>,
        callback: P,
    ) { ... }
    fn call_with_unix_fd_list_future(
        &self,
        method_name: &str,
        parameters: Option<&Variant>,
        flags: DBusCallFlags,
        timeout_msec: i32,
        fd_list: Option<&(impl IsA<UnixFDList> + Clone + 'static)>,
    ) -> Pin<Box_<dyn Future<Output = Result<(Variant, UnixFDList), Error>> + 'static>> { ... }
    fn call_with_unix_fd_list_sync(
        &self,
        method_name: &str,
        parameters: Option<&Variant>,
        flags: DBusCallFlags,
        timeout_msec: i32,
        fd_list: Option<&impl IsA<UnixFDList>>,
        cancellable: Option<&impl IsA<Cancellable>>,
    ) -> Result<(Variant, UnixFDList), Error> { ... }
    fn cached_property(&self, property_name: &str) -> Option<Variant> { ... }
    fn cached_property_names(&self) -> Vec<GString> { ... }
    fn connection(&self) -> DBusConnection { ... }
    fn default_timeout(&self) -> i32 { ... }
    fn flags(&self) -> DBusProxyFlags { ... }
    fn interface_info(&self) -> Option<DBusInterfaceInfo> { ... }
    fn interface_name(&self) -> GString { ... }
    fn name(&self) -> Option<GString> { ... }
    fn name_owner(&self) -> Option<GString> { ... }
    fn object_path(&self) -> GString { ... }
    fn set_cached_property(&self, property_name: &str, value: Option<&Variant>) { ... }
    fn set_default_timeout(&self, timeout_msec: i32) { ... }
    fn set_interface_info(&self, info: Option<&DBusInterfaceInfo>) { ... }
    fn g_connection(&self) -> Option<DBusConnection> { ... }
    fn g_default_timeout(&self) -> i32 { ... }
    fn set_g_default_timeout(&self, g_default_timeout: i32) { ... }
    fn g_flags(&self) -> DBusProxyFlags { ... }
    fn g_interface_info(&self) -> Option<DBusInterfaceInfo> { ... }
    fn set_g_interface_info(&self, g_interface_info: Option<&DBusInterfaceInfo>) { ... }
    fn g_interface_name(&self) -> Option<GString> { ... }
    fn g_name(&self) -> Option<GString> { ... }
    fn g_name_owner(&self) -> Option<GString> { ... }
    fn g_object_path(&self) -> Option<GString> { ... }
    fn connect_g_default_timeout_notify<F: Fn(&Self) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId { ... }
    fn connect_g_interface_info_notify<F: Fn(&Self) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId { ... }
    fn connect_g_name_owner_notify<F: Fn(&Self) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId { ... }

}
Expand description

Trait containing all DBusProxy methods.

§Implementors

DBusProxy

Provided Methods§

source

fn call<P: FnOnce(Result<Variant, Error>) + 'static>( &self, method_name: &str, parameters: Option<&Variant>, flags: DBusCallFlags, timeout_msec: i32, cancellable: Option<&impl IsA<Cancellable>>, callback: P, )

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 #GDBusConnection associated with @self is closed then the operation will fail with IOErrorEnum::Closed. If @cancellable is canceled, the operation will fail with IOErrorEnum::Cancelled. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with IOErrorEnum::InvalidArgument.

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

⚠️ The following code is in C ⚠️

 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 #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 None then the D-Bus method call message will be sent with the DBusMessageFlags::NO_REPLY_EXPECTED flag set.

§method_name

Name of method to invoke.

§parameters

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

§flags

Flags from the #GDBusCallFlags enumeration.

§timeout_msec

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

§cancellable

A #GCancellable or None.

§callback

A #GAsyncReadyCallback to call when the request is satisfied or None if you don’t care about the result of the method invocation.

source

fn call_future( &self, method_name: &str, parameters: Option<&Variant>, flags: DBusCallFlags, timeout_msec: i32, ) -> Pin<Box_<dyn Future<Output = Result<Variant, Error>> + 'static>>

source

fn call_sync( &self, method_name: &str, parameters: Option<&Variant>, flags: DBusCallFlags, timeout_msec: i32, cancellable: Option<&impl IsA<Cancellable>>, ) -> Result<Variant, Error>

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 #GDBusConnection associated with @self is disconnected then the operation will fail with IOErrorEnum::Closed. If @cancellable is canceled, the operation will fail with IOErrorEnum::Cancelled. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with IOErrorEnum::InvalidArgument.

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

⚠️ The following code is in C ⚠️

 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 @self 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.

§method_name

Name of method to invoke.

§parameters

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

§flags

Flags from the #GDBusCallFlags enumeration.

§timeout_msec

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

§cancellable

A #GCancellable or None.

§Returns

None if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().

source

fn call_with_unix_fd_list<P: FnOnce(Result<(Variant, UnixFDList), Error>) + 'static>( &self, method_name: &str, parameters: Option<&Variant>, flags: DBusCallFlags, timeout_msec: i32, fd_list: Option<&impl IsA<UnixFDList>>, cancellable: Option<&impl IsA<Cancellable>>, callback: P, )

Available on Unix only.

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

This method is only available on UNIX.

§method_name

Name of method to invoke.

§parameters

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

§flags

Flags from the #GDBusCallFlags enumeration.

§timeout_msec

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

§fd_list

A #GUnixFDList or None.

§cancellable

A #GCancellable or None.

§callback

A #GAsyncReadyCallback to call when the request is satisfied or None if you don’t care about the result of the method invocation.

source

fn call_with_unix_fd_list_future( &self, method_name: &str, parameters: Option<&Variant>, flags: DBusCallFlags, timeout_msec: i32, fd_list: Option<&(impl IsA<UnixFDList> + Clone + 'static)>, ) -> Pin<Box_<dyn Future<Output = Result<(Variant, UnixFDList), Error>> + 'static>>

Available on Unix only.
source

fn call_with_unix_fd_list_sync( &self, method_name: &str, parameters: Option<&Variant>, flags: DBusCallFlags, timeout_msec: i32, fd_list: Option<&impl IsA<UnixFDList>>, cancellable: Option<&impl IsA<Cancellable>>, ) -> Result<(Variant, UnixFDList), Error>

Available on Unix only.

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

This method is only available on UNIX.

§method_name

Name of method to invoke.

§parameters

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

§flags

Flags from the #GDBusCallFlags enumeration.

§timeout_msec

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

§fd_list

A #GUnixFDList or None.

§cancellable

A #GCancellable or None.

§Returns

None if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().

§out_fd_list

Return location for a #GUnixFDList or None.

source

fn cached_property(&self, property_name: &str) -> Option<Variant>

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

If @self 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.

§property_name

Property name.

§Returns

A reference to the #GVariant 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 g_variant_unref().

source

fn cached_property_names(&self) -> Vec<GString>

Gets the names of all cached properties on @self.

§Returns

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

source

fn connection(&self) -> DBusConnection

Gets the connection @self is for.

§Returns

A #GDBusConnection owned by @self. Do not free.

source

fn default_timeout(&self) -> i32

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.

§Returns

Timeout to use for @self.

source

fn flags(&self) -> DBusProxyFlags

Gets the flags that @self was constructed with.

§Returns

Flags from the #GDBusProxyFlags enumeration.

source

fn interface_info(&self) -> Option<DBusInterfaceInfo>

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

§Returns

A #GDBusInterfaceInfo or None. Do not unref the returned object, it is owned by @self.

source

fn interface_name(&self) -> GString

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

§Returns

A string owned by @self. Do not free.

source

fn name(&self) -> Option<GString>

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.

§Returns

A string owned by @self. Do not free.

source

fn name_owner(&self) -> Option<GString>

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::notify signal to track changes to the #GDBusProxy:g-name-owner property.

§Returns

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

source

fn object_path(&self) -> GString

Gets the object path @self is for.

§Returns

A string owned by @self. Do not free.

source

fn set_cached_property(&self, property_name: &str, value: Option<&Variant>)

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 #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.

⚠️ The following code is in C ⚠️

 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).

§property_name

Property name.

§value

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

source

fn set_default_timeout(&self, timeout_msec: i32)

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.

§timeout_msec

Timeout in milliseconds.

source

fn set_interface_info(&self, info: Option<&DBusInterfaceInfo>)

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

§info

Minimum interface this proxy conforms to or None to unset.

source

fn g_connection(&self) -> Option<DBusConnection>

The #GDBusConnection the proxy is for.

source

fn g_default_timeout(&self) -> i32

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.

source

fn set_g_default_timeout(&self, g_default_timeout: i32)

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.

source

fn g_flags(&self) -> DBusProxyFlags

Flags from the #GDBusProxyFlags enumeration.

source

fn g_interface_info(&self) -> Option<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 #GDBusInterfaceInfo 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 IOErrorEnum::InvalidArgument.

  • 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 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 #GDBusInterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break.

source

fn set_g_interface_info(&self, g_interface_info: Option<&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 #GDBusInterfaceInfo 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 IOErrorEnum::InvalidArgument.

  • 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 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 #GDBusInterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break.

source

fn g_interface_name(&self) -> Option<GString>

The D-Bus interface name the proxy is for.

source

fn g_name(&self) -> Option<GString>

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

source

fn g_name_owner(&self) -> Option<GString>

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

source

fn g_object_path(&self) -> Option<GString>

The object path the proxy is for.

source

fn connect_g_default_timeout_notify<F: Fn(&Self) + Send + Sync + 'static>( &self, f: F, ) -> SignalHandlerId

source

fn connect_g_interface_info_notify<F: Fn(&Self) + Send + Sync + 'static>( &self, f: F, ) -> SignalHandlerId

source

fn connect_g_name_owner_notify<F: Fn(&Self) + Send + Sync + 'static>( &self, f: F, ) -> SignalHandlerId

Object Safety§

This trait is not object safe.

Implementors§