Struct DBusMethodInvocation

pub struct DBusMethodInvocation { /* private fields */ }

Instances of the GDBusMethodInvocation class are used when handling D-Bus method calls. It provides a way to asynchronously return results and errors.

The normal way to obtain a GDBusMethodInvocation object is to receive it as an argument to the handle_method_call() function in a [type@Gio.DBusInterfaceVTable] that was passed to DBusConnection::register_object().

Implements

[trait@glib::ObjectExt]

GLib type: GObject with reference counted clone semantics.

Implementations

impl DBusMethodInvocation

pub fn return_error<T: ErrorDomain>(&self, error: T, message: &str)

Finishes handling a D-Bus method call by returning an error.

See g_dbus_error_encode_gerror() for details about what error name will be returned on the wire. In a nutshell, if the given error is registered using g_dbus_error_register_error() the name given during registration is used. Otherwise, a name of the form org.gtk.GDBus.UnmappedGError.Quark... is used. This provides transparent mapping of #GError between applications using GDBus.

If you are writing an application intended to be portable, always register errors with g_dbus_error_register_error() or use g_dbus_method_invocation_return_dbus_error().

This method will take ownership of @self. See #GDBusInterfaceVTable for more information about the ownership of @self.

Since 2.48, if the method call requested for a reply not to be sent then this call will free @self but otherwise do nothing (as per the recommendations of the D-Bus specification).

domain

A #GQuark for the #GError error domain.

code

The error code.

format

printf()-style format.

pub fn return_gerror(&self, error: Error)

Like g_dbus_method_invocation_return_error() but takes a #GError instead of the error domain, error code and message.

This method will take ownership of @self. See #GDBusInterfaceVTable for more information about the ownership of @self.

error

A #GError.

impl DBusMethodInvocation

pub fn connection(&self) -> DBusConnection

Gets the #GDBusConnection the method was invoked on.

Returns

A #GDBusConnection. Do not free, it is owned by @self.

pub fn interface_name(&self) -> GString

Gets the name of the D-Bus interface the method was invoked on.

If this method call is a property Get, Set or GetAll call that has been redirected to the method call handler then “org.freedesktop.DBus.Properties” will be returned. See #GDBusInterfaceVTable for more information.

Returns

A string. Do not free, it is owned by @self.

pub fn message(&self) -> DBusMessage

Gets the #GDBusMessage for the method invocation. This is useful if you need to use low-level protocol features, such as UNIX file descriptor passing, that cannot be properly expressed in the #GVariant API.

See this [server][gdbus-server] and [client][gdbus-unix-fd-client] for an example of how to use this low-level API to send and receive UNIX file descriptors.

Returns

#GDBusMessage. Do not free, it is owned by @self.

pub fn method_info(&self) -> Option<DBusMethodInfo>

Gets information about the method call, if any.

If this method invocation is a property Get, Set or GetAll call that has been redirected to the method call handler then None will be returned. See g_dbus_method_invocation_get_property_info() and #GDBusInterfaceVTable for more information.

Returns

A #GDBusMethodInfo or None. Do not free, it is owned by @self.

pub fn method_name(&self) -> GString

Gets the name of the method that was invoked.

Returns

A string. Do not free, it is owned by @self.

pub fn object_path(&self) -> GString

Gets the object path the method was invoked on.

Returns

A string. Do not free, it is owned by @self.

pub fn parameters(&self) -> Variant

Gets the parameters of the method invocation. If there are no input parameters then this will return a GVariant with 0 children rather than NULL.

Returns

A #GVariant tuple. Do not unref this because it is owned by @self.

pub fn property_info(&self) -> Option<DBusPropertyInfo>

Gets information about the property that this method call is for, if any.

This will only be set in the case of an invocation in response to a property Get or Set call that has been directed to the method call handler for an object on account of its property_get() or property_set() vtable pointers being unset.

See #GDBusInterfaceVTable for more information.

If the call was GetAll, None will be returned.

Returns

a #GDBusPropertyInfo or None

pub fn sender(&self) -> GString

Gets the bus name that invoked the method.

Returns

A string. Do not free, it is owned by @self.

pub fn return_dbus_error(self, error_name: &str, error_message: &str)

Finishes handling a D-Bus method call by returning an error.

This method will take ownership of @self. See #GDBusInterfaceVTable for more information about the ownership of @self.

error_name

A valid D-Bus error name.

error_message

A valid D-Bus error message.

pub fn return_value(self, parameters: Option<&Variant>)

Finishes handling a D-Bus method call by returning @parameters. If the @parameters GVariant is floating, it is consumed.

It is an error if @parameters is not of the right format: it must be a tuple containing the out-parameters of the D-Bus method. Even if the method has a single out-parameter, it must be contained in a tuple. If the method has no out-parameters, @parameters may be None or an empty tuple.

⚠️ The following code is in C ⚠️

GDBusMethodInvocation *invocation = some_invocation;
g_autofree gchar *result_string = NULL;
g_autoptr (GError) error = NULL;

result_string = calculate_result (&error);

if (error != NULL)
  g_dbus_method_invocation_return_gerror (invocation, error);
else
  g_dbus_method_invocation_return_value (invocation,
                                         g_variant_new ("(s)", result_string));

// Do not free @self here; returning a value does that

This method will take ownership of @self. See #GDBusInterfaceVTable for more information about the ownership of @self.

Since 2.48, if the method call requested for a reply not to be sent then this call will sink @parameters and free @self, but otherwise do nothing (as per the recommendations of the D-Bus specification).

parameters

A #GVariant tuple with out parameters for the method or None if not passing any parameters.

pub fn return_value_with_unix_fd_list( self, parameters: Option<&Variant>, fd_list: Option<&impl IsA<UnixFDList>>, )

Available on Unix only.

Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.

This method is only available on UNIX.

This method will take ownership of @self. See #GDBusInterfaceVTable for more information about the ownership of @self.

parameters

A #GVariant tuple with out parameters for the method or None if not passing any parameters.

fd_list

A #GUnixFDList or None.

Trait Implementations

impl Clone for DBusMethodInvocation

fn clone(&self) -> Self

Makes a clone of this shared reference.

This increments the strong reference count of the object. Dropping the object will decrement it again.

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

Performs copy-assignment from source.

impl Debug for DBusMethodInvocation

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

Formats the value using the given formatter.

impl HasParamSpec for DBusMethodInvocation

type ParamSpec = ParamSpecObject

type SetValue = DBusMethodInvocation

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

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

fn param_spec_builder() -> Self::BuilderFn

impl Hash for DBusMethodInvocation

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

where H: Hasher,

Hashes the memory address of this object.

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 DBusMethodInvocation

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

Comparison for two GObjects.

Compares the memory addresses of the provided objects.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl ParentClassIs for DBusMethodInvocation

type Parent = Object

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

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

Equality for two GObjects.

Two GObjects are equal if their memory addresses are equal.

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

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

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

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

Partial comparison for two GObjects.

Compares the memory addresses of the provided objects.

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl StaticType for DBusMethodInvocation

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for DBusMethodInvocation