Struct gio::DBusMethodInvocation

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

Instances of the DBusMethodInvocation 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 DBusMethodInvocation object is to receive it as an argument to the handle_method_call() function in a GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().

Implements

glib::ObjectExt

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 glib::Error 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 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 glib::Error 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 glib::Error 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 glib::Error.

impl DBusMethodInvocation

pub fn connection(&self) -> DBusConnection

Gets the DBusConnection the method was invoked on.

Returns

A DBusConnection. 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 DBusMessage 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 glib::Variant 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

DBusMessage. 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 property_info() and GDBusInterfaceVTable for more information.

Returns

A DBusMethodInfo 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 glib::Variant 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 DBusPropertyInfo 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 glib::Variant 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 return_value() but also takes a UnixFDList.

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 glib::Variant tuple with out parameters for the method or None if not passing any parameters.

fd_list

A UnixFDList or None.

Trait Implementations

impl Clone for DBusMethodInvocation

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 DBusMethodInvocation

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

Formats the value using the given formatter.

impl Display for DBusMethodInvocation

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

Formats the value using the given formatter.

impl Hash for DBusMethodInvocation

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 DBusMethodInvocation

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 DBusMethodInvocation

type Parent = Object

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

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 DBusMethodInvocation

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 DBusMethodInvocation

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for DBusMethodInvocation