gio/auto/volume.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::{
6 ffi, AsyncResult, Cancellable, Drive, File, Icon, Mount, MountMountFlags, MountOperation,
7 MountUnmountFlags,
8};
9use glib::{
10 object::ObjectType as _,
11 prelude::*,
12 signal::{connect_raw, SignalHandlerId},
13 translate::*,
14};
15use std::{boxed::Box as Box_, pin::Pin};
16
17glib::wrapper! {
18 /// The `GVolume` interface represents user-visible objects that can be
19 /// mounted. For example, a file system partition on a USB flash drive, or an
20 /// optical disc inserted into a disc drive.
21 ///
22 /// If a `GVolume` is currently mounted, the corresponding [`Mount`][crate::Mount] can
23 /// be retrieved using [`VolumeExt::get_mount()`][crate::prelude::VolumeExt::get_mount()].
24 ///
25 /// Mounting a `GVolume` instance is an asynchronous operation. For more
26 /// information about asynchronous operations, see [`AsyncResult`][crate::AsyncResult] and
27 /// [`Task`][crate::Task]. To mount a `GVolume`, first call [`VolumeExt::mount()`][crate::prelude::VolumeExt::mount()]
28 /// with (at least) the `GVolume` instance, optionally a
29 /// [`MountOperation`][crate::MountOperation] object and a [type@Gio.AsyncReadyCallback].
30 ///
31 /// Typically, one will only want to pass `NULL` for the
32 /// [`MountOperation`][crate::MountOperation] if automounting all volumes when a desktop session
33 /// starts since it’s not desirable to put up a lot of dialogs asking
34 /// for credentials.
35 ///
36 /// The callback will be fired when the operation has resolved (either
37 /// with success or failure), and a [`AsyncResult`][crate::AsyncResult] instance will be
38 /// passed to the callback. That callback should then call
39 /// `Gio::Volume::mount_finish()` with the `GVolume` instance and the
40 /// [`AsyncResult`][crate::AsyncResult] data to see if the operation was completed
41 /// successfully. If a [type@GLib.Error] is present when
42 /// `Gio::Volume::mount_finish()` is called, then it will be filled with any
43 /// error information.
44 ///
45 /// Note, when [porting from GnomeVFS](migrating-gnome-vfs.html),
46 /// `GVolume` is the moral equivalent of `GnomeVFSDrive`.
47 ///
48 /// ## Volume Identifiers
49 ///
50 /// It is sometimes necessary to directly access the underlying
51 /// operating system object behind a volume (e.g. for passing a volume
52 /// to an application via the command line). For this purpose, GIO
53 /// allows to obtain an ‘identifier’ for the volume. There can be
54 /// different kinds of identifiers, such as Hal UDIs, filesystem labels,
55 /// traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined
56 /// strings as names for the different kinds of identifiers:
57 /// `G_VOLUME_IDENTIFIER_KIND_UUID`, `G_VOLUME_IDENTIFIER_KIND_LABEL`, etc.
58 /// Use [`VolumeExt::identifier()`][crate::prelude::VolumeExt::identifier()] to obtain an identifier for a volume.
59 ///
60 /// Note that `G_VOLUME_IDENTIFIER_KIND_HAL_UDI` will only be available
61 /// when the GVFS hal volume monitor is in use. Other volume monitors
62 /// will generally be able to provide the `G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE`
63 /// identifier, which can be used to obtain a hal device by means of
64 /// `libhal_manager_find_device_string_match()`.
65 ///
66 /// ## Signals
67 ///
68 ///
69 /// #### `changed`
70 /// Emitted when the volume has been changed.
71 ///
72 ///
73 ///
74 ///
75 /// #### `removed`
76 /// This signal is emitted when the #GVolume have been removed. If
77 /// the recipient is holding references to the object they should
78 /// release them so the object can be finalized.
79 ///
80 ///
81 ///
82 /// # Implements
83 ///
84 /// [`VolumeExt`][trait@crate::prelude::VolumeExt]
85 #[doc(alias = "GVolume")]
86 pub struct Volume(Interface<ffi::GVolume, ffi::GVolumeIface>);
87
88 match fn {
89 type_ => || ffi::g_volume_get_type(),
90 }
91}
92
93impl Volume {
94 pub const NONE: Option<&'static Volume> = None;
95}
96
97mod sealed {
98 pub trait Sealed {}
99 impl<T: super::IsA<super::Volume>> Sealed for T {}
100}
101
102/// Trait containing all [`struct@Volume`] methods.
103///
104/// # Implementors
105///
106/// [`Volume`][struct@crate::Volume]
107pub trait VolumeExt: IsA<Volume> + sealed::Sealed + 'static {
108 /// Checks if a volume can be ejected.
109 ///
110 /// # Returns
111 ///
112 /// [`true`] if the @self can be ejected. [`false`] otherwise
113 #[doc(alias = "g_volume_can_eject")]
114 fn can_eject(&self) -> bool {
115 unsafe { from_glib(ffi::g_volume_can_eject(self.as_ref().to_glib_none().0)) }
116 }
117
118 /// Checks if a volume can be mounted.
119 ///
120 /// # Returns
121 ///
122 /// [`true`] if the @self can be mounted. [`false`] otherwise
123 #[doc(alias = "g_volume_can_mount")]
124 fn can_mount(&self) -> bool {
125 unsafe { from_glib(ffi::g_volume_can_mount(self.as_ref().to_glib_none().0)) }
126 }
127
128 /// Ejects a volume. This is an asynchronous operation, and is
129 /// finished by calling g_volume_eject_with_operation_finish() with the @self
130 /// and #GAsyncResult data returned in the @callback.
131 /// ## `flags`
132 /// flags affecting the unmount if required for eject
133 /// ## `mount_operation`
134 /// a #GMountOperation or [`None`] to
135 /// avoid user interaction
136 /// ## `cancellable`
137 /// optional #GCancellable object, [`None`] to ignore
138 /// ## `callback`
139 /// a #GAsyncReadyCallback, or [`None`]
140 #[doc(alias = "g_volume_eject_with_operation")]
141 fn eject_with_operation<P: FnOnce(Result<(), glib::Error>) + 'static>(
142 &self,
143 flags: MountUnmountFlags,
144 mount_operation: Option<&impl IsA<MountOperation>>,
145 cancellable: Option<&impl IsA<Cancellable>>,
146 callback: P,
147 ) {
148 let main_context = glib::MainContext::ref_thread_default();
149 let is_main_context_owner = main_context.is_owner();
150 let has_acquired_main_context = (!is_main_context_owner)
151 .then(|| main_context.acquire().ok())
152 .flatten();
153 assert!(
154 is_main_context_owner || has_acquired_main_context.is_some(),
155 "Async operations only allowed if the thread is owning the MainContext"
156 );
157
158 let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
159 Box_::new(glib::thread_guard::ThreadGuard::new(callback));
160 unsafe extern "C" fn eject_with_operation_trampoline<
161 P: FnOnce(Result<(), glib::Error>) + 'static,
162 >(
163 _source_object: *mut glib::gobject_ffi::GObject,
164 res: *mut crate::ffi::GAsyncResult,
165 user_data: glib::ffi::gpointer,
166 ) {
167 let mut error = std::ptr::null_mut();
168 ffi::g_volume_eject_with_operation_finish(_source_object as *mut _, res, &mut error);
169 let result = if error.is_null() {
170 Ok(())
171 } else {
172 Err(from_glib_full(error))
173 };
174 let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
175 Box_::from_raw(user_data as *mut _);
176 let callback: P = callback.into_inner();
177 callback(result);
178 }
179 let callback = eject_with_operation_trampoline::<P>;
180 unsafe {
181 ffi::g_volume_eject_with_operation(
182 self.as_ref().to_glib_none().0,
183 flags.into_glib(),
184 mount_operation.map(|p| p.as_ref()).to_glib_none().0,
185 cancellable.map(|p| p.as_ref()).to_glib_none().0,
186 Some(callback),
187 Box_::into_raw(user_data) as *mut _,
188 );
189 }
190 }
191
192 fn eject_with_operation_future(
193 &self,
194 flags: MountUnmountFlags,
195 mount_operation: Option<&(impl IsA<MountOperation> + Clone + 'static)>,
196 ) -> Pin<Box_<dyn std::future::Future<Output = Result<(), glib::Error>> + 'static>> {
197 let mount_operation = mount_operation.map(ToOwned::to_owned);
198 Box_::pin(crate::GioFuture::new(
199 self,
200 move |obj, cancellable, send| {
201 obj.eject_with_operation(
202 flags,
203 mount_operation.as_ref().map(::std::borrow::Borrow::borrow),
204 Some(cancellable),
205 move |res| {
206 send.resolve(res);
207 },
208 );
209 },
210 ))
211 }
212
213 /// Gets the kinds of [identifiers](#volume-identifiers) that @self has.
214 /// Use g_volume_get_identifier() to obtain the identifiers themselves.
215 ///
216 /// # Returns
217 ///
218 /// a [`None`]-terminated array
219 /// of strings containing kinds of identifiers. Use g_strfreev() to free.
220 #[doc(alias = "g_volume_enumerate_identifiers")]
221 fn enumerate_identifiers(&self) -> Vec<glib::GString> {
222 unsafe {
223 FromGlibPtrContainer::from_glib_full(ffi::g_volume_enumerate_identifiers(
224 self.as_ref().to_glib_none().0,
225 ))
226 }
227 }
228
229 /// Gets the activation root for a #GVolume if it is known ahead of
230 /// mount time. Returns [`None`] otherwise. If not [`None`] and if @self
231 /// is mounted, then the result of g_mount_get_root() on the
232 /// #GMount object obtained from g_volume_get_mount() will always
233 /// either be equal or a prefix of what this function returns. In
234 /// other words, in code
235 ///
236 ///
237 ///
238 /// **⚠️ The following code is in C ⚠️**
239 ///
240 /// ```C
241 /// GMount *mount;
242 /// GFile *mount_root
243 /// GFile *volume_activation_root;
244 ///
245 /// mount = g_volume_get_mount (volume); // mounted, so never NULL
246 /// mount_root = g_mount_get_root (mount);
247 /// volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
248 /// ```
249 /// then the expression
250 ///
251 ///
252 /// **⚠️ The following code is in C ⚠️**
253 ///
254 /// ```C
255 /// (g_file_has_prefix (volume_activation_root, mount_root) ||
256 /// g_file_equal (volume_activation_root, mount_root))
257 /// ```
258 /// will always be [`true`].
259 ///
260 /// Activation roots are typically used in #GVolumeMonitor
261 /// implementations to find the underlying mount to shadow, see
262 /// g_mount_is_shadowed() for more details.
263 ///
264 /// # Returns
265 ///
266 /// the activation root of @self
267 /// or [`None`]. Use g_object_unref() to free.
268 #[doc(alias = "g_volume_get_activation_root")]
269 #[doc(alias = "get_activation_root")]
270 fn activation_root(&self) -> Option<File> {
271 unsafe {
272 from_glib_full(ffi::g_volume_get_activation_root(
273 self.as_ref().to_glib_none().0,
274 ))
275 }
276 }
277
278 /// Gets the drive for the @self.
279 ///
280 /// # Returns
281 ///
282 /// a #GDrive or [`None`] if @self is not
283 /// associated with a drive. The returned object should be unreffed
284 /// with g_object_unref() when no longer needed.
285 #[doc(alias = "g_volume_get_drive")]
286 #[doc(alias = "get_drive")]
287 fn drive(&self) -> Option<Drive> {
288 unsafe { from_glib_full(ffi::g_volume_get_drive(self.as_ref().to_glib_none().0)) }
289 }
290
291 /// Gets the icon for @self.
292 ///
293 /// # Returns
294 ///
295 /// a #GIcon.
296 /// The returned object should be unreffed with g_object_unref()
297 /// when no longer needed.
298 #[doc(alias = "g_volume_get_icon")]
299 #[doc(alias = "get_icon")]
300 fn icon(&self) -> Icon {
301 unsafe { from_glib_full(ffi::g_volume_get_icon(self.as_ref().to_glib_none().0)) }
302 }
303
304 /// Gets the identifier of the given kind for @self.
305 /// See the [introduction](#volume-identifiers) for more
306 /// information about volume identifiers.
307 /// ## `kind`
308 /// the kind of identifier to return
309 ///
310 /// # Returns
311 ///
312 /// a newly allocated string containing the
313 /// requested identifier, or [`None`] if the #GVolume
314 /// doesn't have this kind of identifier
315 #[doc(alias = "g_volume_get_identifier")]
316 #[doc(alias = "get_identifier")]
317 fn identifier(&self, kind: &str) -> Option<glib::GString> {
318 unsafe {
319 from_glib_full(ffi::g_volume_get_identifier(
320 self.as_ref().to_glib_none().0,
321 kind.to_glib_none().0,
322 ))
323 }
324 }
325
326 /// Gets the mount for the @self.
327 ///
328 /// # Returns
329 ///
330 /// a #GMount or [`None`] if @self isn't mounted.
331 /// The returned object should be unreffed with g_object_unref()
332 /// when no longer needed.
333 #[doc(alias = "g_volume_get_mount")]
334 fn get_mount(&self) -> Option<Mount> {
335 unsafe { from_glib_full(ffi::g_volume_get_mount(self.as_ref().to_glib_none().0)) }
336 }
337
338 /// Gets the name of @self.
339 ///
340 /// # Returns
341 ///
342 /// the name for the given @self. The returned string should
343 /// be freed with g_free() when no longer needed.
344 #[doc(alias = "g_volume_get_name")]
345 #[doc(alias = "get_name")]
346 fn name(&self) -> glib::GString {
347 unsafe { from_glib_full(ffi::g_volume_get_name(self.as_ref().to_glib_none().0)) }
348 }
349
350 /// Gets the sort key for @self, if any.
351 ///
352 /// # Returns
353 ///
354 /// Sorting key for @self or [`None`] if no such key is available
355 #[doc(alias = "g_volume_get_sort_key")]
356 #[doc(alias = "get_sort_key")]
357 fn sort_key(&self) -> Option<glib::GString> {
358 unsafe { from_glib_none(ffi::g_volume_get_sort_key(self.as_ref().to_glib_none().0)) }
359 }
360
361 /// Gets the symbolic icon for @self.
362 ///
363 /// # Returns
364 ///
365 /// a #GIcon.
366 /// The returned object should be unreffed with g_object_unref()
367 /// when no longer needed.
368 #[doc(alias = "g_volume_get_symbolic_icon")]
369 #[doc(alias = "get_symbolic_icon")]
370 fn symbolic_icon(&self) -> Icon {
371 unsafe {
372 from_glib_full(ffi::g_volume_get_symbolic_icon(
373 self.as_ref().to_glib_none().0,
374 ))
375 }
376 }
377
378 /// Gets the UUID for the @self. The reference is typically based on
379 /// the file system UUID for the volume in question and should be
380 /// considered an opaque string. Returns [`None`] if there is no UUID
381 /// available.
382 ///
383 /// # Returns
384 ///
385 /// the UUID for @self or [`None`] if no UUID
386 /// can be computed.
387 /// The returned string should be freed with g_free()
388 /// when no longer needed.
389 #[doc(alias = "g_volume_get_uuid")]
390 #[doc(alias = "get_uuid")]
391 fn uuid(&self) -> Option<glib::GString> {
392 unsafe { from_glib_full(ffi::g_volume_get_uuid(self.as_ref().to_glib_none().0)) }
393 }
394
395 /// Mounts a volume. This is an asynchronous operation, and is
396 /// finished by calling g_volume_mount_finish() with the @self
397 /// and #GAsyncResult returned in the @callback.
398 /// ## `flags`
399 /// flags affecting the operation
400 /// ## `mount_operation`
401 /// a #GMountOperation or [`None`] to avoid user interaction
402 /// ## `cancellable`
403 /// optional #GCancellable object, [`None`] to ignore
404 /// ## `callback`
405 /// a #GAsyncReadyCallback, or [`None`]
406 #[doc(alias = "g_volume_mount")]
407 fn mount<P: FnOnce(Result<(), glib::Error>) + 'static>(
408 &self,
409 flags: MountMountFlags,
410 mount_operation: Option<&impl IsA<MountOperation>>,
411 cancellable: Option<&impl IsA<Cancellable>>,
412 callback: P,
413 ) {
414 let main_context = glib::MainContext::ref_thread_default();
415 let is_main_context_owner = main_context.is_owner();
416 let has_acquired_main_context = (!is_main_context_owner)
417 .then(|| main_context.acquire().ok())
418 .flatten();
419 assert!(
420 is_main_context_owner || has_acquired_main_context.is_some(),
421 "Async operations only allowed if the thread is owning the MainContext"
422 );
423
424 let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
425 Box_::new(glib::thread_guard::ThreadGuard::new(callback));
426 unsafe extern "C" fn mount_trampoline<P: FnOnce(Result<(), glib::Error>) + 'static>(
427 _source_object: *mut glib::gobject_ffi::GObject,
428 res: *mut crate::ffi::GAsyncResult,
429 user_data: glib::ffi::gpointer,
430 ) {
431 let mut error = std::ptr::null_mut();
432 ffi::g_volume_mount_finish(_source_object as *mut _, res, &mut error);
433 let result = if error.is_null() {
434 Ok(())
435 } else {
436 Err(from_glib_full(error))
437 };
438 let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
439 Box_::from_raw(user_data as *mut _);
440 let callback: P = callback.into_inner();
441 callback(result);
442 }
443 let callback = mount_trampoline::<P>;
444 unsafe {
445 ffi::g_volume_mount(
446 self.as_ref().to_glib_none().0,
447 flags.into_glib(),
448 mount_operation.map(|p| p.as_ref()).to_glib_none().0,
449 cancellable.map(|p| p.as_ref()).to_glib_none().0,
450 Some(callback),
451 Box_::into_raw(user_data) as *mut _,
452 );
453 }
454 }
455
456 fn mount_future(
457 &self,
458 flags: MountMountFlags,
459 mount_operation: Option<&(impl IsA<MountOperation> + Clone + 'static)>,
460 ) -> Pin<Box_<dyn std::future::Future<Output = Result<(), glib::Error>> + 'static>> {
461 let mount_operation = mount_operation.map(ToOwned::to_owned);
462 Box_::pin(crate::GioFuture::new(
463 self,
464 move |obj, cancellable, send| {
465 obj.mount(
466 flags,
467 mount_operation.as_ref().map(::std::borrow::Borrow::borrow),
468 Some(cancellable),
469 move |res| {
470 send.resolve(res);
471 },
472 );
473 },
474 ))
475 }
476
477 /// Returns whether the volume should be automatically mounted.
478 ///
479 /// # Returns
480 ///
481 /// [`true`] if the volume should be automatically mounted
482 #[doc(alias = "g_volume_should_automount")]
483 fn should_automount(&self) -> bool {
484 unsafe {
485 from_glib(ffi::g_volume_should_automount(
486 self.as_ref().to_glib_none().0,
487 ))
488 }
489 }
490
491 /// Emitted when the volume has been changed.
492 #[doc(alias = "changed")]
493 fn connect_changed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
494 unsafe extern "C" fn changed_trampoline<P: IsA<Volume>, F: Fn(&P) + 'static>(
495 this: *mut ffi::GVolume,
496 f: glib::ffi::gpointer,
497 ) {
498 let f: &F = &*(f as *const F);
499 f(Volume::from_glib_borrow(this).unsafe_cast_ref())
500 }
501 unsafe {
502 let f: Box_<F> = Box_::new(f);
503 connect_raw(
504 self.as_ptr() as *mut _,
505 b"changed\0".as_ptr() as *const _,
506 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
507 changed_trampoline::<Self, F> as *const (),
508 )),
509 Box_::into_raw(f),
510 )
511 }
512 }
513
514 /// This signal is emitted when the #GVolume have been removed. If
515 /// the recipient is holding references to the object they should
516 /// release them so the object can be finalized.
517 #[doc(alias = "removed")]
518 fn connect_removed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
519 unsafe extern "C" fn removed_trampoline<P: IsA<Volume>, F: Fn(&P) + 'static>(
520 this: *mut ffi::GVolume,
521 f: glib::ffi::gpointer,
522 ) {
523 let f: &F = &*(f as *const F);
524 f(Volume::from_glib_borrow(this).unsafe_cast_ref())
525 }
526 unsafe {
527 let f: Box_<F> = Box_::new(f);
528 connect_raw(
529 self.as_ptr() as *mut _,
530 b"removed\0".as_ptr() as *const _,
531 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
532 removed_trampoline::<Self, F> as *const (),
533 )),
534 Box_::into_raw(f),
535 )
536 }
537 }
538}
539
540impl<O: IsA<Volume>> VolumeExt for O {}