gio/
dbus_method_invocation.rs

1// Take a look at the license at the top of the repository in the LICENSE file.
2
3use glib::{prelude::*, translate::*, VariantTy};
4
5use crate::{ffi, DBusMethodInvocation};
6
7impl DBusMethodInvocation {
8    /// Finishes handling a D-Bus method call by returning an error.
9    ///
10    /// See g_dbus_error_encode_gerror() for details about what error name
11    /// will be returned on the wire. In a nutshell, if the given error is
12    /// registered using g_dbus_error_register_error() the name given
13    /// during registration is used. Otherwise, a name of the form
14    /// `org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides
15    /// transparent mapping of #GError between applications using GDBus.
16    ///
17    /// If you are writing an application intended to be portable,
18    /// always register errors with g_dbus_error_register_error()
19    /// or use g_dbus_method_invocation_return_dbus_error().
20    ///
21    /// This method will take ownership of @self. See
22    /// #GDBusInterfaceVTable for more information about the ownership of
23    /// @self.
24    ///
25    /// Since 2.48, if the method call requested for a reply not to be sent
26    /// then this call will free @self but otherwise do nothing (as per
27    /// the recommendations of the D-Bus specification).
28    /// ## `domain`
29    /// A #GQuark for the #GError error domain.
30    /// ## `code`
31    /// The error code.
32    /// ## `format`
33    /// printf()-style format.
34    #[doc(alias = "g_dbus_method_invocation_return_error_literal")]
35    pub fn return_error<T: ErrorDomain>(&self, error: T, message: &str) {
36        unsafe {
37            ffi::g_dbus_method_invocation_return_error_literal(
38                self.to_glib_full(),
39                T::domain().into_glib(),
40                error.code(),
41                message.to_glib_none().0,
42            );
43        }
44    }
45
46    /// Like g_dbus_method_invocation_return_error() but takes a #GError
47    /// instead of the error domain, error code and message.
48    ///
49    /// This method will take ownership of @self. See
50    /// #GDBusInterfaceVTable for more information about the ownership of
51    /// @self.
52    /// ## `error`
53    /// A #GError.
54    #[doc(alias = "g_dbus_method_invocation_return_gerror")]
55    pub fn return_gerror(&self, error: glib::Error) {
56        unsafe {
57            ffi::g_dbus_method_invocation_return_gerror(
58                self.to_glib_full(),
59                error.to_glib_none().0,
60            );
61        }
62    }
63
64    // rustdoc-stripper-ignore-next
65    /// Return a result for this invocation.
66    ///
67    /// If `Ok` return the contained value with [`return_value`].  If the return
68    /// value is not a tuple, automatically convert it to a one-element tuple, as
69    /// DBus return values must be tuples.
70    ///
71    /// If `Err` return the contained error with [`return_gerror`].
72    pub fn return_result(self, result: Result<Option<glib::Variant>, glib::Error>) {
73        match result {
74            Ok(Some(value)) if !value.is_type(VariantTy::TUPLE) => {
75                let tupled = glib::Variant::tuple_from_iter(std::iter::once(value));
76                self.return_value(Some(&tupled));
77            }
78            Ok(value) => self.return_value(value.as_ref()),
79            Err(error) => self.return_gerror(error),
80        }
81    }
82
83    // rustdoc-stripper-ignore-next
84    /// Return an async result for this invocation.
85    ///
86    /// Spawn the given future on the thread-default main context, and return the
87    /// the result with [`return_result`].  Specifically, if a variant is returned
88    /// that is not a tuple it is automatically wrapped into a tuple.
89    ///
90    /// The given `Future` does not have to be `Send`.
91    ///
92    /// This can be called only from the thread where the main context is running, e.g.
93    /// from any other `Future` that is executed on this main context, or after calling
94    /// `with_thread_default` or `acquire` on the main context.
95    pub fn return_future_local<F>(self, f: F) -> glib::JoinHandle<()>
96    where
97        F: std::future::Future<Output = Result<Option<glib::Variant>, glib::Error>> + 'static,
98    {
99        glib::spawn_future_local(async move {
100            self.return_result(f.await);
101        })
102    }
103}