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 {}