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