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}