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            let _ = ffi::g_volume_eject_with_operation_finish(
169                _source_object as *mut _,
170                res,
171                &mut error,
172            );
173            let result = if error.is_null() {
174                Ok(())
175            } else {
176                Err(from_glib_full(error))
177            };
178            let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
179                Box_::from_raw(user_data as *mut _);
180            let callback: P = callback.into_inner();
181            callback(result);
182        }
183        let callback = eject_with_operation_trampoline::<P>;
184        unsafe {
185            ffi::g_volume_eject_with_operation(
186                self.as_ref().to_glib_none().0,
187                flags.into_glib(),
188                mount_operation.map(|p| p.as_ref()).to_glib_none().0,
189                cancellable.map(|p| p.as_ref()).to_glib_none().0,
190                Some(callback),
191                Box_::into_raw(user_data) as *mut _,
192            );
193        }
194    }
195
196    fn eject_with_operation_future(
197        &self,
198        flags: MountUnmountFlags,
199        mount_operation: Option<&(impl IsA<MountOperation> + Clone + 'static)>,
200    ) -> Pin<Box_<dyn std::future::Future<Output = Result<(), glib::Error>> + 'static>> {
201        let mount_operation = mount_operation.map(ToOwned::to_owned);
202        Box_::pin(crate::GioFuture::new(
203            self,
204            move |obj, cancellable, send| {
205                obj.eject_with_operation(
206                    flags,
207                    mount_operation.as_ref().map(::std::borrow::Borrow::borrow),
208                    Some(cancellable),
209                    move |res| {
210                        send.resolve(res);
211                    },
212                );
213            },
214        ))
215    }
216
217    /// Gets the kinds of [identifiers](#volume-identifiers) that @self has.
218    /// Use g_volume_get_identifier() to obtain the identifiers themselves.
219    ///
220    /// # Returns
221    ///
222    /// a [`None`]-terminated array
223    ///   of strings containing kinds of identifiers. Use g_strfreev() to free.
224    #[doc(alias = "g_volume_enumerate_identifiers")]
225    fn enumerate_identifiers(&self) -> Vec<glib::GString> {
226        unsafe {
227            FromGlibPtrContainer::from_glib_full(ffi::g_volume_enumerate_identifiers(
228                self.as_ref().to_glib_none().0,
229            ))
230        }
231    }
232
233    /// Gets the activation root for a #GVolume if it is known ahead of
234    /// mount time. Returns [`None`] otherwise. If not [`None`] and if @self
235    /// is mounted, then the result of g_mount_get_root() on the
236    /// #GMount object obtained from g_volume_get_mount() will always
237    /// either be equal or a prefix of what this function returns. In
238    /// other words, in code
239    ///
240    ///
241    ///
242    /// **⚠️ The following code is in C ⚠️**
243    ///
244    /// ```C
245    ///   GMount *mount;
246    ///   GFile *mount_root
247    ///   GFile *volume_activation_root;
248    ///
249    ///   mount = g_volume_get_mount (volume); // mounted, so never NULL
250    ///   mount_root = g_mount_get_root (mount);
251    ///   volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
252    /// ```
253    /// then the expression
254    ///
255    ///
256    /// **⚠️ The following code is in C ⚠️**
257    ///
258    /// ```C
259    ///   (g_file_has_prefix (volume_activation_root, mount_root) ||
260    ///    g_file_equal (volume_activation_root, mount_root))
261    /// ```
262    /// will always be [`true`].
263    ///
264    /// Activation roots are typically used in #GVolumeMonitor
265    /// implementations to find the underlying mount to shadow, see
266    /// g_mount_is_shadowed() for more details.
267    ///
268    /// # Returns
269    ///
270    /// the activation root of @self
271    ///     or [`None`]. Use g_object_unref() to free.
272    #[doc(alias = "g_volume_get_activation_root")]
273    #[doc(alias = "get_activation_root")]
274    fn activation_root(&self) -> Option<File> {
275        unsafe {
276            from_glib_full(ffi::g_volume_get_activation_root(
277                self.as_ref().to_glib_none().0,
278            ))
279        }
280    }
281
282    /// Gets the drive for the @self.
283    ///
284    /// # Returns
285    ///
286    /// a #GDrive or [`None`] if @self is not
287    ///     associated with a drive. The returned object should be unreffed
288    ///     with g_object_unref() when no longer needed.
289    #[doc(alias = "g_volume_get_drive")]
290    #[doc(alias = "get_drive")]
291    fn drive(&self) -> Option<Drive> {
292        unsafe { from_glib_full(ffi::g_volume_get_drive(self.as_ref().to_glib_none().0)) }
293    }
294
295    /// Gets the icon for @self.
296    ///
297    /// # Returns
298    ///
299    /// a #GIcon.
300    ///     The returned object should be unreffed with g_object_unref()
301    ///     when no longer needed.
302    #[doc(alias = "g_volume_get_icon")]
303    #[doc(alias = "get_icon")]
304    fn icon(&self) -> Icon {
305        unsafe { from_glib_full(ffi::g_volume_get_icon(self.as_ref().to_glib_none().0)) }
306    }
307
308    /// Gets the identifier of the given kind for @self.
309    /// See the [introduction](#volume-identifiers) for more
310    /// information about volume identifiers.
311    /// ## `kind`
312    /// the kind of identifier to return
313    ///
314    /// # Returns
315    ///
316    /// a newly allocated string containing the
317    ///     requested identifier, or [`None`] if the #GVolume
318    ///     doesn't have this kind of identifier
319    #[doc(alias = "g_volume_get_identifier")]
320    #[doc(alias = "get_identifier")]
321    fn identifier(&self, kind: &str) -> Option<glib::GString> {
322        unsafe {
323            from_glib_full(ffi::g_volume_get_identifier(
324                self.as_ref().to_glib_none().0,
325                kind.to_glib_none().0,
326            ))
327        }
328    }
329
330    /// Gets the mount for the @self.
331    ///
332    /// # Returns
333    ///
334    /// a #GMount or [`None`] if @self isn't mounted.
335    ///     The returned object should be unreffed with g_object_unref()
336    ///     when no longer needed.
337    #[doc(alias = "g_volume_get_mount")]
338    fn get_mount(&self) -> Option<Mount> {
339        unsafe { from_glib_full(ffi::g_volume_get_mount(self.as_ref().to_glib_none().0)) }
340    }
341
342    /// Gets the name of @self.
343    ///
344    /// # Returns
345    ///
346    /// the name for the given @self. The returned string should
347    ///     be freed with g_free() when no longer needed.
348    #[doc(alias = "g_volume_get_name")]
349    #[doc(alias = "get_name")]
350    fn name(&self) -> glib::GString {
351        unsafe { from_glib_full(ffi::g_volume_get_name(self.as_ref().to_glib_none().0)) }
352    }
353
354    /// Gets the sort key for @self, if any.
355    ///
356    /// # Returns
357    ///
358    /// Sorting key for @self or [`None`] if no such key is available
359    #[doc(alias = "g_volume_get_sort_key")]
360    #[doc(alias = "get_sort_key")]
361    fn sort_key(&self) -> Option<glib::GString> {
362        unsafe { from_glib_none(ffi::g_volume_get_sort_key(self.as_ref().to_glib_none().0)) }
363    }
364
365    /// Gets the symbolic icon for @self.
366    ///
367    /// # Returns
368    ///
369    /// a #GIcon.
370    ///     The returned object should be unreffed with g_object_unref()
371    ///     when no longer needed.
372    #[doc(alias = "g_volume_get_symbolic_icon")]
373    #[doc(alias = "get_symbolic_icon")]
374    fn symbolic_icon(&self) -> Icon {
375        unsafe {
376            from_glib_full(ffi::g_volume_get_symbolic_icon(
377                self.as_ref().to_glib_none().0,
378            ))
379        }
380    }
381
382    /// Gets the UUID for the @self. The reference is typically based on
383    /// the file system UUID for the volume in question and should be
384    /// considered an opaque string. Returns [`None`] if there is no UUID
385    /// available.
386    ///
387    /// # Returns
388    ///
389    /// the UUID for @self or [`None`] if no UUID
390    ///     can be computed.
391    ///     The returned string should be freed with g_free()
392    ///     when no longer needed.
393    #[doc(alias = "g_volume_get_uuid")]
394    #[doc(alias = "get_uuid")]
395    fn uuid(&self) -> Option<glib::GString> {
396        unsafe { from_glib_full(ffi::g_volume_get_uuid(self.as_ref().to_glib_none().0)) }
397    }
398
399    /// Mounts a volume. This is an asynchronous operation, and is
400    /// finished by calling g_volume_mount_finish() with the @self
401    /// and #GAsyncResult returned in the @callback.
402    /// ## `flags`
403    /// flags affecting the operation
404    /// ## `mount_operation`
405    /// a #GMountOperation or [`None`] to avoid user interaction
406    /// ## `cancellable`
407    /// optional #GCancellable object, [`None`] to ignore
408    /// ## `callback`
409    /// a #GAsyncReadyCallback, or [`None`]
410    #[doc(alias = "g_volume_mount")]
411    fn mount<P: FnOnce(Result<(), glib::Error>) + 'static>(
412        &self,
413        flags: MountMountFlags,
414        mount_operation: Option<&impl IsA<MountOperation>>,
415        cancellable: Option<&impl IsA<Cancellable>>,
416        callback: P,
417    ) {
418        let main_context = glib::MainContext::ref_thread_default();
419        let is_main_context_owner = main_context.is_owner();
420        let has_acquired_main_context = (!is_main_context_owner)
421            .then(|| main_context.acquire().ok())
422            .flatten();
423        assert!(
424            is_main_context_owner || has_acquired_main_context.is_some(),
425            "Async operations only allowed if the thread is owning the MainContext"
426        );
427
428        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
429            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
430        unsafe extern "C" fn mount_trampoline<P: FnOnce(Result<(), glib::Error>) + 'static>(
431            _source_object: *mut glib::gobject_ffi::GObject,
432            res: *mut crate::ffi::GAsyncResult,
433            user_data: glib::ffi::gpointer,
434        ) {
435            let mut error = std::ptr::null_mut();
436            let _ = ffi::g_volume_mount_finish(_source_object as *mut _, res, &mut error);
437            let result = if error.is_null() {
438                Ok(())
439            } else {
440                Err(from_glib_full(error))
441            };
442            let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
443                Box_::from_raw(user_data as *mut _);
444            let callback: P = callback.into_inner();
445            callback(result);
446        }
447        let callback = mount_trampoline::<P>;
448        unsafe {
449            ffi::g_volume_mount(
450                self.as_ref().to_glib_none().0,
451                flags.into_glib(),
452                mount_operation.map(|p| p.as_ref()).to_glib_none().0,
453                cancellable.map(|p| p.as_ref()).to_glib_none().0,
454                Some(callback),
455                Box_::into_raw(user_data) as *mut _,
456            );
457        }
458    }
459
460    fn mount_future(
461        &self,
462        flags: MountMountFlags,
463        mount_operation: Option<&(impl IsA<MountOperation> + Clone + 'static)>,
464    ) -> Pin<Box_<dyn std::future::Future<Output = Result<(), glib::Error>> + 'static>> {
465        let mount_operation = mount_operation.map(ToOwned::to_owned);
466        Box_::pin(crate::GioFuture::new(
467            self,
468            move |obj, cancellable, send| {
469                obj.mount(
470                    flags,
471                    mount_operation.as_ref().map(::std::borrow::Borrow::borrow),
472                    Some(cancellable),
473                    move |res| {
474                        send.resolve(res);
475                    },
476                );
477            },
478        ))
479    }
480
481    /// Returns whether the volume should be automatically mounted.
482    ///
483    /// # Returns
484    ///
485    /// [`true`] if the volume should be automatically mounted
486    #[doc(alias = "g_volume_should_automount")]
487    fn should_automount(&self) -> bool {
488        unsafe {
489            from_glib(ffi::g_volume_should_automount(
490                self.as_ref().to_glib_none().0,
491            ))
492        }
493    }
494
495    /// Emitted when the volume has been changed.
496    #[doc(alias = "changed")]
497    fn connect_changed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
498        unsafe extern "C" fn changed_trampoline<P: IsA<Volume>, F: Fn(&P) + 'static>(
499            this: *mut ffi::GVolume,
500            f: glib::ffi::gpointer,
501        ) {
502            let f: &F = &*(f as *const F);
503            f(Volume::from_glib_borrow(this).unsafe_cast_ref())
504        }
505        unsafe {
506            let f: Box_<F> = Box_::new(f);
507            connect_raw(
508                self.as_ptr() as *mut _,
509                b"changed\0".as_ptr() as *const _,
510                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
511                    changed_trampoline::<Self, F> as *const (),
512                )),
513                Box_::into_raw(f),
514            )
515        }
516    }
517
518    /// This signal is emitted when the #GVolume have been removed. If
519    /// the recipient is holding references to the object they should
520    /// release them so the object can be finalized.
521    #[doc(alias = "removed")]
522    fn connect_removed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
523        unsafe extern "C" fn removed_trampoline<P: IsA<Volume>, F: Fn(&P) + 'static>(
524            this: *mut ffi::GVolume,
525            f: glib::ffi::gpointer,
526        ) {
527            let f: &F = &*(f as *const F);
528            f(Volume::from_glib_borrow(this).unsafe_cast_ref())
529        }
530        unsafe {
531            let f: Box_<F> = Box_::new(f);
532            connect_raw(
533                self.as_ptr() as *mut _,
534                b"removed\0".as_ptr() as *const _,
535                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
536                    removed_trampoline::<Self, F> as *const (),
537                )),
538                Box_::into_raw(f),
539            )
540        }
541    }
542}
543
544impl<O: IsA<Volume>> VolumeExt for O {}