gio/auto/
dbus_method_invocation.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5#[cfg(unix)]
6#[cfg_attr(docsrs, doc(cfg(unix)))]
7use crate::UnixFDList;
8use crate::{ffi, DBusConnection, DBusMessage, DBusMethodInfo, DBusPropertyInfo};
9#[cfg(unix)]
10#[cfg_attr(docsrs, doc(cfg(unix)))]
11use glib::prelude::*;
12use glib::translate::*;
13
14glib::wrapper! {
15    /// Instances of the `GDBusMethodInvocation` class are used when
16    /// handling D-Bus method calls. It provides a way to asynchronously
17    /// return results and errors.
18    ///
19    /// The normal way to obtain a `GDBusMethodInvocation` object is to receive
20    /// it as an argument to the `handle_method_call()` function in a
21    /// [type@Gio.DBusInterfaceVTable] that was passed to
22    /// [`DBusConnection::register_object()`][crate::DBusConnection::register_object()].
23    ///
24    /// # Implements
25    ///
26    /// [`trait@glib::ObjectExt`]
27    #[doc(alias = "GDBusMethodInvocation")]
28    pub struct DBusMethodInvocation(Object<ffi::GDBusMethodInvocation>);
29
30    match fn {
31        type_ => || ffi::g_dbus_method_invocation_get_type(),
32    }
33}
34
35impl DBusMethodInvocation {
36    /// Gets the #GDBusConnection the method was invoked on.
37    ///
38    /// # Returns
39    ///
40    /// A #GDBusConnection. Do not free, it is owned by @self.
41    #[doc(alias = "g_dbus_method_invocation_get_connection")]
42    #[doc(alias = "get_connection")]
43    pub fn connection(&self) -> DBusConnection {
44        unsafe {
45            from_glib_none(ffi::g_dbus_method_invocation_get_connection(
46                self.to_glib_none().0,
47            ))
48        }
49    }
50
51    /// Gets the name of the D-Bus interface the method was invoked on.
52    ///
53    /// This can be `NULL` if it was not specified by the sender. See
54    /// `callback::Gio::DBusInterfaceMethodCallFunc or the
55    /// [D-Bus Specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-types-method)
56    /// for details on when this can happen and how it should be handled.
57    ///
58    /// If this method call is a property Get, Set or GetAll call that has
59    /// been redirected to the method call handler then
60    /// "org.freedesktop.DBus.Properties" will be returned.  See
61    /// #GDBusInterfaceVTable for more information.
62    ///
63    /// # Returns
64    ///
65    /// A string. Do not free, it is owned by @self.
66    #[doc(alias = "g_dbus_method_invocation_get_interface_name")]
67    #[doc(alias = "get_interface_name")]
68    pub fn interface_name(&self) -> Option<glib::GString> {
69        unsafe {
70            from_glib_none(ffi::g_dbus_method_invocation_get_interface_name(
71                self.to_glib_none().0,
72            ))
73        }
74    }
75
76    /// Gets the #GDBusMessage for the method invocation. This is useful if
77    /// you need to use low-level protocol features, such as UNIX file
78    /// descriptor passing, that cannot be properly expressed in the
79    /// #GVariant API.
80    ///
81    /// See this [server][`DBusConnection`][crate::DBusConnection]#an-example-d-bus-server]
82    /// and [client][`DBusConnection`][crate::DBusConnection]#an-example-for-file-descriptor-passing]
83    /// for an example of how to use this low-level API to send and receive
84    /// UNIX file descriptors.
85    ///
86    /// # Returns
87    ///
88    /// #GDBusMessage. Do not free, it is owned by @self.
89    #[doc(alias = "g_dbus_method_invocation_get_message")]
90    #[doc(alias = "get_message")]
91    pub fn message(&self) -> DBusMessage {
92        unsafe {
93            from_glib_none(ffi::g_dbus_method_invocation_get_message(
94                self.to_glib_none().0,
95            ))
96        }
97    }
98
99    /// Gets information about the method call, if any.
100    ///
101    /// If this method invocation is a property Get, Set or GetAll call that
102    /// has been redirected to the method call handler then [`None`] will be
103    /// returned.  See g_dbus_method_invocation_get_property_info() and
104    /// #GDBusInterfaceVTable for more information.
105    ///
106    /// # Returns
107    ///
108    /// A #GDBusMethodInfo or [`None`]. Do not free, it is owned by @self.
109    #[doc(alias = "g_dbus_method_invocation_get_method_info")]
110    #[doc(alias = "get_method_info")]
111    pub fn method_info(&self) -> Option<DBusMethodInfo> {
112        unsafe {
113            from_glib_none(ffi::g_dbus_method_invocation_get_method_info(
114                self.to_glib_none().0,
115            ))
116        }
117    }
118
119    /// Gets the name of the method that was invoked.
120    ///
121    /// # Returns
122    ///
123    /// A string. Do not free, it is owned by @self.
124    #[doc(alias = "g_dbus_method_invocation_get_method_name")]
125    #[doc(alias = "get_method_name")]
126    pub fn method_name(&self) -> glib::GString {
127        unsafe {
128            from_glib_none(ffi::g_dbus_method_invocation_get_method_name(
129                self.to_glib_none().0,
130            ))
131        }
132    }
133
134    /// Gets the object path the method was invoked on.
135    ///
136    /// # Returns
137    ///
138    /// A string. Do not free, it is owned by @self.
139    #[doc(alias = "g_dbus_method_invocation_get_object_path")]
140    #[doc(alias = "get_object_path")]
141    pub fn object_path(&self) -> glib::GString {
142        unsafe {
143            from_glib_none(ffi::g_dbus_method_invocation_get_object_path(
144                self.to_glib_none().0,
145            ))
146        }
147    }
148
149    /// Gets the parameters of the method invocation. If there are no input
150    /// parameters then this will return a GVariant with 0 children rather than NULL.
151    ///
152    /// # Returns
153    ///
154    /// A #GVariant tuple. Do not unref this because it is owned by @self.
155    #[doc(alias = "g_dbus_method_invocation_get_parameters")]
156    #[doc(alias = "get_parameters")]
157    pub fn parameters(&self) -> glib::Variant {
158        unsafe {
159            from_glib_none(ffi::g_dbus_method_invocation_get_parameters(
160                self.to_glib_none().0,
161            ))
162        }
163    }
164
165    /// Gets information about the property that this method call is for, if
166    /// any.
167    ///
168    /// This will only be set in the case of an invocation in response to a
169    /// property Get or Set call that has been directed to the method call
170    /// handler for an object on account of its property_get() or
171    /// property_set() vtable pointers being unset.
172    ///
173    /// See #GDBusInterfaceVTable for more information.
174    ///
175    /// If the call was GetAll, [`None`] will be returned.
176    ///
177    /// # Returns
178    ///
179    /// a #GDBusPropertyInfo or [`None`]
180    #[doc(alias = "g_dbus_method_invocation_get_property_info")]
181    #[doc(alias = "get_property_info")]
182    pub fn property_info(&self) -> Option<DBusPropertyInfo> {
183        unsafe {
184            from_glib_none(ffi::g_dbus_method_invocation_get_property_info(
185                self.to_glib_none().0,
186            ))
187        }
188    }
189
190    /// Gets the bus name that invoked the method.
191    ///
192    /// This can return [`None`] if not specified by the caller, e.g. on peer-to-peer
193    /// connections.
194    ///
195    /// # Returns
196    ///
197    /// A string. Do not free, it is owned by @self.
198    #[doc(alias = "g_dbus_method_invocation_get_sender")]
199    #[doc(alias = "get_sender")]
200    pub fn sender(&self) -> Option<glib::GString> {
201        unsafe {
202            from_glib_none(ffi::g_dbus_method_invocation_get_sender(
203                self.to_glib_none().0,
204            ))
205        }
206    }
207
208    //#[doc(alias = "g_dbus_method_invocation_get_user_data")]
209    //#[doc(alias = "get_user_data")]
210    //pub fn user_data(&self) -> /*Unimplemented*/Option<Basic: Pointer> {
211    //    unsafe { TODO: call ffi:g_dbus_method_invocation_get_user_data() }
212    //}
213
214    /// Finishes handling a D-Bus method call by returning an error.
215    ///
216    /// This method will take ownership of @self. See
217    /// #GDBusInterfaceVTable for more information about the ownership of
218    /// @self.
219    /// ## `error_name`
220    /// A valid D-Bus error name.
221    /// ## `error_message`
222    /// A valid D-Bus error message.
223    #[doc(alias = "g_dbus_method_invocation_return_dbus_error")]
224    pub fn return_dbus_error(self, error_name: &str, error_message: &str) {
225        unsafe {
226            ffi::g_dbus_method_invocation_return_dbus_error(
227                self.into_glib_ptr(),
228                error_name.to_glib_none().0,
229                error_message.to_glib_none().0,
230            );
231        }
232    }
233
234    //#[doc(alias = "g_dbus_method_invocation_return_error")]
235    //pub fn return_error(self, domain: glib::Quark, code: i32, format: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
236    //    unsafe { TODO: call ffi:g_dbus_method_invocation_return_error() }
237    //}
238
239    //#[doc(alias = "g_dbus_method_invocation_return_error_valist")]
240    //pub fn return_error_valist(self, domain: glib::Quark, code: i32, format: &str, var_args: /*Unknown conversion*//*Unimplemented*/Unsupported) {
241    //    unsafe { TODO: call ffi:g_dbus_method_invocation_return_error_valist() }
242    //}
243
244    /// Finishes handling a D-Bus method call by returning @parameters.
245    /// If the @parameters GVariant is floating, it is consumed.
246    ///
247    /// It is an error if @parameters is not of the right format: it must be a tuple
248    /// containing the out-parameters of the D-Bus method. Even if the method has a
249    /// single out-parameter, it must be contained in a tuple. If the method has no
250    /// out-parameters, @parameters may be [`None`] or an empty tuple.
251    ///
252    ///
253    ///
254    /// **⚠️ The following code is in C ⚠️**
255    ///
256    /// ```C
257    /// GDBusMethodInvocation *invocation = some_invocation;
258    /// g_autofree gchar *result_string = NULL;
259    /// g_autoptr (GError) error = NULL;
260    ///
261    /// result_string = calculate_result (&error);
262    ///
263    /// if (error != NULL)
264    ///   g_dbus_method_invocation_return_gerror (invocation, error);
265    /// else
266    ///   g_dbus_method_invocation_return_value (invocation,
267    ///                                          g_variant_new ("(s)", result_string));
268    ///
269    /// // Do not free @self here; returning a value does that
270    /// ```
271    ///
272    /// This method will take ownership of @self. See
273    /// #GDBusInterfaceVTable for more information about the ownership of
274    /// @self.
275    ///
276    /// Since 2.48, if the method call requested for a reply not to be sent
277    /// then this call will sink @parameters and free @self, but
278    /// otherwise do nothing (as per the recommendations of the D-Bus
279    /// specification).
280    /// ## `parameters`
281    /// A #GVariant tuple with out parameters for the method or [`None`] if not passing any parameters.
282    #[doc(alias = "g_dbus_method_invocation_return_value")]
283    pub fn return_value(self, parameters: Option<&glib::Variant>) {
284        unsafe {
285            ffi::g_dbus_method_invocation_return_value(
286                self.into_glib_ptr(),
287                parameters.to_glib_none().0,
288            );
289        }
290    }
291
292    /// Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
293    ///
294    /// This method is only available on UNIX.
295    ///
296    /// This method will take ownership of @self. See
297    /// #GDBusInterfaceVTable for more information about the ownership of
298    /// @self.
299    /// ## `parameters`
300    /// A #GVariant tuple with out parameters for the method or [`None`] if not passing any parameters.
301    /// ## `fd_list`
302    /// A #GUnixFDList or [`None`].
303    #[cfg(unix)]
304    #[cfg_attr(docsrs, doc(cfg(unix)))]
305    #[doc(alias = "g_dbus_method_invocation_return_value_with_unix_fd_list")]
306    pub fn return_value_with_unix_fd_list(
307        self,
308        parameters: Option<&glib::Variant>,
309        fd_list: Option<&impl IsA<UnixFDList>>,
310    ) {
311        unsafe {
312            ffi::g_dbus_method_invocation_return_value_with_unix_fd_list(
313                self.into_glib_ptr(),
314                parameters.to_glib_none().0,
315                fd_list.map(|p| p.as_ref()).to_glib_none().0,
316            );
317        }
318    }
319}