Trait gio::prelude::DBusProxyExt

pub trait DBusProxyExt: 'static {
    // Required 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;
}

Trait containing all DBusProxy methods.

Implementors

DBusProxy

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

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 DBusConnection 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 glib::Variant is floating, it is consumed. This allows convenient ‘inline’ use of [glib::Variant::new()][crate::glib::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 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 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 glib::Variant tuple with parameters for the signal or None if not passing parameters.

flags

Flags from the DBusCallFlags enumeration.

timeout_msec

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

cancellable

A Cancellable 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.

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>

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 DBusConnection 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 glib::Variant is floating, it is consumed. This allows convenient ‘inline’ use of [glib::Variant::new()][crate::glib::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 call() for the asynchronous version of this method.

If self has an expected interface (see 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 glib::Variant tuple with parameters for the signal or None if not passing parameters.

flags

Flags from the DBusCallFlags enumeration.

timeout_msec

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

cancellable

A Cancellable or None.

Returns

None if error is set. Otherwise a glib::Variant tuple with return values. Free with g_variant_unref().

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 call() but also takes a UnixFDList object.

This method is only available on UNIX.

method_name

Name of method to invoke.

parameters

A glib::Variant tuple with parameters for the signal or None if not passing parameters.

flags

Flags from the DBusCallFlags enumeration.

timeout_msec

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

fd_list

A UnixFDList or None.

cancellable

A Cancellable 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.

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.

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 call_sync() but also takes and returns UnixFDList objects.

This method is only available on UNIX.

method_name

Name of method to invoke.

parameters

A glib::Variant tuple with parameters for the signal or None if not passing parameters.

flags

Flags from the DBusCallFlags enumeration.

timeout_msec

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

fd_list

A UnixFDList or None.

cancellable

A Cancellable or None.

Returns

None if error is set. Otherwise a glib::Variant tuple with return values. Free with g_variant_unref().

out_fd_list

Return location for a UnixFDList or None.

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 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 glib::Variant 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().

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

fn connection(&self) -> DBusConnection

Gets the connection self is for.

Returns

A DBusConnection owned by self. Do not free.

fn default_timeout(&self) -> i32

Gets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the call() and call_sync() functions.

See the g-default-timeout property for more details.

Returns

Timeout to use for self.

fn flags(&self) -> DBusProxyFlags

Gets the flags that self was constructed with.

Returns

Flags from the DBusProxyFlags enumeration.

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

Returns the DBusInterfaceInfo, if any, specifying the interface that self conforms to. See the g-interface-info property for more details.

Returns

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

fn interface_name(&self) -> GString

Gets the D-Bus interface name self is for.

Returns

A string owned by self. Do not free.

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.

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

Returns

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

fn object_path(&self) -> GString

Gets the object path self is for.

Returns

A string owned by self. Do not free.

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

If the value glib::Variant is floating, it is consumed. This allows convenient ‘inline’ use of [glib::Variant::new()][crate::glib::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.

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 call() and call_sync() functions.

See the g-default-timeout property for more details.

timeout_msec

Timeout in milliseconds.

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

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

info

Minimum interface this proxy conforms to or None to unset.

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

The DBusConnection the proxy is for.

fn g_default_timeout(&self) -> i32

The timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the call() and 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.

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 call() and 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.

fn g_flags(&self) -> DBusProxyFlags

Flags from the DBusProxyFlags enumeration.

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 DBusInterfaceInfo 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 glib::Error 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 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 DBusInterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break.

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 DBusInterfaceInfo 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 glib::Error 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 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 DBusInterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break.

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

The D-Bus interface name the proxy is for.

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

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

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

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

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

The object path the proxy is for.

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

Implementors

impl<O: IsA<DBusProxy>> DBusProxyExt for O