gio/
dbus_method_invocation.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
// Take a look at the license at the top of the repository in the LICENSE file.

use glib::{prelude::*, translate::*, VariantTy};

use crate::{ffi, DBusMethodInvocation};

impl DBusMethodInvocation {
    /// 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.
    #[doc(alias = "g_dbus_method_invocation_return_error_literal")]
    pub fn return_error<T: ErrorDomain>(&self, error: T, message: &str) {
        unsafe {
            ffi::g_dbus_method_invocation_return_error_literal(
                self.to_glib_full(),
                T::domain().into_glib(),
                error.code(),
                message.to_glib_none().0,
            );
        }
    }

    /// 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.
    #[doc(alias = "g_dbus_method_invocation_return_gerror")]
    pub fn return_gerror(&self, error: glib::Error) {
        unsafe {
            ffi::g_dbus_method_invocation_return_gerror(
                self.to_glib_full(),
                error.to_glib_none().0,
            );
        }
    }

    // rustdoc-stripper-ignore-next
    /// 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_result(self, result: Result<Option<glib::Variant>, glib::Error>) {
        match result {
            Ok(Some(value)) if !value.is_type(VariantTy::TUPLE) => {
                let tupled = glib::Variant::tuple_from_iter(std::iter::once(value));
                self.return_value(Some(&tupled));
            }
            Ok(value) => self.return_value(value.as_ref()),
            Err(error) => self.return_gerror(error),
        }
    }

    // rustdoc-stripper-ignore-next
    /// 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.
    pub fn return_future_local<F>(self, f: F) -> glib::JoinHandle<()>
    where
        F: std::future::Future<Output = Result<Option<glib::Variant>, glib::Error>> + 'static,
    {
        glib::spawn_future_local(async move {
            self.return_result(f.await);
        })
    }
}