gio/auto/test_dbus.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::{TestDBusFlags, ffi};
6use glib::translate::*;
7
8glib::wrapper! {
9 /// t activate D-Bus services that are not yet installed into the
10 /// target system. The `GTestDBus` object makes this easier for us by taking care
11 /// of the lower level tasks such as running a private D-Bus daemon and looking
12 /// up uninstalled services in customizable locations, typically in your source
13 /// code tree.
14 ///
15 /// The first thing you will need is a separate service description file for the
16 /// D-Bus daemon. Typically a `services` subdirectory of your `tests` directory
17 /// is a good place to put this file.
18 ///
19 /// The service file should list your service along with an absolute path to the
20 /// uninstalled service executable in your source tree. Using autotools we would
21 /// achieve this by adding a file such as `my-server.service.in` in the services
22 /// directory and have it processed by configure.
23 ///
24 /// ```text
25 /// [D-BUS Service]
26 /// Name=org.gtk.GDBus.Examples.ObjectManager
27 /// Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
28 /// ```
29 ///
30 /// You will also need to indicate this service directory in your test
31 /// fixtures, so you will need to pass the path while compiling your
32 /// test cases. Typically this is done with autotools with an added
33 /// preprocessor flag specified to compile your tests such as:
34 ///
35 /// ```text
36 /// -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
37 /// ```
38 ///
39 /// Once you have a service definition file which is local to your source tree,
40 /// you can proceed to set up a GTest fixture using the `GTestDBus` scaffolding.
41 ///
42 /// An example of a test fixture for D-Bus services can be found
43 /// here:
44 /// [gdbus-test-fixture.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-test-fixture.c)
45 ///
46 /// Note that these examples only deal with isolating the D-Bus aspect of your
47 /// service. To successfully run isolated unit tests on your service you may need
48 /// some additional modifications to your test case fixture. For example; if your
49 /// service uses [`Settings`][crate::Settings] and installs a schema then it is important
50 /// that your test service not load the schema in the ordinary installed location
51 /// (chances are that your service and schema files are not yet installed, or
52 /// worse; there is an older version of the schema file sitting in the install
53 /// location).
54 ///
55 /// Most of the time we can work around these obstacles using the
56 /// environment. Since the environment is inherited by the D-Bus daemon
57 /// created by `GTestDBus` and then in turn inherited by any services the
58 /// D-Bus daemon activates, using the setup routine for your fixture is
59 /// a practical place to help sandbox your runtime environment. For the
60 /// rather typical GSettings case we can work around this by setting
61 /// `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
62 /// in the above `fixture_setup()` routine.
63 ///
64 /// The GSettings schemas need to be locally pre-compiled for this to work. This
65 /// can be achieved by compiling the schemas locally as a step before running
66 /// test cases, an autotools setup might do the following in the directory
67 /// holding schemas:
68 ///
69 /// ```text
70 /// all-am:
71 /// $(GLIB_COMPILE_SCHEMAS) .
72 ///
73 /// CLEANFILES += gschemas.compiled
74 /// ```
75 ///
76 /// ## Properties
77 ///
78 ///
79 /// #### `flags`
80 /// #GTestDBusFlags specifying the behaviour of the D-Bus session.
81 ///
82 /// Readable | Writable | Construct Only
83 ///
84 /// # Implements
85 ///
86 /// [`trait@glib::ObjectExt`]
87 #[doc(alias = "GTestDBus")]
88 pub struct TestDBus(Object<ffi::GTestDBus>);
89
90 match fn {
91 type_ => || ffi::g_test_dbus_get_type(),
92 }
93}
94
95impl TestDBus {
96 /// Create a new #GTestDBus object.
97 /// ## `flags`
98 /// a #GTestDBusFlags
99 ///
100 /// # Returns
101 ///
102 /// a new #GTestDBus.
103 #[doc(alias = "g_test_dbus_new")]
104 pub fn new(flags: TestDBusFlags) -> TestDBus {
105 unsafe { from_glib_full(ffi::g_test_dbus_new(flags.into_glib())) }
106 }
107
108 /// Add a path where dbus-daemon will look up .service files. This can't be
109 /// called after g_test_dbus_up().
110 /// ## `path`
111 /// path to a directory containing .service files
112 #[doc(alias = "g_test_dbus_add_service_dir")]
113 pub fn add_service_dir(&self, path: &str) {
114 unsafe {
115 ffi::g_test_dbus_add_service_dir(self.to_glib_none().0, path.to_glib_none().0);
116 }
117 }
118
119 /// Stop the session bus started by g_test_dbus_up().
120 ///
121 /// This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
122 /// to be destroyed. This is done to ensure that the next unit test won't get a
123 /// leaked singleton from this test.
124 #[doc(alias = "g_test_dbus_down")]
125 pub fn down(&self) {
126 unsafe {
127 ffi::g_test_dbus_down(self.to_glib_none().0);
128 }
129 }
130
131 /// Get the address on which dbus-daemon is running. If g_test_dbus_up() has not
132 /// been called yet, [`None`] is returned. This can be used with
133 /// g_dbus_connection_new_for_address().
134 ///
135 /// # Returns
136 ///
137 /// the address of the bus, or [`None`].
138 #[doc(alias = "g_test_dbus_get_bus_address")]
139 #[doc(alias = "get_bus_address")]
140 pub fn bus_address(&self) -> Option<glib::GString> {
141 unsafe { from_glib_none(ffi::g_test_dbus_get_bus_address(self.to_glib_none().0)) }
142 }
143
144 /// Get the flags of the #GTestDBus object.
145 ///
146 /// # Returns
147 ///
148 /// the value of #GTestDBus:flags property
149 #[doc(alias = "g_test_dbus_get_flags")]
150 #[doc(alias = "get_flags")]
151 pub fn flags(&self) -> TestDBusFlags {
152 unsafe { from_glib(ffi::g_test_dbus_get_flags(self.to_glib_none().0)) }
153 }
154
155 /// Stop the session bus started by g_test_dbus_up().
156 ///
157 /// Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
158 /// singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
159 /// tests wanting to verify behaviour after the session bus has been stopped
160 /// can use this function but should still call g_test_dbus_down() when done.
161 #[doc(alias = "g_test_dbus_stop")]
162 pub fn stop(&self) {
163 unsafe {
164 ffi::g_test_dbus_stop(self.to_glib_none().0);
165 }
166 }
167
168 /// Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
169 /// call, it is safe for unit tests to start sending messages on the session bus.
170 ///
171 /// If this function is called from setup callback of g_test_add(),
172 /// g_test_dbus_down() must be called in its teardown callback.
173 ///
174 /// If this function is called from unit test's main(), then g_test_dbus_down()
175 /// must be called after g_test_run().
176 #[doc(alias = "g_test_dbus_up")]
177 pub fn up(&self) {
178 unsafe {
179 ffi::g_test_dbus_up(self.to_glib_none().0);
180 }
181 }
182
183 /// Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
184 /// won't use user's session bus.
185 ///
186 /// This is useful for unit tests that want to verify behaviour when no session
187 /// bus is running. It is not necessary to call this if unit test already calls
188 /// g_test_dbus_up() before acquiring the session bus.
189 #[doc(alias = "g_test_dbus_unset")]
190 pub fn unset() {
191 unsafe {
192 ffi::g_test_dbus_unset();
193 }
194 }
195}