Struct gio::DBusProxy

#[repr(transparent)]
pub struct DBusProxy { /* private fields */ }

DBusProxy is a base class used for proxies to access a D-Bus interface on a remote object. A DBusProxy can be constructed for both well-known and unique names.

By default, DBusProxy 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 DBusProxyFlags 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 g-name-owner. Connect to the 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 DBusProxyFlags::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 g-name-owner tracking of DBusProxy 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 DBusProxy — use direct D-Bus method calls and signal connections.

The generic g-properties-changed and g-signal signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass DBusProxy, 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 DBusProxy instance can be used from multiple threads but note that all signals (e.g. g-signal, g-properties-changed and 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

Properties

g-bus-type

If this property is not BusType::None, then g-connection must be None and will be set to the DBusConnection obtained by calling bus_get() with the value of this property.

Writeable | Construct Only

g-connection

The DBusConnection the proxy is for.

Readable | Writeable | Construct Only

g-default-timeout

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

Readable | Writeable | Construct

g-flags

Flags from the DBusProxyFlags enumeration.

Readable | Writeable | Construct Only

g-interface-info

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 DBusProxyExt::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.

Readable | Writeable

g-interface-name

The D-Bus interface name the proxy is for.

Readable | Writeable | Construct Only

g-name

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

Readable | Writeable | Construct Only

g-name-owner

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.

Readable

g-object-path

The object path the proxy is for.

Readable | Writeable | Construct Only

Signals

g-properties-changed

Emitted when one or more D-Bus properties on proxy changes. The local cache has already been updated when this signal fires. Note that both changed_properties and invalidated_properties are guaranteed to never be None (either may be empty though).

If the proxy has the flag DBusProxyFlags::GET_INVALIDATED_PROPERTIES set, then invalidated_properties will always be empty.

This signal corresponds to the PropertiesChanged D-Bus signal on the org.freedesktop.DBus.Properties interface.

g-signal

Emitted when a signal from the remote object and interface that proxy is for, has been received.

Since 2.72 this signal supports detailed connections. You can connect to the detailed signal g-signal::x in order to receive callbacks only when signal x is received from the remote object.

Detailed

Implements

DBusProxyExt, glib::ObjectExt, AsyncInitableExt, DBusInterfaceExt, InitableExt, DBusProxyExtManual

Implementations

impl DBusProxy

pub const NONE: Option<&'static DBusProxy> = None

pub fn for_bus_sync( bus_type: BusType, flags: DBusProxyFlags, info: Option<&DBusInterfaceInfo>, name: &str, object_path: &str, interface_name: &str, cancellable: Option<&impl IsA<Cancellable>> ) -> Result<DBusProxy, Error>

Like new_sync() but takes a BusType instead of a DBusConnection.

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

bus_type

A BusType.

flags

Flags used when constructing the proxy.

info

A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or None.

name

A bus name (well-known or unique).

object_path

An object path.

interface_name

A D-Bus interface name.

cancellable

A Cancellable or None.

Returns

A DBusProxy or None if error is set. Free with g_object_unref().

pub fn new_sync( connection: &DBusConnection, flags: DBusProxyFlags, info: Option<&DBusInterfaceInfo>, name: Option<&str>, object_path: &str, interface_name: &str, cancellable: Option<&impl IsA<Cancellable>> ) -> Result<DBusProxy, Error>

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 DBusProxyFlags::DO_NOT_LOAD_PROPERTIES flag is used.

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

If both DBusProxyFlags::DO_NOT_LOAD_PROPERTIES and DBusProxyFlags::DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to return immediately without blocking.

If name is a well-known name and the DBusProxyFlags::DO_NOT_AUTO_START and DBusProxyFlags::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 new() and g_dbus_proxy_new_finish() for the asynchronous version.

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

connection

A DBusConnection.

flags

Flags used when constructing the proxy.

info

A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or None.

name

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

object_path

An object path.

interface_name

A D-Bus interface name.

cancellable

A Cancellable or None.

Returns

A DBusProxy or None if error is set. Free with g_object_unref().

pub fn new<P: FnOnce(Result<DBusProxy, Error>) + 'static>( connection: &DBusConnection, flags: DBusProxyFlags, info: Option<&DBusInterfaceInfo>, name: Option<&str>, object_path: &str, interface_name: &str, cancellable: Option<&impl IsA<Cancellable>>, callback: P )

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 DBusProxyFlags::DO_NOT_LOAD_PROPERTIES flag is used. Connect to the g-properties-changed signal to get notified about property changes.

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

If both DBusProxyFlags::DO_NOT_LOAD_PROPERTIES and DBusProxyFlags::DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to complete immediately without blocking.

If name is a well-known name and the DBusProxyFlags::DO_NOT_AUTO_START and DBusProxyFlags::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 new_sync() and for a synchronous version of this constructor.

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

connection

A DBusConnection.

flags

Flags used when constructing the proxy.

info

A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or None.

name

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

object_path

An object path.

interface_name

A D-Bus interface name.

cancellable

A Cancellable or None.

callback

Callback function to invoke when the proxy is ready.

pub fn new_future( connection: &DBusConnection, flags: DBusProxyFlags, info: Option<&DBusInterfaceInfo>, name: Option<&str>, object_path: &str, interface_name: &str ) -> Pin<Box_<dyn Future<Output = Result<DBusProxy, Error>> + 'static>>

pub fn for_bus<P: FnOnce(Result<DBusProxy, Error>) + 'static>( bus_type: BusType, flags: DBusProxyFlags, info: Option<&DBusInterfaceInfo>, name: &str, object_path: &str, interface_name: &str, cancellable: Option<&impl IsA<Cancellable>>, callback: P )

Like new() but takes a BusType instead of a DBusConnection.

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

bus_type

A BusType.

flags

Flags used when constructing the proxy.

info

A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or None.

name

A bus name (well-known or unique).

object_path

An object path.

interface_name

A D-Bus interface name.

cancellable

A Cancellable or None.

callback

Callback function to invoke when the proxy is ready.

pub fn for_bus_future( bus_type: BusType, flags: DBusProxyFlags, info: Option<&DBusInterfaceInfo>, name: &str, object_path: &str, interface_name: &str ) -> Pin<Box_<dyn Future<Output = Result<DBusProxy, Error>> + 'static>>

Trait Implementations

impl Clone for DBusProxy

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DBusProxy

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for DBusProxy

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HasParamSpec for DBusProxy

type ParamSpec = ParamSpecObject

type SetValue = DBusProxy

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, DBusProxy>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for DBusProxy

fn hash<H>(&self, state: &mut H)where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for DBusProxy

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl ParentClassIs for DBusProxy

type Parent = Object

impl<OT: ObjectType> PartialEq<OT> for DBusProxy

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for DBusProxy

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for DBusProxy

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for DBusProxy

impl IsA<AsyncInitable> for DBusProxy

impl IsA<DBusInterface> for DBusProxy

impl IsA<Initable> for DBusProxy

impl Send for DBusProxy

impl Sync for DBusProxy