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.

pub fn return_result(self, result: Result<Option<Variant>, Error>)

Return a result for this invocation.

If Ok return the contained value with [return_value]. If the return value is not a tuple, automatically convert it to a one-element tuple, as DBus return values must be tuples.

If Err return the contained error with [return_gerror].

pub fn return_future_local<F>(self, f: F) -> JoinHandle<()>

where F: Future<Output = Result<Option<Variant>, Error>> + 'static,

Return an async result for this invocation.

Spawn the given future on the thread-default main context, and return the the result with [return_result]. Specifically, if a variant is returned that is not a tuple it is automatically wrapped into a tuple.

The given Future does not have to be Send.

This can be called only from the thread where the main context is running, e.g. from any other Future that is executed on this main context, or after calling with_thread_default or acquire on the main context.

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) -> Option<GString>

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

This can be NULL if it was not specified by the sender. See `callback::Gio::DBusInterfaceMethodCallFunc or the D-Bus Specification for details on when this can happen and how it should be handled.

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) -> Option<GString>

Gets the bus name that invoked the method.

This can return None if not specified by the caller, e.g. on peer-to-peer connections.

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