gio/auto/
dbus_server.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
5use crate::{ffi, Cancellable, DBusAuthObserver, DBusConnection, DBusServerFlags, Initable};
6use glib::{
7    object::ObjectType as _,
8    prelude::*,
9    signal::{connect_raw, SignalHandlerId},
10    translate::*,
11};
12use std::boxed::Box as Box_;
13
14glib::wrapper! {
15    /// `GDBusServer` is a helper for listening to and accepting D-Bus
16    /// connections. This can be used to create a new D-Bus server, allowing two
17    /// peers to use the D-Bus protocol for their own specialized communication.
18    /// A server instance provided in this way will not perform message routing or
19    /// implement the
20    /// [`org.freedesktop.DBus` interface](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-messages).
21    ///
22    /// To just export an object on a well-known name on a message bus, such as the
23    /// session or system bus, you should instead use `bus_own_name()`.
24    ///
25    /// An example of peer-to-peer communication with GDBus can be found
26    /// in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c).
27    ///
28    /// Note that a minimal `GDBusServer` will accept connections from any
29    /// peer. In many use-cases it will be necessary to add a
30    /// [`DBusAuthObserver`][crate::DBusAuthObserver] that only accepts connections that have
31    /// successfully authenticated as the same user that is running the
32    /// `GDBusServer`. Since GLib 2.68 this can be achieved more simply by passing
33    /// the `G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag to the
34    /// server.
35    ///
36    /// ## Properties
37    ///
38    ///
39    /// #### `active`
40    ///  Whether the server is currently active.
41    ///
42    /// Readable
43    ///
44    ///
45    /// #### `address`
46    ///  The D-Bus address to listen on.
47    ///
48    /// Readable | Writeable | Construct Only
49    ///
50    ///
51    /// #### `authentication-observer`
52    ///  A #GDBusAuthObserver object to assist in the authentication process or [`None`].
53    ///
54    /// Readable | Writeable | Construct Only
55    ///
56    ///
57    /// #### `client-address`
58    ///  The D-Bus address that clients can use.
59    ///
60    /// Readable
61    ///
62    ///
63    /// #### `flags`
64    ///  Flags from the #GDBusServerFlags enumeration.
65    ///
66    /// Readable | Writeable | Construct Only
67    ///
68    ///
69    /// #### `guid`
70    ///  The GUID of the server.
71    ///
72    /// See #GDBusConnection:guid for more details.
73    ///
74    /// Readable | Writeable | Construct Only
75    ///
76    /// ## Signals
77    ///
78    ///
79    /// #### `new-connection`
80    ///  Emitted when a new authenticated connection has been made. Use
81    /// g_dbus_connection_get_peer_credentials() to figure out what
82    /// identity (if any), was authenticated.
83    ///
84    /// If you want to accept the connection, take a reference to the
85    /// @connection object and return [`true`]. When you are done with the
86    /// connection call g_dbus_connection_close() and give up your
87    /// reference. Note that the other peer may disconnect at any time -
88    /// a typical thing to do when accepting a connection is to listen to
89    /// the #GDBusConnection::closed signal.
90    ///
91    /// If #GDBusServer:flags contains [`DBusServerFlags::RUN_IN_THREAD`][crate::DBusServerFlags::RUN_IN_THREAD]
92    /// then the signal is emitted in a new thread dedicated to the
93    /// connection. Otherwise the signal is emitted in the thread-default
94    /// main context (see [`glib::MainContext::push_thread_default()`][crate::glib::MainContext::push_thread_default()])
95    /// of the thread that @server was constructed in.
96    ///
97    /// You are guaranteed that signal handlers for this signal runs
98    /// before incoming messages on @connection are processed. This means
99    /// that it's suitable to call g_dbus_connection_register_object() or
100    /// similar from the signal handler.
101    ///
102    ///
103    ///
104    /// # Implements
105    ///
106    /// [`trait@glib::ObjectExt`], [`InitableExt`][trait@crate::prelude::InitableExt]
107    #[doc(alias = "GDBusServer")]
108    pub struct DBusServer(Object<ffi::GDBusServer>) @implements Initable;
109
110    match fn {
111        type_ => || ffi::g_dbus_server_get_type(),
112    }
113}
114
115impl DBusServer {
116    /// Creates a new D-Bus server that listens on the first address in
117    /// @address that works.
118    ///
119    /// Once constructed, you can use g_dbus_server_get_client_address() to
120    /// get a D-Bus address string that clients can use to connect.
121    ///
122    /// To have control over the available authentication mechanisms and
123    /// the users that are authorized to connect, it is strongly recommended
124    /// to provide a non-[`None`] #GDBusAuthObserver.
125    ///
126    /// Connect to the #GDBusServer::new-connection signal to handle
127    /// incoming connections.
128    ///
129    /// The returned #GDBusServer isn't active - you have to start it with
130    /// g_dbus_server_start().
131    ///
132    /// #GDBusServer is used in this [example](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c).
133    ///
134    /// This is a synchronous failable constructor. There is currently no
135    /// asynchronous version.
136    /// ## `address`
137    /// A D-Bus address.
138    /// ## `flags`
139    /// Flags from the #GDBusServerFlags enumeration.
140    /// ## `guid`
141    /// A D-Bus GUID.
142    /// ## `observer`
143    /// A #GDBusAuthObserver or [`None`].
144    /// ## `cancellable`
145    /// A #GCancellable or [`None`].
146    ///
147    /// # Returns
148    ///
149    /// A #GDBusServer or [`None`] if @error is set. Free with
150    /// g_object_unref().
151    #[doc(alias = "g_dbus_server_new_sync")]
152    pub fn new_sync(
153        address: &str,
154        flags: DBusServerFlags,
155        guid: &str,
156        observer: Option<&DBusAuthObserver>,
157        cancellable: Option<&impl IsA<Cancellable>>,
158    ) -> Result<DBusServer, glib::Error> {
159        unsafe {
160            let mut error = std::ptr::null_mut();
161            let ret = ffi::g_dbus_server_new_sync(
162                address.to_glib_none().0,
163                flags.into_glib(),
164                guid.to_glib_none().0,
165                observer.to_glib_none().0,
166                cancellable.map(|p| p.as_ref()).to_glib_none().0,
167                &mut error,
168            );
169            if error.is_null() {
170                Ok(from_glib_full(ret))
171            } else {
172                Err(from_glib_full(error))
173            }
174        }
175    }
176
177    /// Gets a
178    /// [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses)
179    /// string that can be used by clients to connect to @self.
180    ///
181    /// This is valid and non-empty if initializing the #GDBusServer succeeded.
182    ///
183    /// # Returns
184    ///
185    /// A D-Bus address string. Do not free, the string is owned
186    /// by @self.
187    #[doc(alias = "g_dbus_server_get_client_address")]
188    #[doc(alias = "get_client_address")]
189    #[doc(alias = "client-address")]
190    pub fn client_address(&self) -> glib::GString {
191        unsafe { from_glib_none(ffi::g_dbus_server_get_client_address(self.to_glib_none().0)) }
192    }
193
194    /// Gets the flags for @self.
195    ///
196    /// # Returns
197    ///
198    /// A set of flags from the #GDBusServerFlags enumeration.
199    #[doc(alias = "g_dbus_server_get_flags")]
200    #[doc(alias = "get_flags")]
201    pub fn flags(&self) -> DBusServerFlags {
202        unsafe { from_glib(ffi::g_dbus_server_get_flags(self.to_glib_none().0)) }
203    }
204
205    /// Gets the GUID for @self, as provided to g_dbus_server_new_sync().
206    ///
207    /// # Returns
208    ///
209    /// A D-Bus GUID. Do not free this string, it is owned by @self.
210    #[doc(alias = "g_dbus_server_get_guid")]
211    #[doc(alias = "get_guid")]
212    pub fn guid(&self) -> glib::GString {
213        unsafe { from_glib_none(ffi::g_dbus_server_get_guid(self.to_glib_none().0)) }
214    }
215
216    /// Gets whether @self is active.
217    ///
218    /// # Returns
219    ///
220    /// [`true`] if server is active, [`false`] otherwise.
221    #[doc(alias = "g_dbus_server_is_active")]
222    #[doc(alias = "active")]
223    pub fn is_active(&self) -> bool {
224        unsafe { from_glib(ffi::g_dbus_server_is_active(self.to_glib_none().0)) }
225    }
226
227    /// Starts @self.
228    #[doc(alias = "g_dbus_server_start")]
229    pub fn start(&self) {
230        unsafe {
231            ffi::g_dbus_server_start(self.to_glib_none().0);
232        }
233    }
234
235    /// Stops @self.
236    #[doc(alias = "g_dbus_server_stop")]
237    pub fn stop(&self) {
238        unsafe {
239            ffi::g_dbus_server_stop(self.to_glib_none().0);
240        }
241    }
242
243    /// The D-Bus address to listen on.
244    pub fn address(&self) -> Option<glib::GString> {
245        ObjectExt::property(self, "address")
246    }
247
248    /// A #GDBusAuthObserver object to assist in the authentication process or [`None`].
249    #[doc(alias = "authentication-observer")]
250    pub fn authentication_observer(&self) -> Option<DBusAuthObserver> {
251        ObjectExt::property(self, "authentication-observer")
252    }
253
254    /// Emitted when a new authenticated connection has been made. Use
255    /// g_dbus_connection_get_peer_credentials() to figure out what
256    /// identity (if any), was authenticated.
257    ///
258    /// If you want to accept the connection, take a reference to the
259    /// @connection object and return [`true`]. When you are done with the
260    /// connection call g_dbus_connection_close() and give up your
261    /// reference. Note that the other peer may disconnect at any time -
262    /// a typical thing to do when accepting a connection is to listen to
263    /// the #GDBusConnection::closed signal.
264    ///
265    /// If #GDBusServer:flags contains [`DBusServerFlags::RUN_IN_THREAD`][crate::DBusServerFlags::RUN_IN_THREAD]
266    /// then the signal is emitted in a new thread dedicated to the
267    /// connection. Otherwise the signal is emitted in the thread-default
268    /// main context (see [`glib::MainContext::push_thread_default()`][crate::glib::MainContext::push_thread_default()])
269    /// of the thread that @server was constructed in.
270    ///
271    /// You are guaranteed that signal handlers for this signal runs
272    /// before incoming messages on @connection are processed. This means
273    /// that it's suitable to call g_dbus_connection_register_object() or
274    /// similar from the signal handler.
275    /// ## `connection`
276    /// A #GDBusConnection for the new connection.
277    ///
278    /// # Returns
279    ///
280    /// [`true`] to claim @connection, [`false`] to let other handlers
281    /// run.
282    #[doc(alias = "new-connection")]
283    pub fn connect_new_connection<F: Fn(&Self, &DBusConnection) -> bool + 'static>(
284        &self,
285        f: F,
286    ) -> SignalHandlerId {
287        unsafe extern "C" fn new_connection_trampoline<
288            F: Fn(&DBusServer, &DBusConnection) -> bool + 'static,
289        >(
290            this: *mut ffi::GDBusServer,
291            connection: *mut ffi::GDBusConnection,
292            f: glib::ffi::gpointer,
293        ) -> glib::ffi::gboolean {
294            let f: &F = &*(f as *const F);
295            f(&from_glib_borrow(this), &from_glib_borrow(connection)).into_glib()
296        }
297        unsafe {
298            let f: Box_<F> = Box_::new(f);
299            connect_raw(
300                self.as_ptr() as *mut _,
301                b"new-connection\0".as_ptr() as *const _,
302                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
303                    new_connection_trampoline::<F> as *const (),
304                )),
305                Box_::into_raw(f),
306            )
307        }
308    }
309
310    #[doc(alias = "active")]
311    pub fn connect_active_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
312        unsafe extern "C" fn notify_active_trampoline<F: Fn(&DBusServer) + 'static>(
313            this: *mut ffi::GDBusServer,
314            _param_spec: glib::ffi::gpointer,
315            f: glib::ffi::gpointer,
316        ) {
317            let f: &F = &*(f as *const F);
318            f(&from_glib_borrow(this))
319        }
320        unsafe {
321            let f: Box_<F> = Box_::new(f);
322            connect_raw(
323                self.as_ptr() as *mut _,
324                b"notify::active\0".as_ptr() as *const _,
325                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
326                    notify_active_trampoline::<F> as *const (),
327                )),
328                Box_::into_raw(f),
329            )
330        }
331    }
332
333    #[doc(alias = "client-address")]
334    pub fn connect_client_address_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
335        unsafe extern "C" fn notify_client_address_trampoline<F: Fn(&DBusServer) + 'static>(
336            this: *mut ffi::GDBusServer,
337            _param_spec: glib::ffi::gpointer,
338            f: glib::ffi::gpointer,
339        ) {
340            let f: &F = &*(f as *const F);
341            f(&from_glib_borrow(this))
342        }
343        unsafe {
344            let f: Box_<F> = Box_::new(f);
345            connect_raw(
346                self.as_ptr() as *mut _,
347                b"notify::client-address\0".as_ptr() as *const _,
348                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
349                    notify_client_address_trampoline::<F> as *const (),
350                )),
351                Box_::into_raw(f),
352            )
353        }
354    }
355}