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}