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}